&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 you &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. 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. 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; --uscan. 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 --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. 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 --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. 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.