1quilt(1) General Commands Manual quilt(1)
2
6 quilt - tool to manage series of patches
7
10 quilt [-h] command [options]
11
14 Quilt is a tool to manage large sets of patches by keeping track of the
15 changes each patch makes. Patches can be applied, un-applied,
16 refreshed, etc. The key philosophical concept is that your primary out‐
17 put is patches.
18 With quilt, all work occurs within a single directory tree. Commands
20 can be be invoked from anywhere within the source tree. They are of the
21 form quilt cmd similar to CVS commands. They can be abbreviated as long
22 as the specified part of the command is unique. All commands print some
23 help text with quilt cmd -h.
24 Quilt manages a stack of patches. Patches are applied incrementally on
26 top of the base tree plus all preceding patches. They can be pushed on
27 top of the stack (quilt push), and popped off the stack (quilt pop).
28 Commands are available for querying the contents of the series file
29 (quilt series, see below), the contents of the stack (quilt applied,
30 quilt previous, quilt top), and the patches that are not applied at a
31 particular moment (quilt next, quilt unapplied). By default, most com‐
32 mands apply to the topmost patch on the stack.
33 Patch files are located in the patches sub-directory of the source tree
35 (see EXAMPLE OF WORKING TREE below). The QUILT_PATCHES environment
36 variable can be used to override this location. The patches directory
37 may contain sub-directories. It may also be a symbolic link instead of
38 a directory.
39 A file called series contains a list of patch file names that defines
41 the order in which patches are applied. Unless there are means by which
42 series files can be generated automatically, it is usually provided
43 along with a set of patches. In this file, each patch file name is on a
44 separate line. Patch files are identified by pathnames that are rela‐
45 tive to the patches directory; patches may be in sub-directories below
46 this directory. Lines in the series file that start with a hash charac‐
47 ter (#) are ignored. You can also add a comment after each patch file
48 name, introduced by a space followed by a hash character. When quilt
49 adds, removes, or renames patches, it automatically updates the series
50 file. Users of quilt can modify series files while some patches are
51 applied, as long as the applied patches remain in their original order.
52 Different series files can be used to assemble patches in different
54 ways, corresponding for example to different development branches.
55 Before a patch is applied (or ``pushed on the stack''), copies of all
57 files the patch modifies are saved to the .pc/patch directory. The
58 patch is added to the list of currently applied patches (.pc/applied-
59 patches). Later when a patch is regenerated (quilt refresh), the backup
60 copies in .pc/patch are compared with the current versions of the files
61 in the source tree using GNU diff.
62 Documentation related to a patch can be put at the beginning of a patch
64 file. Quilt is careful to preserve all text that precedes the actual
65 patch when doing a refresh. (This is limited to patches in unified for‐
66 mat; see diff documentation).
67 The series file is looked up in the .pc directory, in the root of the
69 source tree, and in the patches directory. The first series file that
70 is found is used. This may also be a symbolic link, or a file with mul‐
71 tiple hard links. Usually, only one series file is used for a set of
72 patches, so the patches sub-directory is a convenient location.
73 The .pc directory and its sub-directories cannot be relocated, but it
75 can be a symbolic link. While patches are applied to the source tree,
76 this directory is essential for many operations, including taking
77 patches off the stack (quilt pop), and refreshing patches (quilt
78 refresh). Files in the .pc directory are automatically removed when
79 they are no longer needed, so there is no need to clean up manually.
80
83 add [-P patch] {file} ...
84 Add one or more files to the topmost or named patch. Files must be
86 added to the patch before being modified. Files that are modified
87 by patches already applied on top of the specified patch cannot be
88 added.
89 -P patch
92 Patch to add files to.
94 annotate [-P patch] {file}
98 Print an annotated listing of the specified file showing which
100 patches modify which lines. Only applied patches are included.
101 -P patch
104 Stop checking for changes at the specified rather than the top‐
106 most patch.
107 applied [patch]
111 Print a list of applied patches, or all patches up to and including
113 the specified patch in the file series.
114 delete [-r] [--backup] [patch|-n]
118 Remove the specified or topmost patch from the series file. If the
120 patch is applied, quilt will attempt to remove it first. (Only the
121 topmost patch can be removed right now.)
122 -n Delete the next patch after topmost, rather than the specified
125 or topmost patch.
126 -r Remove the deleted patch file from the patches directory as
129 well.
130 --backup
133 Rename the patch file to patch~ rather than deleting it.
135 Ignored if not used with `-r'.
136 diff [-p n|-p ab] [-u|-U num|-c|-C num] [--combine patch|-z] [-R] [-P
140 patch] [--snapshot] [--diff=utility] [--no-timestamps] [--no-index]
141 [--sort] [--color] [file ...]
142 Produces a diff of the specified file(s) in the topmost or speci‐
144 fied patch. If no files are specified, all files that are modified
145 are included.
146 -p n
149 Create a -p n style patch (-p0 or -p1 are supported).
150 -p ab
153 Create a -p1 style patch, but use a/file and b/file as the
154 original and new filenames instead of the default dir.orig/file
155 and dir/file names.
156 -u, -U num, -c, -C num
159 Create a unified diff (-u, -U) with num lines of context. Cre‐
161 ate a context diff (-c, -C) with num lines of context. The num‐
162 ber of context lines defaults to 3.
163 --no-timestamps
166 Do not include file timestamps in patch headers.
168 --no-index
171 Do not output Index: lines.
173 -z Write to standard output the changes that have been made rela‐
176 tive to the topmost or specified patch.
177 -R Create a reverse diff.
180 -P patch
183 Create a diff for the specified patch. (Defaults to the top‐
185 most patch.)
186 --combine patch
189 Create a combined diff for all patches between this patch and
191 the patch specified with -P. A patch name of `-' is equivalent
192 to specifying the first applied patch.
193 --snapshot
196 Diff against snapshot (see `quilt snapshot -h').
198 --diff=utility
201 Use the specified utility for generating the diff. The utility
203 is invoked with the original and new file name as arguments.
204 --color[=always|auto|never]
207 Use syntax coloring.
209 --sort
212 Sort files by their name instead of preserving the original
213 order.
214 edit file ...
218 Edit the specified file(s) in $EDITOR after adding it (them) to the
220 topmost patch.
221 files [-v] [-a] [-l] [--combine patch] [patch]
225 Print the list of files that the topmost or specified patch
227 changes.
228 -a List all files in all applied patches.
231 -l Add patch name to output.
234 -v Verbose, more user friendly output.
237 --combine patch
240 Create a listing for all patches between this patch and the
242 topmost or specified patch. A patch name of `-' is equivalent
243 to specifying the first applied patch.
244 fold [-R] [-q] [-f] [-p strip-level]
249 Integrate the patch read from standard input into the topmost
251 patch: After making sure that all files modified are part of the
252 topmost patch, the patch is applied with the specified strip level
253 (which defaults to 1).
254 -R Apply patch in reverse.
257 -q Quiet operation.
260 -f Force apply, even if the patch has rejects. Unless in quiet
263 mode, apply the patch interactively: the patch utility may ask
264 questions.
265 -p strip-level
268 The number of pathname components to strip from file names when
270 applying patchfile.
271 fork [new_name]
275 Fork the topmost patch. Forking a patch means creating a verbatim
277 copy of it under a new name, and use that new name instead of the
278 original one in the current series. This is useful when a patch
279 has to be modified, but the original version of it should be pre‐
280 served, e.g. because it is used in another series, or for the his‐
281 tory. A typical sequence of commands would be: fork, edit,
282 refresh.
283 If new_name is missing, the name of the forked patch will be the
285 current patch name, followed by `-2'. If the patch name already
286 ends in a dash-and-number, the number is further incremented (e.g.,
287 patch.diff, patch-2.diff, patch-3.diff).
288 graph [--all] [--reduce] [--lines[=num]] [--edge-labels=files] [-T ps]
292 [patch]
293 Generate a dot(1) directed graph showing the dependencies between
295 applied patches. A patch depends on another patch if both touch the
296 same file or, with the --lines option, if their modifications over‐
297 lap. Unless otherwise specified, the graph includes all patches
298 that the topmost patch depends on. When a patch name is specified,
299 instead of the topmost patch, create a graph for the specified
300 patch. The graph will include all other patches that this patch
301 depends on, as well as all patches that depend on this patch.
302 --all
305 Generate a graph including all applied patches and their depen‐
306 dencies. (Unapplied patches are not included.)
307 --reduce
310 Eliminate transitive edges from the graph.
312 --lines[=num]
315 Compute dependencies by looking at the lines the patches mod‐
317 ify. Unless a different num is specified, two lines of context
318 are included.
319 --edge-labels=files
322 Label graph edges with the file names that the adjacent patches
324 modify.
325 -T ps
328 Directly produce a PostScript output file.
329 grep [-h|options] {pattern}
333 Grep through the source files, recursively, skipping patches and
335 quilt meta-information. If no filename argument is given, the whole
336 source tree is searched. Please see the grep(1) manual page for
337 options.
338 -h Print this help. The grep -h option can be passed after a dou‐
341 ble-dash (--). Search expressions that start with a dash can be
342 passed after a second double-dash (-- --).
343 header [-a|-r|-e] [--backup] [--strip-diffstat] [--strip-trailing-
347 whitespace] [patch]
348 Print or change the header of the topmost or specified patch.
350 -a, -r, -e
353 Append to (-a) or replace (-r) the exiting patch header, or
355 edit (-e) the header in $EDITOR. If none of these options is
356 given, print the patch header.
357 --strip-diffstat
360 Strip diffstat output from the header.
362 --strip-trailing-whitespace
365 Strip trailing whitespace at the end of lines of the header.
367 --backup
370 Create a backup copy of the old version of a patch as patch~.
372 import [-p num] [-R] [-P patch] [-f] [-d {o|a|n}] patchfile ...
376 Import external patches. The patches will be inserted following
378 the current top patch, and must be pushed after import to apply
379 them.
380 -p num
383 Number of directory levels to strip when applying (default=1)
385 -R
388 Apply patch in reverse.
390 -P patch
393 Patch filename to use inside quilt. This option can only be
395 used when importing a single patch.
396 -f Overwite/update existing patches.
399 -d {o|a|n}
402 When overwriting in existing patch, keep the old (o), all (a),
404 or new (n) patch header. If both patches include headers, this
405 option must be specified. This option is only effective when -f
406 is used.
407 mail {--mbox file|--send} [-m text] [--prefix prefix] [--sender ...]
411 [--from ...] [--to ...] [--cc ...] [--bcc ...] [--subject ...]
412 [--reply-to message] [first_patch [last_patch]]
413 Create mail messages from a specified range of patches, or all
415 patches in the series file, and either store them in a mailbox
416 file, or send them immediately. The editor is opened with a tem‐
417 plate for the introduction. Please see
418 /usr/share/doc/quilt-0.48/README.MAIL for details. When specifying
419 a range of patches, a first patch name of `-' denotes the first,
420 and a last patch name of `-' denotes the last patch in the series.
421 -m text
424 Text to use as the text in the introduction. When this option
426 is used, the editor will not be invoked, and the patches will
427 be processed immediately.
428 --prefix prefix
431 Use an alternate prefix in the bracketed part of the subjects
433 generated. Defaults to `patch'.
434 --mbox file
437 Store all messages in the specified file in mbox format. The
439 mbox can later be sent using formail, for example.
440 --send
443 Send the messages directly.
445 --sender
448 The envelope sender address to use. The address must be of the
450 form `user@domain.name'. No display name is allowed.
451 --from, --subject
454 The values for the From and Subject headers to use. If no
456 --from option is given, the value of the --sender option is
457 used.
458 --to, --cc, --bcc
461 Append a recipient to the To, Cc, or Bcc header.
463 --signature file
466 Append the specified signature to messages (defaults to ~/.sig‐
468 nature if found; use `-' for no signature).
469 --reply-to message
472 Add the appropriate headers to reply to the specified message.
474 new {patchname}
478 Create a new patch with the specified file name, and insert it
480 after the topmost patch.
481 Quilt can be used in sub-directories of a source tree. It deter‐
483 mines the root of a source tree by searching for a patches direc‐
484 tory above the current working directory. Create a patches direc‐
485 tory in the intended root directory if quilt chooses a top-level
486 directory that is too high up in the directory tree.
487 next [patch]
491 Print the name of the next patch after the specified or topmost
493 patch in the series file.
494 patches [-v] {file}
498 Print the list of patches that modify the specified file. (Uses a
500 heuristic to determine which files are modified by unapplied
501 patches. Note that this heuristic is much slower than scanning
502 applied patches.)
503 -v Verbose, more user friendly output.
506 pop [-afRqv] [num|patch]
510 Remove patch(es) from the stack of applied patches. Without
512 options, the topmost patch is removed. When a number is specified,
513 remove the specified number of patches. When a patch name is spec‐
514 ified, remove patches until the specified patch end up on top of
515 the stack. Patch names may include the patches/ prefix, which
516 means that filename completion can be used.
517 -a Remove all applied patches.
520 -f Force remove. The state before the patch(es) were applied will
523 be restored from backup files.
524 -R Always verify if the patch removes cleanly; don't rely on time‐
527 stamp checks.
528 -q Quiet operation.
531 -v Verbose operation.
534 previous [patch]
538 Print the name of the previous patch before the specified or top‐
540 most patch in the series file.
541 push [-afqv] [--leave-rejects] [--color[=always|auto|never]]
545 [num|patch]
546 Apply patch(es) from the series file. Without options, the next
548 patch in the series file is applied. When a number is specified,
549 apply the specified number of patches. When a patch name is speci‐
550 fied, apply all patches up to and including the specified patch.
551 Patch names may include the patches/ prefix, which means that file‐
552 name completion can be used.
553 -a Apply all patches in the series file.
556 -q Quiet operation.
559 -f Force apply, even if the patch has rejects. Unless in quiet
562 mode, apply the patch interactively: the patch utility may ask
563 questions.
564 -v Verbose operation.
567 --leave-rejects
570 Leave around the reject files patch produced, even if the patch
572 is not actually applied.
573 --color[=always|auto|never]
576 Use syntax coloring.
578 refresh [-p n|-p ab] [-u|-U num|-c|-C num] [-z[new_name]] [-f] [--no-
582 timestamps] [--no-index] [--diffstat] [--sort] [--backup] [--strip-
583 trailing-whitespace] [patch]
584 Refreshes the specified patch, or the topmost patch by default.
586 Documentation that comes before the actual patch in the patch file
587 is retained.
588 It is possible to refresh patches that are not on top. If any
590 patches on top of the patch to refresh modify the same files, the
591 script aborts by default. Patches can still be refreshed with -f.
592 In that case this script will print a warning for each shadowed
593 file, changes by more recent patches will be ignored, and only
594 changes in files that have not been modified by any more recent
595 patches will end up in the specified patch.
596 -p n
599 Create a -p n style patch (-p0 or -p1 supported).
600 -p ab
603 Create a -p1 style patch, but use a/file and b/file as the
604 original and new filenames instead of the default dir.orig/file
605 and dir/file names.
606 -u, -U num, -c, -C num
609 Create a unified diff (-u, -U) with num lines of context. Cre‐
611 ate a context diff (-c, -C) with num lines of context. The num‐
612 ber of context lines defaults to 3.
613 -z[new_name]
616 Create a new patch containing the changes instead of refreshing
618 the topmost patch. If no new name is specified, `-2' is added
619 to the original patch name, etc. (See the fork command.)
620 --no-timestamps
623 Do not include file timestamps in patch headers.
625 --no-index
628 Do not output Index: lines.
630 --diffstat
633 Add a diffstat section to the patch header, or replace the
635 existing diffstat section.
636 -f Enforce refreshing of a patch that is not on top.
639 --backup
642 Create a backup copy of the old version of a patch as patch~.
644 --sort
647 Sort files by their name instead of preserving the original
648 order.
649 --strip-trailing-whitespace
652 Strip trailing whitespace at the end of lines.
654 rename [-P patch] new_name
658 Rename the topmost or named patch.
660 -P patch
663 Patch to rename.
665 revert [-P patch] {file} ...
669 Revert the changes to the topmost or named patch for the specified
671 file(s). Changes to files that are modified by patches on top of
672 the specified patch cannot be reverted.
673 -P patch
676 Revert changes in the named patch.
678 series [-v]
682 Print the names of all patches in the series file.
684 -v Verbose, more user friendly output.
687 setup [-d path-prefix] [-v] [--sourcedir dir] {specfile|seriesfile}
691 Initializes a source tree from an rpm spec file or a quilt series
693 file.
694 -d Optional path prefix for the resulting source tree.
697 --sourcedir
700 Directory that contains the package sources. Defaults to `.'.
702 -v Verbose debug output.
705 snapshot [-d]
709 Take a snapshot of the current working state. After taking the
711 snapshot, the tree can be modified in the usual ways, including
712 pushing and popping patches. A diff against the tree at the moment
713 of the snapshot can be generated with `quilt diff --snapshot'.
714 -d Only remove current snapshot.
717 top
721 Print the name of the topmost patch on the current stack of applied
723 patches.
724 unapplied [patch]
728 Print a list of patches that are not applied, or all patches that
730 follow the specified patch in the series file.
731 upgrade
735 Upgrade the meta-data in a working tree from an old version of
737 quilt to the current version. This command is only needed when the
738 quilt meta-data format has changed, and the working tree still con‐
739 tains old-format meta-data. In that case, quilt will request to run
740 `quilt upgrade'.
741
745 --trace
746 Runs the command in bash trace mode (-x). For internal debug‐
748 ging.
749 --quiltrc file
752 Use the specified configuration file instead of ~/.quiltrc (or
754 /etc/quilt.quiltrc if ~/.quiltrc does not exist). See the pdf
755 documentation for details about its possible contents. The
756 special value "-" causes quilt not to read any configuration
757 file.
758 --version
761 Print the version number and exit immediately.
763
767 work/ -+- ...
768 |- patches/ -+- series
769 | |- patch2.diff
770 | |- patch1.diff
771 | +- ...
772 +- .pc/ -+- applied-patches
773 |- patch1.diff/ -+- ...
774 |- patch2.diff/ -+- ...
775 +- ...
776
779 Please refer to the pdf documentation for an example.
780
783 Upon startup, quilt evaluates the file .quiltrc in the user's home
784 directory, or the file specified with the --quiltrc option. This file
785 is a regular bash script. Default options can be passed to any command
786 by defining a QUILT_COMMAND_ARGS variable. For example,
787 QUILT_DIFF_ARGS="--color=auto" causes the output of quilt diff to be
788 syntax colored when writing to a terminal.
789 In addition to that, quilt recognizes the following variables:
791 QUILT_DIFF_OPTS
794 Additional options that quilt shall pass to GNU diff when generat‐
796 ing patches. A useful setting for C source code is "-p", which
797 causes GNU diff to show in the resulting patch which function a
798 change is in.
799 QUILT_PATCH_OPTS
802 Additional options that quilt shall pass to GNU patch when applying
804 patches. For example, some versions of GNU patch support the
805 "--unified-reject-files" option for generating reject files in uni‐
806 fied diff style.
807 QUILT_DIFFSTAT_OPTS
810 Additional options that quilt shall pass to diffstat when generat‐
812 ing patch statistics. For example, "-f0" can be used for an alter‐
813 native output format. Recent versions of diffstat also support
814 alternative rounding methods ("-r1", "-r2").
815 QUILT_PATCHES
818 The location of patch files, defaulting to "patches".
820 QUILT_SERIES
823 The name of the series file, defaulting to "series". Unless an
825 absolute path is used, the search algorithm described above
826 applies.
827 QUILT_PATCHES_PREFIX
830 If set to anything, quilt will prefix patch names it prints with
832 their directory (QUILT_PATCHES).
833 QUILT_NO_DIFF_INDEX
836 By default, quilt prepends an Index: line to the patches it gener‐
838 ates. If this variable is set to anything, no line is prepended.
839 This is a shortcut to adding --no-index to both QUILT_DIFF_ARGS and
840 QUILT_REFRESH_ARGS.
841 QUILT_NO_DIFF_TIMESTAMP
844 By default, quilt includes timestamps in headers when generating
846 patches. If this variable is set to anything, no timestamp will be
847 included. This is a shortcut to adding --no-timestamps to both
848 QUILT_DIFF_ARGS and QUILT_REFRESH_ARGS.
849 EDITOR
852 The program to run to edit files. If it isn't redefined in the
854 configuration file, $EDITOR as defined in the environment will be
855 used.
856
859 Quilt started as a series of scripts written by Andrew Morton (patch-
860 scripts). Based on Andrew's ideas, Andreas Gruenbacher completely
861 rewrote the scripts, with the help of several other contributors (see
862 AUTHORS file in the distribution).
863 This man page was written by Martin Quinson, based on information found
865 in the pdf documentation, and in the help messages of each commands.
866
869 The pdf documentation, which should be under
870 /usr/share/doc/quilt/quilt.pdf. Note that some distributors compress
871 this file. zxpdf(1) can be used to display compressed pdf files.
872 diff(1), patch(1).
874quilt June 2, 2006 quilt(1)