# 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/latest` and do a

        gbp pq import

then the newly created branch will be called `patch-queue/debian/latest`.

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 dropped 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/latest`.

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/latest'

What happened is that gbp pq imported each patch file and switched you to the newly created patch-queue branch (`patch-queue/debian/latest`) 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/latest` 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.