Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
User Guide › Setup › osc, the Command Line Tool
ContentsContents
User Guide
  1. About this Guide
  2. I First Steps
    1. 1 Beginnerʼs Guide
  3. II Concepts
    1. 2 Supported Build Recipes and Package Formats
  4. III Setup
    1. 3 osc, the Command Line Tool
    2. 4 Project Configuration
  5. IV Usage
    1. 5 Basic OBS Workflow
    2. 6 Local Building
    3. 7 Using Source Services
    4. 8 SCM/CI Workflow Integration
    5. 9 Staging Workflow
    6. 10 Notifications
  6. V Best Practices
    1. 11 Using the OBS Web UI
    2. 12 Basic Concepts and Work Styles
    3. 13 How to integrate external SCM sources
    4. 14 Publishing Upstream Binaries
    5. 15 Bootstrapping
    6. 16 osc Example Commands
    7. 17 Advanced Project Setups
    8. 18 Building Kernel Modules
    9. 19 Common Questions and Solutions
  7. VI Reference
    1. 20 OBS Architecture
    2. 21 OBS Concepts
    3. 22 Build Process
    4. 23 Build Containers
    5. 24 Source Management
    6. 25 SCM Bridge [EXPERIMENTAL]
    7. 26 Supported Formats
    8. 27 Request And Review System
    9. 28 Image Templates
    10. 29 Multiple Build Description File Handling
    11. 30 Maintenance Support
    12. 31 Binary Package Tracking
    13. 32 Administration
    14. 33 Scheduling and Dispatching
    15. 34 Build Job Constraints
    16. 35 Building Preinstall Images
    17. 36 Authorization
    18. 37 Quality Assurance(QA) Hooks
    19. 38 openSUSE Factory
  8. Glossary
  9. A GNU Licenses
Navigation←→
User Guide › Setup › osc, the Command Line Tool
Top
←→

3 osc, the Command Line Tool

Abstract

3.1 Installing and Configuring
3.2 Configuring osc
3.3 Usage

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.

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]
→Chapter 4 Project Configuration←Part III Setup
Print this page

© 2023 SUSE