r7038 - /website/quilt.pod

Tue Aug 21 10:02:54 UTC 2007

Author: dmn
Date: Tue Aug 21 10:02:54 2007
New Revision: 7038

URL: http://svn.debian.org/wsvn/?sc=1&rev=7038
Log:
Add brief quilt introduction to pkg-perl site

Added:
    website/quilt.pod   (with props)

Added: website/quilt.pod
URL: http://svn.debian.org/wsvn/website/quilt.pod?rev=7038&op=file
==============================================================================

--- website/quilt.pod (added)
+++ website/quilt.pod Tue Aug 21 10:02:54 2007
@@ -1,0 +1,179 @@
+
+=head1 Quilt for Debian maintainers
+
+This guide briefly introduces usage of C<quilt> for managing patches to debian
+packages.
+
+It will describe how to create, modify, apply and unapply patches with
+C<quilt>.
+
+This is a work in progress.  Please send any comments or ideas to
+<dmn at debian.org>.
+
+=head1 1. The big picture
+
+C<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
+C<dpatch> and C<cdbs>'s simple-patchsys in that the patches are kept as a
+series of files in C<debian/patches>.
+
+=head2 1.1. Patches order -- the series
+
+C<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 in C<debian/patches>, C<series>, which contains the
+list of all patches to be applied. C<quilt> applies patches in the order they
+are listed in that file.
+
+=head2 1.2. debian/patches
+
+In Debian packages, it is usual to have the patches in C<debian/patches>.
+C<quilt>'s default patches directory, however, is C<./patches>. To make it
+follow Debian, one needs to do C<export QUILT_PATCHES=debian/patches>. Note
+that the C<quilt.make> snippet makes this so you don't need to set this
+explicitly in C<debian/rules>.
+
+=head2 1.3. quilt philosophy
+
+C<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, C<quilt> needs to know which files are contained in
+each patch. The workflow is as follows:
+
+=over 4
+
+=item 1. you tell C<quilt> that you start working on a given patch
+
+=item 2. you work on that patch
+
+=item 3. you tell C<quilt> that you're done
+
+=back
+
+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.
+
+=head1 2. Working with C<quilt>
+
+Here are a few examples of working with C<quilt>. Note that most of the
+commands below have plenty of options so reading quilt man page is a good idea.
+
+=head2 2.1. Creating a patch
+
+To create a patch, run C<quilt new $patch_name>. If you want C<.patch>
+extension, you need to give it.
+
+This will create a new patch entry in C<debian/patches>. This patch also
+becomes the I<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
+C<quilt edit $file>. C<quilt> will note the current state of the file and
+launch your C<$EDITOR> so you can edit the file.
+
+Repeat the C<quilt edit> command for all files you want to be changed by that
+patch.
+
+When you're finished, run C<quilt refresh>. This will compare the noted state
+of the edited files with their present state and produce a patch in
+C<debian/patches>.
+
+Note that that patch is currently applied. Check it with C<quilt applied>.
+
+=head2 2.2. Applying and unapplying patches
+
+Now that we have the patch applied, let's play with it. C<quilt pop> will
+unapply the tompost patch. C<quilt push> applies the next patch in the series.
+You may see the list of unapplied patches with C<quilt unapplied>.
+
+=head2 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
+C<quilt pop $patch_name>; if it is not, run C<quilt push $patch_name>. Now that
+the patch is on the top of the stack, run C<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 C<quilt> by running C<quilt refresh>.
+
+=head2 2.4. Other commands
+
+C<quilt delete> deletes, C<quilt rename> renames a patch. There are a lot more. See the manual page.
+
+=head1 3. Integrating within package build process
+
+C<include /usr/share/quilt/quilt.make> gives debian/rules two useful targets:
+I<patch> and I<unpatch>.
+
+Integrate them within debian/rules as you see fit. Example:
+
+    include /usr/share/quilt/quilt.make
+
+    build: patch build-stamp
+    build-stamp
+        dh_testkdir
+        ...
+    clean: unpatch
+        dh_clean build-stamp
+        ...
+
+=head1 4. Why quilt is better?
+
+=over 4
+
+=item * patch creating/editing is faster
+
+This is due to the fact that quilt works within the source tree. C<dpatch>
+needs to create a copy, then diff recursively.
+
+Using C<svn> to create patches is impossible if you have a file that is modified
+by several patches. C<quilt> does this naturally.
+
+=item * fixing a rejected file is easier
+
+    quilt push -f # force rejections
+    quilt edit files-with-rejections
+    quilt refresh
+
+=item * refreshing a fuzzy patch is a beeze
+
+    quilt push
+    quilt refresh
+
+=back
+
+=head1 Version
+
+$Id$
+
+=head1 Authors
+
+=over
+
+=item * Damyan Ivanov <dmn at debian.org>
+
+=back
+
+=head1 Contributors
+
+=over
+
+=item * none yet :)
+
+=back
+
+=head1 License
+
+Copyright (c) 2007 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'.
+
+=for comment
+vim:tw=79

Propchange: website/quilt.pod
------------------------------------------------------------------------------
    svn:keywords = Id


