# 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:

      &gitcmd; 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
      &gitcmd; tag 10.4

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

      &gitcmd; checkout dfsg_clean
      &gitcmd; 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
      &gitcmd; commit -a -m "Make source dfsg clean"
      &gitcmd; tag 10.4.dfsg
      &gitcmd; checkout master
      &gitcmd; pull . dfsg_clean

## Importing NMUs

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

      &gitcmd; branch nmu master

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

      &gitcmd; 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 apt:package
      cd package
      &gitcmd; 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

      &gitcmd; commit -a
      &gitcmd; 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 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.

## Sloppy tarball creation

By default &gbp-buildpackage; uses `debian/changelog` to detect the upstream version and build the corrsponding tarball either via &pristine-tar; or by using `git archive` directly. This ensures that the tarball matches what's in the Debian archive already.

But there might be cases where you don't want to follow these packaging practice and create a fresh dirty tarball that contains additional changes. Such tarballs are not suitable for upload into the archive but might be helpful in local testing.

Especially when getting started and when you first want to get a package built and dive into &gbp-dch;, &git-pbuilder; and the 3.0 (quilt) format later to find out what exactly

    dpkg-source: info: local changes detected, the modified files are:
     hello-debhelper/configure
    dpkg-source: error: aborting due to unexpected upstream changes, see /tmp/hello-debhelper_2.8-1.diff.har2Xx
    dpkg-source: info: you can integrate the local changes with dpkg-source --commit

means.

For that you can force &gbp-buildpackage; to create a tarball from the debian-branch dropping the `debian/` directory. This will give you a tarball that is very close to your current working copy except for the packaging.

      &gbp-buildpackage --git-ignore-new --git-force-create --git-upstream-tree=SLOPPY --git-no-pristine-tar

The important part is the SLOPPY above. The other options are there to prevent &gbp-buildpackage; from using &pristine-tar;, to force the creation of a new tarball and to not abort if you have changes in your current working copy. If you're still getting an error about unexpected upstream changes make sure you have no uncomitted changes in you workig copy (changes in the `debian/` are o.k.) and no files that are ignored by git via `.gitignore`. A `git clean -dfx` can help here.

Please don't use this tarball to upload to the Debian archive since changes outside `debian/` need to be represented by patches in `debian/patches`. See the `dpkg-source` manpage for details.