# Working with patches

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:

- 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 master. The git documentation explains how to work with git-rebase.

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) packges

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:

- Using `debian/source/local-options`: You can use `unapply-patches` in `debian/source/local-options` to unapply the patches after the build. `/usr/share/doc/git-buildpackage/examples/gbp-configure-unpatched-source` will this set up for you when run from inside a git repository of a Debian package.

- Using `--git-export-dir`: If you are using option `--git-export-dir` already there is no problem since the unpatched source tree gets exported before being built (and patched by dpkg-source). Since this implies an extra copy of the whole source tree (which might be slow for big projects) and it is not really necessary when using pbuilder the next method might be more appropriate.

- Working from a patch-queue branch. Instead of building from master build from patch-queue/master prepared by gbp pq as describe above. This branch has the patches already applied as dpkg-source expects it:

        gbp pq import
        gbp buildpackage --git-debian-branch=patch-queue/master
        #Build and test...
        Git checkout master
        gbp pq export