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 root of the source tree, in the
69 patches directory, and in the .pc directory. The first series file
70 that is found is used. This may also be a symbolic link, or a file with
71 multiple hard links. Usually, only one series file is used for a set
72 of 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 [-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 -p strip-level
257 The number of pathname components to strip from file names when
259 applying patchfile.
260 fork [new_name]
264 Fork the topmost patch. Forking a patch means creating a verbatim
266 copy of it under a new name, and use that new name instead of the
267 original one in the current series. This is useful when a patch
268 has to be modified, but the original version of it should be pre‐
269 served, e.g. because it is used in another series, or for the his‐
270 tory. A typical sequence of commands would be: fork, edit,
271 refresh.
272 If new_name is missing, the name of the forked patch will be the
274 current patch name, followed by `-2'. If the patch name already
275 ends in a dash-and-number, the number is further incremented (e.g.,
276 patch.diff, patch-2.diff, patch-3.diff).
277 graph [--all] [--reduce] [--lines[=num]] [--edge-labels=files] [-T ps]
281 [patch]
282 Generate a dot(1) directed graph showing the dependencies between
284 applied patches. A patch depends on another patch if both touch the
285 same file or, with the --lines option, if their modifications over‐
286 lap. Unless otherwise specified, the graph includes all patches
287 that the topmost patch depends on. When a patch name is specified,
288 instead of the topmost patch, create a graph for the specified
289 patch. The graph will include all other patches that this patch
290 depends on, as well as all patches that depend on this patch.
291 --all
294 Generate a graph including all applied patches and their depen‐
295 dencies. (Unapplied patches are not included.)
296 --reduce
299 Eliminate transitive edges from the graph.
301 --lines[=num]
304 Compute dependencies by looking at the lines the patches mod‐
306 ify. Unless a different num is specified, two lines of context
307 are included.
308 --edge-labels=files
311 Label graph edges with the file names that the adjacent patches
313 modify.
314 -T ps
317 Directly produce a PostScript output file.
318 grep [-h|options] {pattern}
322 Grep through the source files, recursively, skipping patches and
324 quilt meta-information. If no filename argument is given, the whole
325 source tree is searched. Please see the grep(1) manual page for
326 options.
327 -h Print this help. The grep -h option can be passed after a dou‐
330 ble-dash (--). Search expressions that start with a dash can be
331 passed after a second double-dash (-- --).
332 header [-a|-r|-e] [--backup] [--strip-diffstat] [--strip-trailing-
336 whitespace] [patch]
337 Print or change the header of the topmost or specified patch.
339 -a, -r, -e
342 Append to (-a) or replace (-r) the exiting patch header, or
344 edit (-e) the header in $EDITOR. If none of these options is
345 given, print the patch header.
346 --strip-diffstat
349 Strip diffstat output from the header.
351 --strip-trailing-whitespace
354 Strip trailing whitespace at the end of lines of the header.
356 --backup
359 Create a backup copy of the old version of a patch as patch~.
361 import [-p num] [-P patch] [-f] [-d {o|a|n}] patchfile ...
365 Import external patches. The patches will be inserted following
367 the current top patch, and must be pushed after import to apply
368 them.
369 -p num
372 Number of directory levels to strip when applying (default=1)
374 -P patch
377 Patch filename to use inside quilt. This option can only be
379 used when importing a single patch.
380 -f Overwite/update existing patches.
383 -d {o|a|n}
386 When overwriting in existing patch, keep the old (o), all (a),
388 or new (n) patch header. If both patches include headers, this
389 option must be specified. This option is only effective when -f
390 is used.
391 mail {--mbox file|--send} [-m text] [--prefix prefix] [--sender ...]
395 [--from ...] [--to ...] [--cc ...] [--bcc ...] [--subject ...]
396 Create mail messages from all patches in the series file, and
398 either store them in a mailbox file, or send them immediately. The
399 editor is opened with a template for the introduction. Please see
400 /usr/share/doc/quilt-0.46/README.MAIL for details.
401 -m text
404 Text to use as the text in the introduction. When this option
406 is used, the editor will not be invoked, and the patches will
407 be processed immediately.
408 --prefix prefix
411 Use an alternate prefix in the bracketed part of the subjects
413 generated. Defaults to `patch'.
414 --mbox file
417 Store all messages in the specified file in mbox format. The
419 mbox can later be sent using formail, for example.
420 --send
423 Send the messages directly.
425 --sender
428 The envelope sender address to use. The address must be of the
430 form `user@domain.name'. No display name is allowed.
431 --from, --subject
434 The values for the From and Subject headers to use. If no
436 --from option is given, the value of the --sender option is
437 used.
438 --to, --cc, --bcc
441 Append a recipient to the To, Cc, or Bcc header.
443 new {patchname}
447 Create a new patch with the specified file name, and insert it
449 after the topmost patch in the patch series file.
450 Quilt can be used in sub-directories of a source tree. It deter‐
452 mines the root of a source tree by searching for a patches direc‐
453 tory above the current working directory. Create a patches direc‐
454 tory in the intended root directory if quilt chooses a top-level
455 directory that is too high up in the directory tree.
456 next [patch]
460 Print the name of the next patch after the specified or topmost
462 patch in the series file.
463 patches [-v] {file}
467 Print the list of patches that modify the specified file. (Uses a
469 heuristic to determine which files are modified by unapplied
470 patches. Note that this heuristic is much slower than scanning
471 applied patches.)
472 -v Verbose, more user friendly output.
475 pop [-afRqv] [num|patch]
479 Remove patch(es) from the stack of applied patches. Without
481 options, the topmost patch is removed. When a number is specified,
482 remove the specified number of patches. When a patch name is spec‐
483 ified, remove patches until the specified patch end up on top of
484 the stack. Patch names may include the patches/ prefix, which
485 means that filename completion can be used.
486 -a Remove all applied patches.
489 -f Force remove. The state before the patch(es) were applied will
492 be restored from backup files.
493 -R Always verify if the patch removes cleanly; don't rely on time‐
496 stamp checks.
497 -q Quiet operation.
500 -v Verbose operation.
503 previous [patch]
507 Print the name of the previous patch before the specified or top‐
509 most patch in the series file.
510 push [-afqv] [--leave-rejects] [--interactive]
514 [--color[=always|auto|never]] [num|patch]
515 Apply patch(es) from the series file. Without options, the next
517 patch in the series file is applied. When a number is specified,
518 apply the specified number of patches. When a patch name is speci‐
519 fied, apply all patches up to and including the specified patch.
520 Patch names may include the patches/ prefix, which means that file‐
521 name completion can be used.
522 -a Apply all patches in the series file.
525 -f Force apply, even if the patch has rejects.
528 -q Quiet operation.
531 -v Verbose operation.
534 --leave-rejects
537 Leave around the reject files patch produced, even if the patch
539 is not actually applied.
540 --interactive
543 Allow the patch utility to ask how to deal with conflicts. If
545 this option is not given, the -f option will be passed to the
546 patch program.
547 --color[=always|auto|never]
550 Use syntax coloring.
552 refresh [-p n|-p ab] [-u|-U num|-c|-C num] [-f] [--no-timestamps]
556 [--no-index] [--diffstat] [--sort] [--backup] [--strip-trailing-white‐
557 space] [patch]
558 Refreshes the specified patch, or the topmost patch by default.
560 Documentation that comes before the actual patch in the patch file
561 is retained.
562 It is possible to refresh patches that are not on top. If any
564 patches on top of the patch to refresh modify the same files, the
565 script aborts by default. Patches can still be refreshed with -f.
566 In that case this script will print a warning for each shadowed
567 file, changes by more recent patches will be ignored, and only
568 changes in files that have not been modified by any more recent
569 patches will end up in the specified patch.
570 -p n
573 Create a -p n style patch (-p0 or -p1 supported).
574 -p ab
577 Create a -p1 style patch, but use a/file and b/file as the
578 original and new filenames instead of the default dir.orig/file
579 and dir/file names.
580 -u, -U num, -c, -C num
583 Create a unified diff (-u, -U) with num lines of context. Cre‐
585 ate a context diff (-c, -C) with num lines of context. The num‐
586 ber of context lines defaults to 3.
587 --no-timestamps
590 Do not include file timestamps in patch headers.
592 --no-index
595 Do not output Index: lines.
597 --diffstat
600 Add a diffstat section to the patch header, or replace the
602 existing diffstat section.
603 -f Enforce refreshing of a patch that is not on top.
606 --backup
609 Create a backup copy of the old version of a patch as patch~.
611 --sort
614 Sort files by their name instead of preserving the original
615 order.
616 --strip-trailing-whitespace
619 Strip trailing whitespace at the end of lines.
621 remove [-P patch] {file} ...
625 Remove one or more files from the topmost or named patch. Files
627 that are modified by patches on top of the specified patch cannot
628 be removed.
629 -P patch
632 Remove named files from the named patch.
634 rename [-P patch] new_name
638 Rename the topmost or named patch.
640 -P patch
643 Patch to rename.
645 series [-v]
649 Print the names of all patches in the series file.
651 -v Verbose, more user friendly output.
654 setup [-d path-prefix] [-v] [--path dir1:dir2] {specfile|seriesfile}
658 Initializes a source tree from an rpm spec file or a quilt series
660 file.
661 -d Optional path prefix.
664 --path
667 Directories to search when looking for tarballs. Defaults to
668 `.'.
669 -v Verbose debug output.
672 snapshot [-d]
676 Take a snapshot of the current working state. After taking the
678 snapshot, the tree can be modified in the usual ways, including
679 pushing and popping patches. A diff against the tree at the moment
680 of the snapshot can be generated with `quilt diff --snapshot'.
681 -d Only remove current snapshot.
684 top
688 Print the name of the topmost patch on the current stack of applied
690 patches.
691 unapplied [patch]
695 Print a list of patches that are not applied, or all patches that
697 follow the specified patch in the series file.
698 upgrade
702 Upgrade the meta-data in a working tree from an old version of
704 quilt to the current version. This command is only needed when the
705 quilt meta-data format has changed, and the working tree still con‐
706 tains old-format meta-data. In that case, quilt will request to run
707 `quilt upgrade'.
708
712 --trace
713 Runs the command in bash trace mode (-x). For internal debug‐
715 ging.
716 --quiltrc file
719 Use the specified configuration file instead of ~/.quiltrc (or
721 /etc/quilt.quiltrc if ~/.quiltrc does not exist). See the pdf
722 documentation for details about its possible contents. The
723 special value "-" causes quilt not to read any configuration
724 file.
725 --version
728 Print the version number and exit immediately.
730
734 work/ -+- ...
735 |- patches/ -+- series
736 | |- patch2.diff
737 | |- patch1.diff
738 | +- ...
739 +- .pc/ -+- applied-patches
740 |- patch1.diff/ -+- ...
741 |- patch2.diff/ -+- ...
742 +- ...
743
746 Please refer to the pdf documentation for an example.
747
750 Upon startup, quilt evaluates the file .quiltrc in the user's home
751 directory, or the file specified with the --quiltrc option. This file
752 is a regular bash script. Default options can be passed to any command
753 by defining a QUILT_COMMAND_ARGS variable. For example,
754 QUILT_DIFF_ARGS="--color=auto" causes the output of quilt diff to be
755 syntax colored when writing to a terminal.
756 In addition to that, quilt recognizes the following variables:
758 QUILT_DIFF_OPTS
761 Additional options that quilt shall pass to GNU diff when generat‐
763 ing patches. A useful setting for C source code is "-p", which
764 causes GNU diff to show in the resulting patch which function a
765 change is in.
766 QUILT_PATCH_OPTS
769 Additional options that quilt shall pass to GNU patch when applying
771 patches. For example, some versions of GNU patch support the
772 "--unified-reject-files" option for generating reject files in uni‐
773 fied diff style.
774 QUILT_DIFFSTAT_OPTS
777 Additional options that quilt shall pass to diffstat when generat‐
779 ing patch statistics. For example, "-f0" can be used for an alter‐
780 native output format. Recent versions of diffstat also support
781 alternative rounding methods ("-r1", "-r2").
782 QUILT_PATCHES
785 The location of patch files, defaulting to "patches".
787 QUILT_PATCHES_PREFIX
790 If set to anything, quilt will prefix patch names it prints with
792 their directory (QUILT_PATCHES).
793 QUILT_NO_DIFF_INDEX
796 By default, quilt prepends an Index: line to the patches it gener‐
798 ates. If this variable is set to anything, no line is prepended.
799 This is a shortcut to adding --no-index to both QUILT_DIFF_ARGS and
800 QUILT_REFRESH_ARGS.
801 QUILT_NO_DIFF_TIMESTAMP
804 By default, quilt includes timestamps in headers when generating
806 patches. If this variable is set to anything, no timestamp will be
807 included. This is a shortcut to adding --no-timestamps to both
808 QUILT_DIFF_ARGS and QUILT_REFRESH_ARGS.
809 EDITOR
812 The program to run to edit files. If it isn't redefined in the
814 configuration file, $EDITOR as defined in the environment will be
815 used.
816
819 Quilt started as a series of scripts written by Andrew Morton (patch-
820 scripts). Based on Andrew's ideas, Andreas Gruenbacher completely
821 rewrote the scripts, with the help of several other contributors (see
822 AUTHORS file in the distribution).
823 This man page was written by Martin Quinson, based on information found
825 in the pdf documentation, and in the help messages of each commands.
826
829 The pdf documentation, which should be under
830 /usr/share/doc/quilt/quilt.pdf. Note that some distributors compress
831 this file. zxpdf(1) can be used to display compressed pdf files.
832 diff(1), patch(1).
834quilt June 2, 2006 quilt(1)