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


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!

Starting from scratch

  • mkdir package-name

  • cd package-name

  • git init

  • git-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

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


To do the above steps all at once, simply use

  • git-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 git-import-dsc in the order of their revision numbers or use git-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 just "upstream"), 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 git-dch to generate debian/changelog automatically from your previous git commit messages.

Creating a new version / revision:

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

For a snapshot build:

  • git dch -a -S

For a release build:

  • git dch -a -R

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

Working with patches

Building the binary package(s)


  • git-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 remote update

  • 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):

  • git-import-orig --uscan

Using a tarball file:

  • git-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
cleaner = fakeroot debian/rules clean
builder = /usr/bin/git-pbuilder

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 git-buildpackage like either

  • DIST=sid ARCH=amd64 git-buildpackage


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

See also