This Howto is only useful to you if you’re running a Debian/Ubuntu based system and know how packaging for these distributions works.


Install the necessary software with

  • apt-get install cowbuilder debhelper devscripts dh-make fakeroot git-buildpackage pristine-tar


You can then find the upstream documentation in

Make sure to set your name and email address in your ~/.gitconfig file via:

  • git config --global <name>

  • git config --global <email>

You can set these per-repository as well, once you have a repository, by running the command within that repository and omitting the --global flag.

Repository Layout


Tags are very important for all this to work, so be careful to create them and to push them!

Configure git-buildpackage

cat << EOF > ~/.gbp.conf
pristine-tar = True
color = True

Starting from scratch

  • mkdir package-name

  • cd package-name

  • git init

  • gbp import-orig </path/to/*orig.tar.gz>

  • dh-make

…work on Debian package…

Starting from an existing Debian package

  • mkdir package-name

  • cd package-name

  • git init

  • gbp import-dsc </path/to/*.dsc>


To do the above steps all at once, simply use

  • gbp import-dsc <*.dsc>

A new git repository in a folder with the name of the package will be created automatically.

If you want to import further source package versions/revisions you can either run gbp import-dsc in the order of their revision numbers or use gbp import-dscs.

…work on Debian package…

Starting from an existing repository

Clone the repository

  • git clone <URL>

See which remote branches exist

  • git branch -r

Check out all needed branches (usually "upstream" and "pristine-tar"), remote tracking will be set up automatically

  • git checkout <BRANCH>


To do the above steps all at once, simply use

  • gbp clone <URL>

…work on Debian package…


After making your changes in debian/*, do

  • git add debian/<file>

  • git commit

Commit in small steps and write usefull commit messages.

Maganging the changelog

You can use gbp dch to generate debian/changelog automatically from your previous git commit messages.

Creating a new version / revision:

  • gbp dch -a -N <new-version>

For a snapshot build:

  • gbp dch -a -S

For a release build:

  • gbp dch -a -R

Finally the new changelog must be comitted before doing the release build.

Working with patches

Building the binary package(s)


  • gbp buildpackage

    • use --git-ignore-new for testing with uncomitted changes (e.g. a snapshot)

    • use -uc -us if you don’t want to sign your build

    • use --git-tag when building a release

Clean up:

  • fakeroot debian/rules clean

Creating a remote repository

If you cloned an existing repository you can skip this.


  • git push -u --all git@SERVER:FOLDER/NAME.git

  • git remote add origin git@SERVER:FOLDER/NAME.git

  • git push --tags

Pushing your changes

All you have to do is:

  • git push --all

  • git push --tags

Pulling your co-maintainer’s changes

Let’s hope your co-maintainer pushed all his commits and tags!

Now, instead of pulling each branch one by one, pull all branches at once by simply calling

  • gbp-pull

Upgrading to a new upstream version

Using a debian/watch file (recommended):

  • gbp import-orig --uscan

Using a tarball file:

  • gbp import-orig </path/to/new*orig.tar.gz> -u <new upstream version>

…work on Debian package…

Using pbuilder/cowbuilder

If you want to build a package for different architectures/distributions/releases or simply build it in a clean buildd-like chroot so you don’t have to install all the build dependencies in your own system - pbuilder/cowbuilder is your friend!

This is purely optional but recommended.

Unless you’re familiar with user-mode-linux you need root access for this.

Configure git-buildpackage

cat << EOF > ~/.gbp.conf
builder = git-pbuilder
cleaner = fakeroot debian/rules clean
pristine-tar = True
color = True

Set up chroot

Create a new chroot:

  • <DIST=distribution> <ARCH=architecture> git-pbuilder create

Ubuntu users will have to add --components "main universe" for the above to succeed, because the required package cowdancer is not in main but in universe.

Update an existing chroot:

  • <DIST=distribution> <ARCH=architecture> git-pbuilder update

Login to a chroot:

  • <DIST=distribution> <ARCH=architecture> git-pbuilder login --save-after-login


Continue working like before. If you used the DIST or ARCH field when creating the chroot, you need to specify it from now on by calling gbp buildpackage like either

  • DIST=sid ARCH=amd64 gbp buildpackage


  • gbp buildpackage --git-pbuilder --git-dist=DIST --git-arch=ARCH

See also