=head1 Quilt for Debian Maintainers This guide introduces usage of C for managing patches to Debian packages. It describes how to create, modify, apply and unapply patches with C. This is a work in progress. Please send any comments or ideas to . =head1 The Big Picture C helps managing a series of patches that a Debian package maintainer needs applied to upstream source when building the package. It is similar to C and C's simple-patchsys in that the patches are kept as a series of files in F. =head2 Preparation C uses a special directory for keeping patches. Unfortunatelly, that directory is F<./patches/> by default. For Debian packages F<./debian/patches/> is far more comfortable. To flawlessly fix this, add C to F<~/.quiltrc> (creating that file if needed). =head2 Patch Order: the 'series' C 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, F, contains the list of all patches to be applied. C applies patches in the order they are listed in that file. =head2 Git-oriented user-interface Instead of using the C command, you can use C to manage the patch series applied on top of the upstream source tree. To do so, use L. If you choose to go this way, you can skip reading the rest of this document. =head2 Philosophy C 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, C needs to know which files are contained in each patch. The workflow is as follows: =over =item 1. you tell C that you start working on a given patch =item 2. you work on that patch =item 3. you tell C that you're done =back At first this may sound complicated, but you can do it! In a nutshell, you speak to your patch system so it knows what you're doing, and it handles the details. =head2 Working With quilt Here are a few examples of working with C. Note that most of the commands below have plenty of options so reading quilt man page is a good idea. =head2 Creating a Patch To create a patch, run C. If you want C<.patch> extension, you need to give it explicitly. This creates a new patch entry in F. This patch also becomes the I 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 C. C notes the current state of the file and launches your C<$EDITOR> so you can edit the file. Repeat the C command for every file you want to be changed by that patch. When you're finished, run C. This compares the noted state of the edited files with their present state, and produces a patch in F. Note that this patch is currently applied. Check it with C. 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 C. =head2 Applying and Unapplying Patches Now that we have the patch applied, let's play with it. C unapplies the topmost patch. C applies the next patch in the series. You may see the list of unapplied patches with C. =head2 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 C; if it is not, run C. Now that the patch is on the top of the stack, run C 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 C by running C. =head2 Other Commands C deletes, C renames a patch. There are a lot more. See the manual page. =head1 Integrating With the Package Build Process Unless C<3.0 (quilt)> source format is used (see below), C needs to be added to C. Note that C (for arch:all packages) is not appropriate as C is needed by the C 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 C 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 =head1 How to =over =item * fix a rejected file quilt push -f # force rejections quilt edit files-with-rejections quilt refresh =item * refresh a fuzzy patch quilt push quilt refresh =back =head1 Tips and Tricks =head2 Cleaner Patches By default, C saves patches that look like the output from C. This means they include timestamps for each changed file. However, C 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 C. 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 F<~/.quiltrc>. The next time you C a patch, C will remove the extraneous information. =head2 Unified Reject Files If upstream has made a change that conflicts with a patch, one normally force-applies the patch (with C>) and then looks at the resulting F<*.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 C to create unified context diffs for the F<*.rej> files by putting: QUILT_PATCH_OPTS="--reject-format=unified" in your F<~/.quiltrc>. =head1 Authors =over =item * Damyan Ivanov =back =head1 Contributors =over =item * gregor herrmann =item * Russ Allbery =item * Jonathan Yu =item * Dominique Dumont =item * intrigeri =back =head1 License and Copyright 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'. =for comment vim:tw=79