Working with Patches
&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:
&gitcmd; add debian/patches
&gitcmd; commit
If you don't want to commit the result by hand each time you can also
pass to the &gbp;
command above.
Next you can update debian/changelog (e.g. by
running "&gbp-dch; ") and
build the package as usual.
Importing a new upstream version
To update your patches for a new upstream version one
Imports the current patches onto the patch-queue branch (if
not done already) using &gbp-pq-import;. This will allow you
to rebase the patches on the new upstream version later.
Imports the new upstream version with
&gbp-import-orig; .
Rebases the patches onto the new upstream version using
&gbp-pq-rebase;. This will bring the patches up to date
regarding the new upstream version. Patches already applied
upstream can be dropped and remaining patches can be modified
to apply to the new version.
Exports the patches to debian/patches using
&gbp-pq-export;.
But don't worry if you forgot to do so before importing the new
version (or if another team member imported the version already).
In this case you can make &gbp-pq; figure out where to apply the
patches by using the option. The
following command
&gbp-pq-import; --force --time-machine=10
would drop your current patch-queue branch (if existent) and
create a new one by going back in your commit history as far as 10
commits to find a place where your patches still
apply This is not necessarily
your debian-branch; HEAD since the new upstream
version might have changed so that the patches no longer apply
cleanly there.. If it finds such a commit on
your &debian-branch; it will create the patch-queue branch from
there and switch you to that branch. You can now rework your
patches to apply to the new upstream version by using
&gbp-pq-rebase;:
The patch-queue branch and &debian-branch; after importing the
patches.
&gbp-pq-rebase;
or you can invoke &gitcmd; directly:
&gitcmd; rebase -i debian/sid
Should the rebase fail (e.g. because the upstream source changed
at the same place your patches modify the code) you can resolve
this by using the options of &gitcmd; (if
you simply want to abort use
&gitcmd; ).
The patch-queue branch after rebasing the patches. Patches
that were merged upstream were dropped.
Once done you can export your commits to patch files again:
&gbp-pq-export; --commit
The export will also switch you back to the &debian-branch;.
The &debian-branch; after exporting the patches and committing the changes.
See this in action in a
short
video.
Adding your first patch
If a package doesn't have any patches yet, these are the steps to add
your first patch:
Launch an import. If there's nothing to import &gbp-pq; will just
create an empty branch and switch your working copy to it:
&gbp-pq-import;
Create your first patch: edit files, test, commit your changes
using git commit
To generate the new Quilt patch set use
&gbp-pq-export; --commit
This will switch you back to your &debian-branch; branch, generate the
patches and commit them right away to this branch.
Skip the 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.
Team maintenanceThe easiest way is to not push out any patch-queue/* branches at all.
They can be recreated by any team member easily by using
&gbp-pq-import; --force
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 push out patch-queue branches. Other team
members must just be aware that branches in the patch-queue/
namespace are being rebased frequently and therefore cause
non fast-forward updates.