Quilt for Debian maintainers

This guide briefly introduces usage of quilt for managing patches to debian packages.

It will describe 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>.

1. The big picture

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.

1.0. Preparation

quilt uses a special directory for keeping patches (not very surprising). 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.

1.1. Patches order -- the series

quilt manages the series of patches as a stack. You push to it (apply a patch) and pop from it (unapply a patch).

There's one special file, debian/patches/series, which contains the list of all patches to be applied. quilt applies patches in the order they are listed in that file.

1.2. quilt philosophy

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

To achieve this, however, quilt needs to know which files are contained in each patch. The workflow is as follows:

  1. you tell quilt that you start working on a given patch
  2. you work on that patch
  3. you tell quilt that you're done

At first this sounds complicated but it actually it is not. You just speak to your patch system so it knows what you're doing and handles the details.

2. Working with quilt

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.

2.1. Creating a patch

To create a patch, run quilt new $patch_name. If you want .patch extension, you need to give it.

This will create 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 will note the current state of the file and launch your $EDITOR so you can edit the file.

Repeat the quilt edit command for all files you want to be changed by that patch.

When you're finished, run quilt refresh. This will compare the noted state of the edited files with their present state and produce a patch in debian/patches.

Note that that patch is currently applied. Check it with quilt applied.

If the package is already being maintained in the pkg-perl svn repository, it is necessary to tell svn that you have added new files. You can do this with svn add debian/patches.

2.2. Applying and unapplying patches

Now that we have the patch applied, let's play with it. quilt pop will unapply the topmost patch. quilt push applies the next patch in the series. You may see the list of unapplied patches with quilt unapplied.

2.3. Editing patches

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.

2.4. Other commands

quilt delete deletes, quilt rename renames a patch. There are a lot more. See the manual page.

3. Integrating within package build process

Obviously, 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 to SVN!

3.1 The "classical" way

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.

3.2 The "modern" way

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

    #!/usr/bin/make -f
    %:
        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).

3.3 Creating a README.source file

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.

4. Why quilt is better?

5. Tips and tricks

5.1. Cleaner patches

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.

5.2. Unified reject files

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, the *.rej file is a traditional context diff similar to the output of diff -c. If you're used to the output of diff -u, you can tell quilt to create unified context diffs for the *.rej files by putting:

    QUILT_PATCH_OPTS="--unified-reject-files"

in your ~/.quiltrc or by setting that variable in the environment.

Version

$Id: quilt.pod 37718 2009-06-06 19:44:42Z nhandler-guest $

Authors

Contributors

License

Copyright (c) 2007-2009 Debian Perl Group. 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'.