NAME
    bs-update — Update packages in a Build Service from upstream
                sources.

SYNOPSIS
    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]

DESCRIPTION
    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
         bsu_version_hook,
    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 bsu_tarball_hook,
    5.   update package descriptions (specfile, PKGBUILD, etc) from
         their templates extracted from the tarball or provided by
         the optional bsu_specfile_hook,
    6.   (optionally) build the package locally,
    7.   (optionally) commit the changes.

    bs-update aborts on failure in any step.

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

    -h  Display a usage description.

    -A BSAPI
        Use Build Service at BSAPI (URL or alias).  Passed to osc(1).

    -B BUILDARGS
        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.

    -C  Skip the osc commit step.

    -P PROJECT
        Update Build Service package of PROJECT.

    -b  Run osc build before osc commit.  If the build fails,
        bs-update aborts.  See $bsu_osc_build.

    -d URL
        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).

    -m COMMITMSG
        Use COMMITMSG for the commit in Build Service.  Defaults to
        "Update to version VERSION".

    -n  Report values derived from configuration files and command line
        arguments, then exit.

    -p PACKAGE
        Update Build Service PACKAGE.

    -s SPECFILE
        Use SPECFILE.in 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.

    -t TARBALL
        Use TARBALL for the name of the downloaded file.

Operands
    TAG
        Update the package from TAG.
        Substituted for $bsu_tag in values derived from command line
        options and configuration files.

    VERSION
        Update the package to VERSION.  If VERSION is not given, it
        is generated using bsu_version_hook() 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.

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

ENVIRONMENT
    bs-update itself does not use any environment variables.  It is,
    however, implemented in terms of third-party commands which do
    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.

FILES
    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)
    bsu_specfile_hook()
      If this function exists, it is responsible for providing a $s.in
      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.

    bsu_tarball_hook()
      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.

    bsu_version_hook()
      If the VERSION argument is not given and this function exists it
      is executed with the TAG argument, and its output is used as the
      final version string.

  Variables
    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).


EXAMPLES
  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 git@github.com:roman-neuhauser/bs-update.git
      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
      usr=roman-neuhauser
      pkg=bs-update
      bsu_bs_apiurl=https://api.opensuse.org
      bsu_bs_package='$pkg'
      bsu_bs_project='home:$usr'
      bsu_dloadurl='https://github.com/$usr/$pkg/tarball/$bsu_tag'
      bsu_osc_build=(
        'ArchLinux x86_64 PKGBUILD'
        'SLE_12 x86_64 $pkg.spec'
        'openSUSE_Tumbleweed x86_64 $pkg.spec'
      )
      ^D

    Commit some changes:

      vim bs-update.in
      make check
      git commit bs-update.in

    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'
      bsu_tarball_hook()
      (
        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
      )
      EOF

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

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

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

SEE ALSO
    git(1), the openSUSE Build Service ⟨https://build.opensuse.org/⟩,
    and its wiki ⟨http://en.opensuse.org/Portal:Build_Service⟩.

AUTHORS
    bs-update and this manual page are written by ⟨neuhauser@sigpipe.cz⟩.

    See ⟨https://github.com/roman-neuhauser/bs-update/⟩.

BUGS
    No doubt plentiful.  Please report them at
    ⟨https://github.com/roman-neuhauser/bs-update/issues⟩.