This guide introduces usage of quilt for managing patches to
Debian packages.
It describes how to create, modify, apply and unapply patches with
quilt.
This is a work in progress. Please send any comments or ideas to <dmn@debian.org>.
quilt helps managing a series of patches that a Debian package maintainer
needs applied to upstream source when building the package. It is similar to
dpatch and cdbs's simple-patchsys in that the patches are kept as a
series of files in debian/patches.
quilt uses a special directory for keeping patches.
Unfortunatelly, that directory is ./patches/ by default. For Debian packages
./debian/patches/ is far more comfortable. To flawlessly fix this, add
export QUILT_PATCHES=debian/patches in your shell resource file and reload
it. This way you won't have to worry about this quilt oddity (like me; even
forgot to mention it in the first revision of this document).
You can also create .quiltrc in your home directory and set
QUILT_PATCHES there if you prefer.
quilt manages the series of patches as a stack. You push to it (apply a
patch) and pop from it (unapply a patch).
A special file, debian/patches/series, contains the
list of all patches to be applied. quilt applies patches in the order they
are listed in that file.
quilt works in the source tree. There's no copying large trees around.
There's also no need to always keep the source tree clean of unapplied changes
just to be able to extract a diff with Git.
To achieve this, however, quilt needs to know which files are contained in
each patch. The workflow is as follows:
quilt that you start working on a given patch
quilt that you're done
At first this sounds complicated but actually it is not. You just speak to your patch system so it knows what you're doing and handles the details.
Here are a few examples of working with quilt. Note that most of the
commands below have plenty of options so reading quilt man page is a good idea.
To create a patch, run quilt new $patch_name. If you want .patch
extension, you need to give it explicitly.
This creates a new patch entry in debian/patches. This patch also becomes the topmost or current patch. This is the patch that is at the top of the stack.
Now choose what file you want to change in that patch and run
quilt edit $file. quilt notes the current state of the file and
launches your $EDITOR so you can edit the file.
Repeat the quilt edit command for every file you want to be changed by that
patch.
When you're finished, run quilt refresh. This compares the noted state
of the edited files with their present state, and produces a patch in
debian/patches.
Note that this patch is currently applied. Check it with quilt applied.
If the package is already being maintained in the pkg-perl Git repository, it is
necessary to tell Git that you have added new files. You can do this with
git add debian/patches ; git commit.
Now that we have the patch applied, let's play with it. quilt pop
unapplies the topmost patch. quilt push applies the next patch in the series.
You may see the list of unapplied patches with quilt unapplied.
To edit a patch, you have to first make it current (be on the top of the stack
of applied patches). If the patch is already applied (but not the top), run
quilt pop $patch_name; if it is not, run quilt push $patch_name. Now that
the patch is on the top of the stack, run quilt edit $file as before. You
can edit files that were already in the patch and you can edit new files. When
you're done, remember to tell this to quilt by running quilt refresh.
quilt delete deletes, quilt rename renames a patch. There are a lot
more. See the manual page.
Unless 3.0 (quilt) source format is used (see below), quilt needs to be
added to Build-Depends. Note that Build-Depends-Indep (for arch:all
packages) is not appropriate as quilt is needed by the clean target.
Note: Patches should be unapplied before committing other changes to Git! If you forget, don't worry, Lintian will issue a warning to remind you.
Since patches are used so often, the "3.0 (quilt)" source package format
supports them by default. A running build system will use quilt if it's
available and dpkg-source can apply patches otherwise. To test your
package, you can do this:
$ apt-get source libacme-foo-perl
$ mkdir -p libacme-foo-perl-0.1/debian/source
$ echo "3.0 (quilt)" >libacme-foo-perl-0.1/debian/source/format
$ dpkg-source -b libacme-foo-perl-0.1
$ dpkg-source -x libacme-foo-perl-0.1-1.dsc
$ cd libacme-foo-perl-0.1 && debuild -us -uc
Instructions how to convert your package to '3.0 (quilt)' package source format can be found there: http://wiki.debian.org/Projects/DebSrc3.0#Howtoconvertasourcepackage.3F.
If you happen to maintain a perl module package, the following command may help
you migrate to 3.0 (quilt) source format:
dh-make-perl refresh --source-format='3.0 (quilt)'
See dh-make-perl(1) for more details.
include /usr/share/quilt/quilt.make has some candy for debian/rules.
First, it defines QUILT_PATCHES to be debian/patches so that one doesn't
have to worry about that setting during the build process.
Second, it defines QUILT_STAMPFN, which can be used as a build-stamp or
configure-stamp dependency.
Lastly, unpatch target is useful as a clean dependency.
Here's a sample fragment from debian/rules:
include /usr/share/quilt/quilt.make
build: build-stamp
build-stamp: $(QUILT_STAMPFN)
dh_testdir
...
clean: unpatch
dh_clean build-stamp
...
Note that using the following:
build: patch build-stamp
build-stamp:
...
can fail if parallel build is allowed via -jN. patch and build-stamp
would be run in parallel, possibly failing due to partly applied patches.
N.B. /usr/share/quilt/quilt.make is available since quilt version 0.40.
This version is available since Etch so the build-dependency can usually be
without version.
Since 0.46-7 quilt offers a simpler integration with debhelper. A simple
debian/rules can now be written as (needs debhelper >= 7.0.8):
%:
dh $@ --with quilt
Alternatively dh_quilt_patch and dh_quilt_unpatch can be added to
debian/rules.
For the details take a look at /usr/share/doc/quilt/README.Debian and/or
dh_quilt_patch(1), dh_quilt_unpatch(1).
Sometimes you need to rename a file, for example if there are some nice scripts you'd like to have installed, but they have a .pl extension. For Debian packages, scripts are usually installed with the extension dropped, so that you can call it on the command line as:
$ some_utility blahblah
# rather than
$ some_utility.pl blahblah
In this case, you will need to patch the script file itself so that it only
refers to itself as the new name. Afterward, you rename the file using an
override (see the debhelper article for more). You need to make sure
the patch is applied first, then the file can be renamed -- this way, if
one uses dpkg-source to do the patching, it will work properly -- if
you rename the file first, then dpkg-source won't be able to find the file
(since the build isn't being run, and the file hasn't been renamed yet)
and it will fail.
%:
dh $@ --with quilt
override_dh_quilt_patch:
dh_quilt_patch
[ -f bin/some_utility ] || mv bin/some_utility.pl bin/some_utility
override_dh_quilt_unpatch:
[ -f bin/some_utility.pl ] || mv bin/some_utility bin/some_utility.pl
dh_quilt_unpatch
If you use source format 3.0 (quilt), the patches are applied/
un-applied at the right point.
If you use source format 3.0 (quilt), you don't need debian/README.source,
since the package itself doesn't use quilt but a dpkg feature.
Else, as of Debian Policy version 3.8.0, packages that use a patch system, such as quilt, are required to have a debian/README.source file explaining how to generate the patched source, add a new modification, and remove an existing modification. A standard debian/README.source file is used for all packages maintained by the Debian Perl Group. The debian/README.source file looks like this:
This package uses quilt to manage all modifications to the upstream source.
Changes are stored in the source package as diffs in debian/patches and
applied during the build.
See /usr/share/doc/quilt/README.source for a detailed explanation.
You can also use packagecheck -Q -c to generate the debian/README.source
file.
FIXME: compare against the current practical alternative, that is gbp-pq(1). Let's be fair :)
This is due to the fact that quilt works within the source tree. dpatch
needs to create a copy, then diff recursively.
quilt push -f # force rejections
quilt edit files-with-rejections
quilt refresh
quilt push
quilt refresh
By default, quilt saves patches that look like the output from diff.
This means they include timestamps for each changed file. quilt also
preserves Index: lines, such as those generated by svn diff. However,
patch doesn't need any of that data to apply the patch and it has the
unfortunate side effect of causing every file header line of the patch to
change each time someone runs quilt refresh.
To use the simplest headers in the patch, add:
QUILT_DIFF_ARGS="--no-timestamps --no-index -pab"
QUILT_REFRESH_ARGS="--no-timestamps --no-index -pab"
to ~/.quiltrc or set those variables in the environment if you prefer. The
next time you quilt refresh a patch, quilt will remove the extraneous
information.
If upstream has made a change that conflicts with a patch, one normally
force-applies the patch (with quilt push -f patch) and then looks at the
resulting *.rej file to see what part of the patch failed. By default,
rejected hunks come out in unified diff format if the input patch was of that format,
otherwise in ordinary context diff form. If you're using patches in context diff
format, you can tell quilt to create unified context diffs for
the *.rej files by putting:
QUILT_PATCH_OPTS="--reject-format=unified"
in your ~/.quiltrc or by setting that variable in the environment.
Attention: --unified-reject-files was removed in patch 2.6.1-1.
Having this option in ~/.quiltrc breaks quilt.
Copyright (c) 2007-2012 by the individual authors and contributors noted above. All rights reserved. This document is free software; you may redistribute it and/or modify it under the same terms as Perl itself
Perl is distributed under your choice of the GNU General Public License or the Artistic License. On Debian GNU/Linux systems, the complete text of the GNU General Public License can be found in `/usr/share/common-licenses/GPL' and the Artistic License in `/usr/share/common-licenses/Artistic'.