3 osc, the Command Line Tool #

3.1 Installing and Configuring #

To work with Open Build Service, install the osc command line tool from your preferred openSUSE distributions or from the OBS project openSUSE:Tools. The tool runs on any modern Linux system and is available for different distributions, like CentOS, Debian, Fedora, SLE, openSUSE, to name a few.

For SUSE related systems, install it with the zypper command (replace DISTRI with your distribution):

root # zypper addrepo https://download.opensuse.org/repositories/openSUSE:/Tools/DISTRI/openSUSE:Tools.repo
root # zypper install osc

For other systems, use your preferred package manager.

As an alternative, use the AppImage file. An AppImage file is a packaged application and its dependencies which can run on many distributions. Download the file, save it in your ~/bin directory, and make the file executable.

3.2 Configuring osc #

Usually, the default configuration is appropriate in most cases. There are some special configuration option which might be helpful if you have special needs.

Some useful options in the ~/.oscrc file are described in the following list (all under the general section):

apiurl (string)

Used to access the Open Build Service (OBS) API server. This is needed if you work with different OBS server (for example, a public and a private one). If you have to distinguish different servers, you can also use the -A option. Usually, it is good practice to create an alias like this:

alias iosc="osc -A https://api.YOURSERVER"

You use iosc the same as with osc.

extra-pkgs (list)

Contains a space-separated list of package. These extra packages are installed when you build packages locally. Useful when you need an additional editor inside the build environment, for example vim.

build_repository (string)

Sets the default platform when omitted in osc build.

exclude_glob (list)

Contains a list of space separated file names to ignore. For example, *.bak to ignore all backup files.

checkout_no_colon (bool)

Separates projects and subprojects in directories and subdirectories instead of creating a single directory. For example, setting the option and checking out the home project will lead to a directory structure home/obsgeeko instead of the single directory home:obsgeeko.

use_keyring (bool)

Use the default keyring instead of saving the password in the OBS configuration file. For KDE the KWallet is used, for GNOME it is Seahorse.

cafile (string)

Provide set of trusted CA certificates for HTTPs requests. Expects CAs in a single file containing a bundle of CA certificates in PEM format. More details can be found in OpenSSL documentation.

capath (string)

Provide set of trusted CA certificates for HTTPs requests. Expects a directory containing CA certificates in PEM format. More details can be found in OpenSSL documentation.

3.3 Usage #

3.3.1 Getting Help #

To get a general help about this command, use osc --help. For help of specific subcommands, use osc help SUBCOMMAND.

Most commands can be called by a long name (like status) or by one or more aliases (as st).

3.3.2 Using `osc` for the First Time #

When you use the osc command for the first time, the command will ask you for your credentials of your OBS instance. The credentials are stored in the configuration file ~/.oscrc.

By default, the password is stored as plain text. In terms of security, that is not ideal. To avoid the issue:

Use a Password Manager. Set the option use_keyring to 1 after you have created a configuration file for the first time. Remove your credentials sections from your configuration file. The next time osc asks for your username and password, it will store it in the password manager instead of the configuration file.
Obfuscating the Password. Set plaintext_passwd to 0. This is not a security feature, but it obfuscates the password in the configuration file.

If you prefer your current password manager, set the option use_keyring to 1 after you have authenticated it.

3.3.3 Overview of Brief Examples #

The osc command is similar to git: The main command osc has several subcommands. It serves as client and it is used to build packages locally, submit files to a remote OBS instance, edit metadata, or query build results.

List Existing Content on the Server

osc ls                    #list projects
osc ls Apache             #list packages in a project
osc ls Apache flood       #list files of package of a project

osc ls shows you a list of projects on OBS. Which OBS instance it shows depends on the option apiurl in the configuration file. By default, the openSUSE Build Server is used. If you need another server, use the -A option as shown in Section 3.2, “Configuring osc”.

Checkout Content

osc co Apache                   # entire project
osc co Apache flood             # a package
osc co Apache flood flood.spec  # single file

Update a Working Directory

osc up
osc up [directory]
osc up *            # from within a project dir, update all packages
osc up              # from within a project dir, update all packages AND check out all newly added packages

Upload Changed Content

osc ci                          # current dir
osc ci [file1] [file2]          # only specific files
osc ci [dir1] [dir2] ...        # multiple packages
osc ci -m "updated foobar"      # specify a commit message

Check the Commit Log

osc log

Show the status (which files have been changed locally)

osc st
osc st [directory]

If an update cannot be merged automatically, a file is in 'C' (conflict) state, and conflicts are marked with special lines. After manually resolving the problem, use osc resolved FILE.

Mark files to be Added or Removed on the Next Checkin

osc add foo
osc rm foo

Add all New Files in Local Copy and Removes all Disappeared files

osc addremove

Generate a diff to view the changes

osc diff [file]

Show the Build Results of the Package

osc results
osc results [platform]

Show the Log File of a Package

(you need to be inside a package directory)

osc buildlog [platform] [arch]

Show the URLs of .repo Files which are Packages Sources for Package Managers

osc repourls [dir]

Trigger a Package Rebuild for all Repositories/Architectures of a Package

osc rebuildpac [dir]

Build a Package on Your Computer

osc build [platform] [arch] [specfile] [--clean|--noinit|...]

Show Configured Platforms/Build Targets

osc platforms [project]

Show Possible Build Targets for Your Project

osc repos

Show Metadata

osc meta prj [project]
osc meta pkg [project] [package]
osc meta user [username]
osc meta prjconf [project]

Edit Meta Information

Create new package/project if it does not exist. It will open an editor with the raw XML metadata. To avoid need to edit XML, you can use the web UI instead.

osc meta prj -e [project]
osc meta pkg -e [project] [package]
osc meta prjconf -e [project]

(The project configuration may well be empty. It is needed in special cases only.)

Update Package Metadata on OBS with Metadata Taken from Spec File

osc updatepacmetafromspec [dir]