# 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 `--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.

## Importing a new upstream version

To update your patches for a new upstream version one

1. 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.

2. Imports the new upstream version with &gbp-import-orig; `--uscan`.

3. 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.

4. 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 `--time-machine=` 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; `rebase` 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; `rebase` (if you simply want to abort use &gitcmd; `rebase` `--abort`).

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:

1. 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;

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 your &debian-branch; branch, generate the patches and commit them right away to this 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`.

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

      &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.