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

Preparations

Install the necessary software with

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

Note

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 user.name <name>

  • git config --global user.email <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

This is very important! See file:///usr/share/doc/git-buildpackage/manual-html/gbp.intro.html#GBP.REPOSITORY

Tags

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
[DEFAULT]
pristine-tar = True
color = True
EOF

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>

Note

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.
Note
 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>

Note

To do the above steps all at once, simply use

  • gbp clone <URL>

…work on Debian package…

Working

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.

Note
 For further information see file:///usr/share/doc/git-buildpackage/manual-html/man.gbp.dch.html

Working with patches

See

and decide for yourself.

Building the binary package(s)

Build:

  • 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

Note
 For further information see file:///usr/share/doc/git-buildpackage/manual-html/man.gbp.buildpackage.html

Creating a remote repository

If you cloned an existing repository you can skip this.

gitolite

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

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

  • git push --tags

git+ssh

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
[DEFAULT]
builder = git-pbuilder
cleaner = fakeroot debian/rules clean
pristine-tar = True
color = True
EOF

See also file:///usr/share/doc/git-buildpackage/manual-html/gbp.special.html#GBP.SPECIAL.PBUILDER

Set up chroot

Create a new chroot:

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

Note
 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

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

or

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

See also