# Special use cases

# Handling non-DFSG clean upstream sources

If you have to handle non-DFSG clean upstream sources, you can use a different branch which you have to create once:

      git branch dfsg_clean upstream

This creates the dfsg_clean branch from the tip of a branch called upstream. Then, when importing a new upstream version, you import the new version on the `upstream-branch` (by default named upstream) as usual and just don't merge to the debian-branch (by default named master):

      gbp import-orig --no-merge /path/to/nondfsg-clean-package_10.4.orig.tar.gz
      git tag 10.4

After the import, you can switch to the dfsg_clean branch and get the newly imported changes from the upstream branch:

      git checkout dfsg_clean
      git pull . upstream

Now make this checkout dfsg clean (preferably by a cleanup script), commit your changes and merge to your `debian-branch`:

      cleanup-script.sh
      git commit -a -m "Make source dfsg clean"
      git tag 10.4.dfsg
      git checkout master
      git pull . dfsg_clean

# Importing NMUs

First, create a branch that holds the NMUs from the tip of your `debian-branch` (default is master) once:

      git branch nmu master

To import an NMU, change into the git repository and use gbp import-dsc:

      git checkout master
      gbp import-dsc --debian-branch=nmu /path/to/package_1.0-1nmu0.dsc

This will import the NMU onto the branched named nmu instead of the default `master`. This method can also be used to import "old" releases into the Git repository when migrating to Git from another VCS.

# Building with Cowbuilder

Cowbuilder is nice tool to build Debian packages in a defined environment. It makes sure all build-dependencies are specified correctly by building the package in a clean chroot. As its cousin Pbuilder it can be extended via hooks to (e.g. run autopkg tests) but doesn't need a tarball unpacked but uses copy on write tree to speed up the build.

Since Cowbuilder uses different command line arguments than Debuild and Dpkg-buildpackage, we can't simply pass the options to run it on the command line. To simplifiy the integration we use a separate helper named git-pbuilder. gbp has it's own command line option for this:

      gbp buildpackage --git-pbuilder

This will set the build command to run git-pbuilder (which invokes Cowbuilder by default) and the clean command to /bin/true. It also activates the parsing of several git-pbuilder related options like `--git-dist`, `--git-arch` and `--git-pbuilder-options`.

We can make git-pbuilder usage the default by adding it to `~/.gbp.conf`:

    cat <<EOF > ~/.gbp.conf
    [DEFAULT]
    # We invoke cowbuilder via git-pbuilder. Arguments passed to gbp buildpackage
    # will be passed to dpkg-buildpackage in the chroot
    pbuilder = True
    EOF

git-pbuilder defaults to building a package for the `sid` distribution. If you want to build for another distribution, pass this in the `--git-dist` option:

      gbp buildpackage --git-pbuilder --git-dist=jessie

If you want to use debuild again (without modifying `~/.gbp.conf`), you can use:

      gbp buildpackage --git-no-pbuilder

In order for all of the above to work you have to create a base chroot first using git-pbuilder

      git-pbuilder create

This can later be updated using

      git-pbuilder update

# Working on random packages

Whenever you need to work on an arbitrary Debian package, you can check it right into Git with one command:

      gbp import-dsc --download package
      cd package
      git branch debian

This uses apt-get to download the source package, puts the orig tarball on the `upstream-branch` and the Debian changes on the `debian-branch` (by default master). The second command creates a branch called debian. Now you can easily modify the package, revert changes you made, create other branches for testing, see what changes you made, etc. When finished, just do

      git commit -a
      git diff debian --

to get a nice patch that can be submitted to the Debian BTS. You can also fetch the source package from a URL:

      gbp import-dsc --download http://mentors.debian.net/debian/pool/main/i/ipsec-tools/ipsec-tools_0.7.3-9.dsc

The import works incrementally; you can import new versions on top of already imported ones for e.g. easy review of changes.