Working with patches

Table of Contents
Workflow
Team maintenance
Working with 3.0 (quilt) packages

gbp pq can be used to manage patches inside debian/patches/.

The basic idea is that patches are imported to a local patch-queue branch with one commit on the patch-queue branch representing exactly one patch in debian/patches/. The patch-queue branch will be named like the branch that has the debian/patches dir you imported from with patch-queue/ prepended. So if you have your Debian packaging on master the patch-queue branch will be called patch-queue/master.

There, the maintainer will work on them using usual Git commands (rebase, commit --amend, etc). When done, gbp pq will be used to export the patches to debian/patches/. This workflow facilitates the cherry-picking of patches for stable releases, and 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). The generated patches in debian/patches/ have all the necessary information to forward them upstream given they are auto generated via git-format-patch(1).

The main drawback of this workflow is the lack of history on the patch-queue/master branch (but there is full history on the master branch, of course).


Workflow

Assuming the Debian source package has its patches in debian/patches and these are parseable by git-quiltimport(1):

Create patch-queue branch and import debian/patches onto it using gbp pq

  cd REPO
  gbp pq import

This will switch you to the patch-queue branch automatically.

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

Regenerate the patches in debian/patches/ using gbp pq. This will switch you back to master and regenerate the patches using a method similar to git-format-patch(1):

  gbp pq export

Commit the result either by passing --commit to the above export or by using git commands:

  git add debian/patches
  git commit

Update debian/changelog (e.g. by running "gbp dch -S -a")

You can now build the package as usual.

After importing a new upstream version you can use the following commands to refresh debian/patches/:

  gbp pq rebase
  gbp pq export

Should the rebase fail you can resort to git rebase.

If you forgot to create a patch-queue before importing the new upstream version you can make gbp pq figure out where to apply the patches by using the --time-machine=.

If a package doesn't have any patches yet, these are the steps to add your first patch:

  1. Launch an import, this will switch to the proper branch

      gbp pq import

  2. Create your first patch: edit files, test, commit your changes using git commit

  3. To generate the new Quilt patch set use

      gbp pq export --commit
    This will switch you back to the master branch generate the patches and commit them right away to your master branch. Skip the --commit if you don't want to commit right away. If you want to pick the changelog message from the patch see /usr/share/doc/git-buildpackage/examples/gbp-add-patch.

In order to avoid a patched (unclean) source tree after the build, you can use Dpkg-source's unapply-patches option and tell Git to ignore the .pc directory. /usr/share/doc/git-buildpackage/examples/gbp-configure-unpatched-source sets up these two files for you.


Team maintenance

The easiest way is to not push out any patch-queue/* branches at all. They can be recreated by any team member easily by using

  git branch -d patch-queue/master
  gbp pq import

The patch-queue branch can also be re-created when pulling (this will additionally drop your current patch-queue branch and recreate it from debian/patches):

  gbp pull --redo-pq

Note that you can you can push out patch-queue branches. Other team members must just be aware that that branches in the patch-queue/ namespace are being rebased frequently and therefore cause non fast-forward updates.


Working with 3.0 (quilt) packages

The 3.0 (quilt) format applies the patches in debian/patches automatically when building a source package. If you want your debian branch to contain the unpatched source there are several ways to handle this: