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

Also, beware that gbp pq currently has incomplete support for DEP3 headers. Initially, parsing with git-mailinfo(1) is attempted, which supports only the From and Subject fields. If neither of these are present, gbp pq will attempt to convert the patch from DEP3 format into a git-mailinfo(1) compatible format. This involves first loading From using the Author field and Subject using the first line of the Description field. Then, any additional fields (such as Origin and Forwarded), and the remainder of the Description (if any), will be appended to the body.

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.