# 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:

      &gitcmd; add debian/patches
      &gitcmd; 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 &gitcmd; `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

      &gitcmd; 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