quilt - tool to manage series of patches
quilt [-h] command [options]
quilt(1) General Commands Manual quilt(1)
NAME
quilt - tool to manage series of patches
SYNOPSIS
quilt [-h] command [options]
DESCRIPTION
Quilt is a tool to manage large sets of patches by keeping track of the
changes each patch makes. Patches can be applied, un-applied,
refreshed, etc. The key philosophical concept is that your primary out-
put is patches.
With quilt, all work occurs within a single directory tree. Commands
can be be invoked from anywhere within the source tree. They are of the
form quilt cmd similar to CVS commands. They can be abbreviated as long
as the specified part of the command is unique. All commands print some
help text with quilt cmd -h.
Quilt manages a stack of patches. Patches are applied incrementally on
top of the base tree plus all preceding patches. They can be pushed on
top of the stack (quilt push), and popped off the stack (quilt pop).
Commands are available for querying the contents of the series file
(quilt series, see below), the contents of the stack (quilt applied,
quilt previous, quilt top), and the patches that are not applied at a
particular moment (quilt next, quilt unapplied). By default, most com-
mands apply to the topmost patch on the stack.
Patch files are located in the patches sub-directory of the source tree
(see EXAMPLE OF WORKING TREE below). The QUILT_PATCHES environment
variable can be used to override this location. The patches directory
may contain sub-directories. It may also be a symbolic link instead of
a directory.
A file called series contains a list of patch file names that defines
the order in which patches are applied. Unless there are means by which
series files can be generated automatically, it is usually provided
along with a set of patches. In this file, each patch file name is on a
separate line. Patch files are identified by pathnames that are rela-
tive to the patches directory; patches may be in sub-directories below
this directory. Lines in the series file that start with a hash charac-
ter (#) are ignored. You can also add a comment after each patch file
name, introduced by a space followed by a hash character. When quilt
adds, removes, or renames patches, it automatically updates the series
file. Users of quilt can modify series files while some patches are
applied, as long as the applied patches remain in their original order.
Different series files can be used to assemble patches in different
ways, corresponding for example to different development branches.
Before a patch is applied (or ``pushed on the stack''), copies of all
files the patch modifies are saved to the .pc/patch directory. The
patch is added to the list of currently applied patches (.pc/applied-
patches). Later when a patch is regenerated (quilt refresh), the backup
copies in .pc/patch are compared with the current versions of the files
in the source tree using GNU diff.
Documentation related to a patch can be put at the beginning of a patch
file. Quilt is careful to preserve all text that precedes the actual
patch when doing a refresh. (This is limited to patches in unified for-
mat; see diff documentation).
The series file is looked up in the .pc directory, in the root of the
source tree, and in the patches directory. The first series file that
is found is used. This may also be a symbolic link, or a file with mul-
tiple hard links. Usually, only one series file is used for a set of
patches, so the patches sub-directory is a convenient location.
The .pc directory and its sub-directories cannot be relocated, but it
can be a symbolic link. While patches are applied to the source tree,
this directory is essential for many operations, including taking
patches off the stack (quilt pop), and refreshing patches (quilt
refresh). Files in the .pc directory are automatically removed when
they are no longer needed, so there is no need to clean up manually.
QUILT COMMANDS REFERENCE
graph [--all] [--reduce] [--lines[=num]] [--edge-labels=files] [-T ps]
[patch]
Generate a dot(1) directed graph showing the dependencies between
applied patches. A patch depends on another patch if both touch the
same file or, with the --lines option, if their modifications over-
lap. Unless otherwise specified, the graph includes all patches
that the topmost patch depends on. When a patch name is specified,
instead of the topmost patch, create a graph for the specified
patch. The graph will include all other patches that this patch
depends on, as well as all patches that depend on this patch.
--all
Generate a graph including all applied patches and their depen-
dencies. (Unapplied patches are not included.)
--reduce
Eliminate transitive edges from the graph.
--lines[=num]
Compute dependencies by looking at the lines the patches mod-
ify. Unless a different num is specified, two lines of context
are included.
--edge-labels=files
Label graph edges with the file names that the adjacent patches
modify.
-T ps
Directly produce a PostScript output file.
unapplied [patch]
Print a list of patches that are not applied, or all patches that
follow the specified patch in the series file.
next [patch]
Print the name of the next patch after the specified or topmost
patch in the series file.
rename [-P patch] new_name
Rename the topmost or named patch.
-P patch
Patch to rename.
setup [-d path-prefix] [-v] [--sourcedir dir] [--fuzz=N] {spec-
file|seriesfile}
Initializes a source tree from an rpm spec file or a quilt series
file.
-d Optional path prefix for the resulting source tree.
--sourcedir
Directory that contains the package sources. Defaults to `.'.
-v Verbose debug output.
--fuzz=N
Set the maximum fuzz factor (needs rpm 4.6 or later).
push [-afqv] [--merge[=merge|diff3]] [--leave-rejects]
[--color[=always|auto|never]] [num|patch]
Apply patch(es) from the series file. Without options, the next
patch in the series file is applied. When a number is specified,
apply the specified number of patches. When a patch name is speci-
fied, apply all patches up to and including the specified patch.
Patch names may include the patches/ prefix, which means that file-
name completion can be used.
-a Apply all patches in the series file.
-q Quiet operation.
-f Force apply, even if the patch has rejects. Unless in quiet
mode, apply the patch interactively: the patch utility may ask
questions.
-v Verbose operation.
--fuzz=N
Set the maximum fuzz factor (default: 2).
-m, --merge[=merge|diff3]
Merge the patch file into the original files (see patch(1)).
--leave-rejects
Leave around the reject files patch produced, even if the patch
is not actually applied.
--color[=always|auto|never]
Use syntax coloring.
snapshot [-d]
Take a snapshot of the current working state. After taking the
snapshot, the tree can be modified in the usual ways, including
pushing and popping patches. A diff against the tree at the moment
of the snapshot can be generated with `quilt diff --snapshot'.
-d Only remove current snapshot.
patches [-v] {file}
Print the list of patches that modify the specified file. (Uses a
heuristic to determine which files are modified by unapplied
patches. Note that this heuristic is much slower than scanning
applied patches.)
-v Verbose, more user friendly output.
delete [-r] [--backup] [patch|-n]
Remove the specified or topmost patch from the series file. If the
patch is applied, quilt will attempt to remove it first. (Only the
topmost patch can be removed right now.)
-n Delete the next patch after topmost, rather than the specified
or topmost patch.
-r Remove the deleted patch file from the patches directory as
well.
--backup
Rename the patch file to patch~ rather than deleting it.
Ignored if not used with `-r'.
series [-v]
Print the names of all patches in the series file.
-v Verbose, more user friendly output.
applied [patch]
Print a list of applied patches, or all patches up to and including
the specified patch in the file series.
previous [patch]
Print the name of the previous patch before the specified or top-
most patch in the series file.
import [-p num] [-R] [-P patch] [-f] [-d {o|a|n}] patchfile ...
Import external patches. The patches will be inserted following
the current top patch, and must be pushed after import to apply
them.
-p num
Number of directory levels to strip when applying (default=1)
-R
Apply patch in reverse.
-P patch
Patch filename to use inside quilt. This option can only be
used when importing a single patch.
-f Overwrite/update existing patches.
-d {o|a|n}
When overwriting in existing patch, keep the old (o), all (a),
or new (n) patch header. If both patches include headers, this
option must be specified. This option is only effective when -f
is used.
new [-p n|-p ab] {patchname}
Create a new patch with the specified file name, and insert it
after the topmost patch. The name can be prefixed with a sub-direc-
tory name, allowing for grouping related patches together.
-p n
Create a -p n style patch (-p0 or -p1 are supported).
-p ab
Create a -p1 style patch, but use a/file and b/file as the
original and new filenames instead of the default dir.orig/file
and dir/file names.
Quilt can be used in sub-directories of a source tree. It
determines the root of a source tree by searching for a patches
directory above the current working directory. Create a patches
directory in the intended root directory if quilt chooses a
top-level directory that is too high up in the directory tree.
add [-P patch] {file} ...
Add one or more files to the topmost or named patch. Files must be
added to the patch before being modified. Files that are modified
by patches already applied on top of the specified patch cannot be
added.
-P patch
Patch to add files to.
fork [new_name]
Fork the topmost patch. Forking a patch means creating a verbatim
copy of it under a new name, and use that new name instead of the
original one in the current series. This is useful when a patch
has to be modified, but the original version of it should be pre-
served, e.g. because it is used in another series, or for the his-
tory. A typical sequence of commands would be: fork, edit,
refresh.
If new_name is missing, the name of the forked patch will be the
current patch name, followed by `-2'. If the patch name already
ends in a dash-and-number, the number is further incremented (e.g.,
patch.diff, patch-2.diff, patch-3.diff).
mail {--mbox file|--send} [-m text] [-M file] [--prefix prefix]
[--sender ...] [--from ...] [--to ...] [--cc ...] [--bcc ...] [--sub-
ject ...] [--reply-to message] [first_patch [last_patch]]
Create mail messages from a specified range of patches, or all
patches in the series file, and either store them in a mailbox
file, or send them immediately. The editor is opened with a tem-
plate for the introduction. Please see
/usr/share/doc/quilt/README.MAIL for details. When specifying a
range of patches, a first patch name of `-' denotes the first, and
a last patch name of `-' denotes the last patch in the series.
-m text
Text to use as the text in the introduction. When this option
is used, the editor will not be invoked, and the patches will
be processed immediately.
-M file
Like the -m option, but read the introduction from file.
--prefix prefix
Use an alternate prefix in the bracketed part of the subjects
generated. Defaults to `patch'.
--mbox file
Store all messages in the specified file in mbox format. The
mbox can later be sent using formail, for example.
--send
Send the messages directly.
--sender
The envelope sender address to use. The address must be of the
form `user@domain.name'. No display name is allowed.
--from, --subject
The values for the From and Subject headers to use. If no
--from option is given, the value of the --sender option is
used.
--to, --cc, --bcc
Append a recipient to the To, Cc, or Bcc header.
--signature file
Append the specified signature to messages (defaults to ~/.sig-
nature if found; use `-' for no signature).
--reply-to message
Add the appropriate headers to reply to the specified message.
annotate [-P patch] {file}
Print an annotated listing of the specified file showing which
patches modify which lines. Only applied patches are included.
-P patch
Stop checking for changes at the specified rather than the top-
most patch.
edit file ...
Edit the specified file(s) in $EDITOR after adding it (them) to the
topmost patch.
pop [-afRqv] [num|patch]
Remove patch(es) from the stack of applied patches. Without
options, the topmost patch is removed. When a number is specified,
remove the specified number of patches. When a patch name is spec-
ified, remove patches until the specified patch end up on top of
the stack. Patch names may include the patches/ prefix, which
means that filename completion can be used.
-a Remove all applied patches.
-f Force remove. The state before the patch(es) were applied will
be restored from backup files.
-R Always verify if the patch removes cleanly; don't rely on time-
stamp checks.
-q Quiet operation.
-v Verbose operation.
diff [-p n|-p ab] [-u|-U num|-c|-C num] [--combine patch|-z] [-R] [-P
patch] [--snapshot] [--diff=utility] [--no-timestamps] [--no-index]
[--sort] [--color] [file ...]
Produces a diff of the specified file(s) in the topmost or speci-
fied patch. If no files are specified, all files that are modified
are included.
-p n
Create a -p n style patch (-p0 or -p1 are supported).
-p ab
Create a -p1 style patch, but use a/file and b/file as the
original and new filenames instead of the default dir.orig/file
and dir/file names.
-u, -U num, -c, -C num
Create a unified diff (-u, -U) with num lines of context. Cre-
ate a context diff (-c, -C) with num lines of context. The num-
ber of context lines defaults to 3.
--no-timestamps
Do not include file timestamps in patch headers.
--no-index
Do not output Index: lines.
-z Write to standard output the changes that have been made rela-
tive to the topmost or specified patch.
-R Create a reverse diff.
-P patch
Create a diff for the specified patch. (Defaults to the top-
most patch.)
--combine patch
Create a combined diff for all patches between this patch and
the patch specified with -P. A patch name of `-' is equivalent
to specifying the first applied patch.
--snapshot
Diff against snapshot (see `quilt snapshot -h').
--diff=utility
Use the specified utility for generating the diff. The utility
is invoked with the original and new file name as arguments.
--color[=always|auto|never]
Use syntax coloring.
--sort
Sort files by their name instead of preserving the original
order.
top
Print the name of the topmost patch on the current stack of applied
patches.
remove [-P patch] {file} ...
Remove one or more files from the topmost or named patch. Files
that are modified by patches on top of the specified patch cannot
be removed.
-P patch
Remove named files from the named patch.
header [-a|-r|-e] [--backup] [--strip-diffstat] [--strip-trailing-
whitespace] [patch]
Print or change the header of the topmost or specified patch.
-a, -r, -e
Append to (-a) or replace (-r) the exiting patch header, or
edit (-e) the header in $EDITOR. If none of these options is
given, print the patch header.
--strip-diffstat
Strip diffstat output from the header.
--strip-trailing-whitespace
Strip trailing whitespace at the end of lines of the header.
--backup
Create a backup copy of the old version of a patch as patch~.
revert [-P patch] {file} ...
Revert uncommitted changes to the topmost or named patch for the
specified file(s): after the revert, 'quilt diff -z' will show no
differences for those files. Changes to files that are modified by
patches on top of the specified patch cannot be reverted.
-P patch
Revert changes in the named patch.
files [-v] [-a] [-l] [--combine patch] [patch]
Print the list of files that the topmost or specified patch
changes.
-a List all files in all applied patches.
-l Add patch name to output.
-v Verbose, more user friendly output.
--combine patch
Create a listing for all patches between this patch and the
topmost or specified patch. A patch name of `-' is equivalent
to specifying the first applied patch.
fold [-R] [-q] [-f] [-p strip-level]
Integrate the patch read from standard input into the topmost
patch: After making sure that all files modified are part of the
topmost patch, the patch is applied with the specified strip level
(which defaults to 1).
-R Apply patch in reverse.
-q Quiet operation.
-f Force apply, even if the patch has rejects. Unless in quiet
mode, apply the patch interactively: the patch utility may ask
questions.
-p strip-level
The number of pathname components to strip from file names when
applying patchfile.
refresh [-p n|-p ab] [-u|-U num|-c|-C num] [-z[new_name]] [-f] [--no-
timestamps] [--no-index] [--diffstat] [--sort] [--backup] [--strip-
trailing-whitespace] [patch]
Refreshes the specified patch, or the topmost patch by default.
Documentation that comes before the actual patch in the patch file
is retained.
It is possible to refresh patches that are not on top. If any
patches on top of the patch to refresh modify the same files, the
script aborts by default. Patches can still be refreshed with -f.
In that case this script will print a warning for each shadowed
file, changes by more recent patches will be ignored, and only
changes in files that have not been modified by any more recent
patches will end up in the specified patch.
-p n
Create a -p n style patch (-p0 or -p1 supported).
-p ab
Create a -p1 style patch, but use a/file and b/file as the
original and new filenames instead of the default dir.orig/file
and dir/file names.
-u, -U num, -c, -C num
Create a unified diff (-u, -U) with num lines of context. Cre-
ate a context diff (-c, -C) with num lines of context. The num-
ber of context lines defaults to 3.
-z[new_name]
Create a new patch containing the changes instead of refreshing
the topmost patch. If no new name is specified, `-2' is added
to the original patch name, etc. (See the fork command.)
--no-timestamps
Do not include file timestamps in patch headers.
--no-index
Do not output Index: lines.
--diffstat
Add a diffstat section to the patch header, or replace the
existing diffstat section.
-f Enforce refreshing of a patch that is not on top.
--backup
Create a backup copy of the old version of a patch as patch~.
--sort
Sort files by their name instead of preserving the original
order.
--strip-trailing-whitespace
Strip trailing whitespace at the end of lines.
upgrade
Upgrade the meta-data in a working tree from an old version of
quilt to the current version. This command is only needed when the
quilt meta-data format has changed, and the working tree still con-
tains old-format meta-data. In that case, quilt will request to run
`quilt upgrade'.
grep [-h|options] {pattern}
Grep through the source files, recursively, skipping patches and
quilt meta-information. If no filename argument is given, the whole
source tree is searched. Please see the grep(1) manual page for
options.
-h Print this help. The grep -h option can be passed after a dou-
ble-dash (--). Search expressions that start with a dash can be
passed after a second double-dash (-- --).
COMMON OPTIONS TO ALL COMMANDS
B--traceP
Runs the command in bash trace mode (-x). For internal debug-
ging.
B--quiltrcP file
Use the specified configuration file instead of ~/.quiltrc (or
/etc/quilt.quiltrc if ~/.quiltrc does not exist). See the pdf
documentation for details about its possible contents. The
special value "-" causes quilt not to read any configuration
file.
B--versionP
Print the version number and exit immediately.
EXAMPLE OF WORKING TREE
work/ -+- ...
|- patches/ -+- series
| |- patch2.diff
| |- patch1.diff
| +- ...
+- .pc/ -+- applied-patches
|- patch1.diff/ -+- ...
|- patch2.diff/ -+- ...
+- ...
EXAMPLE
Please refer to the pdf documentation for an example.
CONFIGURATION FILE
Upon startup, quilt evaluates the file .quiltrc in the user's home
directory, or the file specified with the --quiltrc option. This file
is a regular bash script. Default options can be passed to any COMMAND
by defining a QUILT_${COMMAND}_ARGS variable. For example,
QUILT_DIFF_ARGS="--color=auto" causes the output of quilt diff to be
syntax colored when writing to a terminal.
In addition to that, quilt recognizes the following variables:
QUILT_DIFF_OPTS
Additional options that quilt shall pass to GNU diff when generat-
ing patches. A useful setting for C source code is "-p", which
causes GNU diff to show in the resulting patch which function a
change is in.
QUILT_PATCH_OPTS
Additional options that quilt shall pass to GNU patch when applying
patches. For example, recent versions of GNU patch support the
"--reject-format=unified" option for generating reject files in
unified diff style (older patch versions used "--unified-reject-
files" for that).
QUILT_DIFFSTAT_OPTS
Additional options that quilt shall pass to diffstat when generat-
ing patch statistics. For example, "-f0" can be used for an alter-
native output format. Recent versions of diffstat also support
alternative rounding methods ("-r1", "-r2").
QUILT_PATCHES
The location of patch files, defaulting to "patches".
QUILT_SERIES
The name of the series file, defaulting to "series". Unless an
absolute path is used, the search algorithm described above
applies.
QUILT_PATCHES_PREFIX
If set to anything, quilt will prefix patch names it prints with
their directory (QUILT_PATCHES).
QUILT_NO_DIFF_INDEX
By default, quilt prepends an Index: line to the patches it gener-
ates. If this variable is set to anything, no line is prepended.
This is a shortcut to adding --no-index to both QUILT_DIFF_ARGS and
QUILT_REFRESH_ARGS.
QUILT_NO_DIFF_TIMESTAMPS
By default, quilt includes timestamps in headers when generating
patches. If this variable is set to anything, no timestamp will be
included. This is a shortcut to adding --no-timestamps to both
QUILT_DIFF_ARGS and QUILT_REFRESH_ARGS.
QUILT_PAGER
The pager quilt shall use for commands which produce paginated out-
put. If unset, the values of GIT_PAGER or PAGER is used. If none
of these variables is set, "less" is used. An empty value indi-
cates that no pager should be used.
EDITOR
The program to run to edit files. If it isn't redefined in the
configuration file, $EDITOR as defined in the environment will be
used.
AUTHORS
Quilt started as a series of scripts written by Andrew Morton (patch-
scripts). Based on Andrew's ideas, Andreas Gruenbacher completely
rewrote the scripts, with the help of several other contributors (see
AUTHORS file in the distribution).
This man page was written by Martin Quinson, based on information found
in the pdf documentation, and in the help messages of each commands.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | developer/quilt |
+---------------+------------------+
|Stability | Uncommitted |
+---------------+------------------+
SEE ALSO
The pdf documentation, which should be under
/usr/share/doc/quilt/quilt.pdf. Note that some distributors compress
this file. zxpdf(1) can be used to display compressed pdf files.
diff(1), patch(1).
NOTES
This software was built from source available at
https://java.net/projects/solaris-userland. The original community
source was downloaded from http://download.savan-
nah.gnu.org/releases/quilt/quilt-0.60.tar.gz
Further information about this software can be found on the open source
community website at http://savannah.nongnu.org/projects/quilt/.
quilt June 2, 2006 quilt(1)