Scroll to navigation

BS-UPDATE(1) General Commands Manual BS-UPDATE(1)


bs-updateUpdate packages in a Build Service from upstream sources.


bs-update -h

bs-update [-A BSAPI] [-B BUILDARGS]... [-C] [-P PROJECT] [-b] [-d URL] [-m COMMITMSG] [-n] [-p PACKAGE] [-s SPECFILE]... [-t TARBALL] TAG [VERSION]


bs-update makes it easier to keep packages in a Build Service up-to-date with respect to their upstream sources.

Given a Build Service API URL, project and package names, a tarball URL, and a version number, bs-update will

  1. figure out the target version from operands and the optional (),
  2. check out the package from the Build Service into a temporary directory,
  3. fetch the tarball from the URL,
  4. update the tarball source with the downloaded tarball, after possible modification by the optional (),
  5. update package descriptions (specfile, PKGBUILD, etc) from their templates extracted from the tarball or provided by the optional (),
  6. (optionally) build the package locally,
  7. (optionally) commit the changes.

bs-update aborts on failure in any step.


All options beside -h have their configuration variable counterparts. See the FILES section for more information.

Display a usage description.
Use Build Service at BSAPI (URL or alias). Passed to osc(1).
Use BUILDARGS (after field splitting) as arguments to osc build (see -b). May be given more than once, each instance yields a separate osc build.
Skip the osc commit step.
Update Build Service package of PROJECT.
Run osc build before osc commit. If the build fails, bs-update aborts. See $bsu_osc_build.
Retrieve the source tarball from URL. If URL is “.”, bs-update uses git-archive(1) or hg-archive(1) in PWD as appropriate. Otherwise, bs-update uses wget(1).
Use COMMITMSG for the commit in Build Service. Defaults to “Update to version VERSION”.
Report values derived from configuration files and command line arguments, then exit.
Update Build Service PACKAGE.
Use from TARBALL, commit SPECFILE into the Build Service. All occurrences of __VERSION__ in SPECFILE are replaced with VERSION. SPECFILE can be a real .spec file (RPM) or a PKGBUILD file (ArchLinux). May be given more than once, all files are processed.
Use TARBALL for the name of the downloaded file.


Update the package from TAG. Substituted for $bsu_tag in values derived from command line options and configuration files.
Update the package to VERSION. If VERSION is not given, it is generated using () if it exists, otherwise from TAG by stripping the initial “v” if any. Substituted for $bsu_version in values derived from command line options and configuration files.


bs-update allows tailoring the update process through shell functions, see the FILES section for more information.


bs-update itself does not use any environment variables. It is, however, implemented in terms of third-party commands which use them. This means bs-update may be influenced by environment variables used by git(1), hg(1), osc(1), tar(1), wget(1), zsh(1), possibly others.


bs-update recognizes two optional configuration files, .bs-update-hooks and .bs-update. They are read, in order, from the current directory before command line arguments are processed. Either file may define any of hooks and/or configuration variables, last definition wins.

Each configuration variable has a corresponding command line option. Command line options and arguments take precedence over configuration files. Resulting values are subject to shell parameter expansion.

Syntactically, the configuration files are limited shell scripts recognizing two kinds of statements: parameter assignments, and function definitions.

Shell Functions (Hooks)

If this function exists, it is responsible for providing a $ file for each $s in $bsu_specfiles. bs-update will invoke it with arguments consisting of $bsu_version, $bsu_tag, $bsu_tarball and $bsu_specfiles.
The tarball may need finalization before it is checked into the Build Service, eg. autoconf, git submodules or npm. If this function exists it is executed in the root of the checked out package, with the tarball name in the first argument.
If the VERSION argument is not given and this function exists it is executed with $1 set to the value of the TAG argument, and its output is used as the final version string.


bsu_bs_apiurl (-A)
bsu_bs_commit (-C)
bsu_bs_commitmsg (-m)
bsu_bs_package (-p)
bsu_bs_project (-P)
bsu_dloadurl (-d)
bsu_dryrun (-n)
bsu_specfiles (-s)
bsu_tarball (-t)
bsu_test_build (-b)
bsu_osc_build (-B)
Array of strings where each item is used (after field splitting) as arguments to osc build (see -b).


Interactive Use by Upstream Maintainer

This is a real-world example showing common .bs-update setup and the use of bs-update to test changes in the package and finally produce a new package version. It assumes the user maintains both the upstream software and its package in the Build Service.

We need a working copy to hack on:

git clone
cd bs-update

Since we're going to use bs-update repeatedly, it makes sense to employ a configuration file, .bs-update. Everything can still be overridden using options on the command line:

cat > .bs-update
  'ArchLinux x86_64 PKGBUILD'
  'SLE_12 x86_64 $pkg.spec'
  'openSUSE_Tumbleweed x86_64 $pkg.spec'

Commit some changes:

make check
git commit

Build the package locally, using the currently checked out revision. Does not commit into the Build Service:

bs-update -Cbd . HEAD

If it was ok we can tag it and publish the tag:

git tag -a v42.69
git push origin master v42.69

Commit the new release into the Build Service:

bs-update v42.69

Snapshot-generating Cronjob

This example demonstrates using bsu_tarball_hook() to generate snapshot tarballs of a Git branch. A new version of the package is created, based on a tarball of the upstream master branch.

mkdir /snapshots

cat > /snapshots/.bs-update-hooks <<'EOF'
  set -e
  local tarball=./${1?}
  local dir=${tarball%.tar.gz}
  mkdir $dir
  tar -xzf $tarball --strip-components=1 -C $dir
  tar -czf $tarball -- ${dir#./}
  rm -rf $dir

cat > /etc/cron.weekly/mk-snapshot <<'EOF'
set -eu
ts=$(date +%Y%m%d%H%M%S)
cd /snapshots
bs-update \
  -P home:roman-neuhauser \
  -p bs-update-snapshot \
  -d \
  -t bs-update-$ts.tar.gz \
  master $ts

chmod a+x /etc/cron.weekly/mk-snapshot


bs-update exits with 0 on success, and with >0 otherwise.


git(1), the openSUSE Build Service ⟨⟩, and its wiki ⟨⟩.


bs-update and this manual page are written by Roman Neuhauser <>.



No doubt plentiful. Please report them at

July 16, 2012 Linux 5.14.21-150500.55.52-default