Working with Patches

Basic Workflow
Importing a new upstream version
Adding your first patch
Team maintenance

gbp pq can be used to manage patches that modify the upstream source inside debian/patches/. This is mostly intended for 3.0 (quilt) format source packages.

The basic idea is that patches are imported from you debian-branch to a patch-queue branch with one patch file in debian/patches/ becoming one commit on the the patch-queue branch. The created branch will be named after the branch you imported from with patch-queue/ prepended. So if you do your Debian™ packaging on debian/sid and do a

    gbp pq import

then the newly created branch will be called patch-queue/debian/sid.

On the patch-queue branch you can work on the commits using familiar Git™ commands (rebase, commit --amend, etc). When done, gbp pq will be used to turn the commits on the patch-queue branch into patch in debian/patches/ files again.

This workflow facilitates e.g. the cherry-picking of patches for stable releases, the forward-porting of patches to new upstream versions by using git rebase on the patch-queue branch (patches already applied upstream are detected automatically) as well as the reordering, dropping and renaming of patches without having to resort to quilt. The generated patches in debian/patches/ have all the necessary information to forward them upstream since they use a format similar to git-format-patch.

The main drawback of this workflow is the lack of history on the patch-queue branch since it is frequently droppend and recreated. But there is full history on the your debian-branch, of course.

Basic Workflow

This example assumes you're working on a source 3.0 (quilt) format package with patches in debian/patches parseable by git-quiltimport(1). The git branch currently checked out is named debian/sid.

The debian-branch we start from.

Let's first create the patch-queue branch and import the contents of debian/patches onto it using gbp pq

  cd REPO
  gbp pq import

This will generate output like:

    gbp:info: Trying to apply patches at 'aaa1011bfd5aa74fea43620aae94709de05f80be'
    gbp:info: 18 patches listed in 'debian/patches/series' imported on 'patch-queue/debian/sid'

What happened is that gbp pq imported each patch file and switched you to the newly created patch-queue branch (patch-queue/debian/sid) automatically.

The patch-queue branch with patches from debian/patches applied.

Now you can work on the patch-queue branch (add, remove, rebase, test) to get your patches into shape:

  • To add what will later become a patch in debian/patches/ simply make a commit. The first line of the commit message will become the patch name later. The following lines include the details of what the patch does.

  • To remove or edit commits use git rebase -i . The git documentation explains how to work with git-rebase.

Once satisfied with the commits let's regenerate the patches in debian/patches/ using gbp pq. This will switch you back to the branch debian/sid and regenerate the patches using a method similar to git-format-patch:

  gbp pq export

You can now commit the result by using:

  git add debian/patches
  git commit

If you don't want to commit the result by hand each time you can also pass --commit to the gbp export command above.

Next you can update debian/changelog (e.g. by running "gbp dch -S -a") and build the package as usual.