Debianization with git-buildpackage

Updated 2018-04-03: git-buildpackage's commands have changed, so this article had to be fixed; I took the opportunity to improve a few things as well.

After building some useful piece of software, one has to decide how to best deploy it. In UNIX, the standard way to do that is by publishing the source code in .tar.gz format and requiring users to compile it.

In Debian there is an alternative: using a .deb package. With a .deb package, a single dpkg -i ${PACKAGE}.deb installs the software.

This article explains how to create and support a .deb package for a simple software maintained in git, by tracking the packaging scheme in a specific branch on the same repository.

Prerequisites

In order to ease the packaging and keep our package warning-free, it should have in its main repository:

  • An AUTHORS file with copyright information.
  • A manual: ${PACKAGE}.1 or similar.
  • A COPYING file with GPL information or some other license.
  • An appropriate build file for the package. For C/C++ programs, I recommend using cmake; for python, setup.py, etc.

These items are not debian-specific and are useful for everyone.

Initial packaging setup

The first step is creating the ${PACKAGE}_${VERSION}.orig.tar.gz file. You can use git itself for that, by running the following commands in the repository:

PREFIX=${PACKAGE}_${VERSION}
git archive --format=tar --prefix=$PREFIX/ $VERSION | gzip -c > ../$PREFIX.orig.tar.gz

You can check the contents of the archive with tar. If there are extraneous files in the archive, you can configure git-archove to exclude them by creating a .gitattributes file; for example:

.gitignore      export-ignore
.gitattributes  export-ignore
.travis.yml     export-ignore

The next step is to create the debian branches in the git repository: on the debian-upstream branch, we store the upstream source, while the debian-debian branch holds the debian package data. This separation provides a cleaner revision history by separating the changes that affect the software from the changes in the packaging.

In order to create these branches, we issue the following commands in the git repository:

git checkout --orphan debian-upstream
git rm --cached -r .
git clean -xfd
git commit --allow-empty -m 'Start of debian branches.'
git checkout -b debian-debian

That creates both branches as orphans, pointing to an empty root commit.

We now use the ../${PACKAGE}_${VERSION}.orig.tar.gz file to create the initial debian directory in the debian-debian branch:

dh_make -s -p ${PACKAGE}_${VERSION}

We can now customize the standard debian directory created. You must edit the following files: changelog, control, copyright and rules. Besides those, the compat file must be present; the other files can be safely removed.

After changing the files that dh_make created, you should create a debian/gbp.conf with the following contents:

[DEFAULT]
upstream-branch=debian-upstream
debian-branch=debian-debian

We can now commit the debian directory in the debian-debian branch.

Importing the sources

In the debian-debian branch:

gbp import-orig --no-interactive ../${PACKAGE}_${VERSION}.orig.tar.gz

That imports the original sources to the debian-upstream branch, and merge it into the debian-debian branch.

Creating the package

To create the debian package:

gbp buildpackage -us -uc --git-tag

Importing further versions

Create the new ../${PACKAGE}_${VERSION}/.orig.tar.gz and then:

gbp import-orig --no-interactive ../${PACKAGE}_${VERSION}.orig.tar.gz

Edit the debian/changelog file (we can use dch -i -v $VERSION for that), and create a new package:

gbp buildpackage -us -uc --git-tag

Yes, it's that easy.

Final remarks

After an initial expensive setup, package creation of further versions is mostly painless, which is the whole point of git-buildpackage and friends.

Besides this article, we should check the debian dir of some already packaged software for reference. We can look at the execpermfix repository at github when first trying to package something.

Further information: