| quilt(1) | General Commands Manual | quilt(1) |
quilt - manage a series of patches
quilt |
[--quiltrc file] [--trace] command [options] |
quilt |
[command] -h |
quilt --version |
Quilt is a tool to manage large sets of patches by keeping track of the changes each patch makes. Patches can be applied, unapplied, refreshed, and so forth. The key philosophical concept is that your primary working material is patches.
With quilt, all work occurs within a single directory tree. Commands can be invoked from anywhere within the source tree. Like CVS, Subversion, or Git, quilt takes commands of the form “quilt command”. A command can be truncated (abbreviated) as long as the specified part of the command is unambiguous. If command is ambiguously short, quilt lists all commands matching that prefix and exits. All commands print a brief contextual help message and exit if given the “-h” option.
Quilt manages a stack of patches. Patches are applied incrementally on top of the base tree plus all preceding patches. They can be pushed onto the stack (“quilt push”), and popped off the stack (“quilt pop”). Commands are available for querying 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 commands apply to the topmost patch on the stack.
Patch files are located in the patches subdirectory of the source tree (see Example of working tree, under FILES, below). The QUILT_PATCHES environment variable overrides this default location. When not found in the current directory, that subdirectory is searched recursively in the parent directories (this is similar to the way Git searches for its configuration files). The patches directory may contain subdirectories. It may also be a symbolic link instead of a directory.
Quilt creates and maintains a file called series, which defines the order in which patches are applied. The QUILT_SERIES environment variable overrides this default name. You can query the contents of the series file at any time with “quilt series”. In this file, each patch file name is on a separate line. Patch files are identified by path names that are relative to the patches directory; patches may be in subdirectories below this directory. Lines in the series file that start with a hash character (#) are ignored. Patch options, such as the strip level or whether the patch is reversed, can be added after each patch file name. Options are introduced by a space, separated by spaces, and follow the syntax of the patch(1) options (e.g., “-p2”). Quilt records patch options automatically when a command supporting them is used. Without options, strip level 1 is assumed. You can also add a comment after each patch file name and options, 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. Unless there are means by which a series file can be generated automatically, you should provide it along with any set of quilt-managed patches you distribute. Different series files can be used to assemble patches in different ways, corresponding (for example) to different development branches.
Before a patch is applied, copies of all files the patch modifies are saved to the .pc/patch-name directory, where patch-name is the name of the patch (for example, fix-buffer-overflow.patch). 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-name are compared with the current versions of the files in the source tree using GNU diff(1).
A similar process occurs when starting a new patch (“quilt new”); the new patch file name is added to the series file. A file to be changed by the patch is backed up and opened for editing (“quilt edit”). After editing, inspect the impact of your changes (“quilt diff”); the changes stay local to your working tree until you call “quilt refresh” to write them to the patch file.
Documentation related to a patch can be put at the beginning of its patch file (“quilt header”). Quilt is careful to preserve all text that precedes the actual patch when doing a refresh. (This is limited to patches in unified format; see the GNU Diffutils manual.)
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 multiple hard links. Usually, only one series file is used for a set of patches, making the patches subdirectory a convenient location.
The .pc directory cannot be relocated, but it can be a symbolic link. Its subdirectories must not be renamed or restructured. While patches are applied to the source tree, this directory is essential for many operations, including popping patches off the stack and refreshing them. Files in the .pc directory are automatically removed when they are no longer needed, so there is no need to clean up manually.
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.
Patch to add files to.
Print an annotated listing of the specified file showing which patches modify which lines. Only applied patches are included.
Stop checking for changes at the specified rather than the topmost patch.
Print a list of applied patches, or all patches up to and including the specified patch in the file series.
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.)
Rename the patch file to patch~ rather than deleting it. Ignored if not used with `-r'.
Produces a diff of the specified file(s) in the topmost or specified patch. If no files are specified, all files that are modified are included.
Create a unified diff (-u, -U) with num lines of context. Create a context diff (-c, -C) with num lines of context. The number of context lines defaults to 3.
Do not include file timestamps in patch headers.
Do not output Index: lines.
Create a diff for the specified patch. (Defaults to the topmost 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.
Diff against snapshot (see `quilt snapshot -h').
Use the specified utility for generating the diff. The utility is invoked with the original and new file name as arguments.
Use syntax coloring (auto activates it only if the output is a tty).
Edit the specified file(s) in $EDITOR after adding it (them) to the topmost patch.
Print the list of files that the topmost or specified patch changes.
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.
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).
The number of pathname components to strip from file names when applying patchfile.
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 preserved, e.g. because it is used in another series, or for the history. 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).
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 overlap. 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.
Eliminate transitive edges from the graph.
Compute dependencies by looking at the lines the patches modify. Unless a different num is specified, two lines of context are included.
Label graph edges with the file names that the adjacent patches modify.
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.
Print or change the header of the topmost or specified patch.
Append to (-a) or replace (-r) the existing patch header, or edit (-e) the header in $EDITOR. If none of these options is given, print the patch header.
Strip diffstat output from the header.
Strip trailing whitespace at the end of lines of the header.
Create a backup copy of the old version of a patch as patch~.
When editing (-e), insert a template with DEP-3 headers. DEP-3 is http://dep.debian.net/deps/dep3/ Patch Tagging Guidelines.
Import external patches. The patches will be inserted following the current top patch, and must be pushed after import to apply them.
Number of directory levels to strip when applying (default=1)
Apply patch in reverse.
Patch filename to use inside quilt. This option can only be used when importing a single patch.
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.
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 template 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.
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.
Like the -m option, but read the introduction from file.
Use an alternate prefix in the bracketed part of the subjects generated. Defaults to `patch'.
Store all messages in the specified file in mbox format. The mbox can later be sent using formail, for example.
Send the messages directly.
The envelope sender address to use. The address must be of the form `user@domain.name'. No display name is allowed.
The values for the From and Subject headers to use. If no --from option is given, the value of the --sender option is used.
Append a recipient to the To, Cc, or Bcc header.
Specify a particular message encoding on systems which don't use UTF-8 or ISO-8859-15. This character encoding must match the one used in the patches.
Append the specified signature to messages (defaults to ~/.signature if found; use `-' for no signature).
Add the appropriate headers to reply to the specified message.
Create a new patch with the specified file name, and insert it after the topmost patch. The name can be prefixed with a sub-directory name, allowing for grouping related patches together.
Quilt can be used in sub-directories of a source tree. It determines the root of a source tree by searching for a directory above the current working directory. Create a directory in the intended root directory if quilt chooses a top-level directory that is too high up in the directory tree.
Print the name of the next patch after the specified or topmost patch in the series file.
Print the list of patches that modify any of the specified files. (Uses a heuristic to determine which files are modified by unapplied patches. Note that this heuristic is much slower than scanning applied patches.)
Use syntax coloring (auto activates it only if the output is a tty).
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 specified, 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.
Automatically refresh every patch before it gets unapplied.
Print the name of the previous patch before the specified or topmost patch in the series file.
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 specified, apply all patches up to and including the specified patch. Patch names may include the patches/ prefix, which means that filename completion can be used. The mtime of all touched files will be exactly the same to prevent time skews.
Set the maximum fuzz factor (default: 2).
Merge the patch file into the original files (see patch(1)).
Leave around the reject files patch produced, even if the patch is not actually applied.
Use syntax coloring (auto activates it only if the output is a tty).
Automatically refresh every patch after it was successfully applied.
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.
Create a unified diff (-u, -U) with num lines of context. Create a context diff (-c, -C) with num lines of context. The number of context lines defaults to 3.
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.)
Do not include file timestamps in patch headers.
Do not output Index: lines.
Add a diffstat section to the patch header, or replace the existing diffstat section.
Create a backup copy of the old version of a patch as patch~.
Strip trailing whitespace at the end of lines.
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.
Remove named files from the named patch.
Rename the topmost or named patch.
Patch to rename.
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.
Revert changes in the named patch.
Print the names of all patches in the series file.
Use syntax coloring (auto activates it only if the output is a tty).
Initializes a source tree from an rpm spec file or a quilt series file.
Directory that contains the package sources. Defaults to `.'.
Set the maximum fuzz factor (needs rpm 4.6 or later).
The setup command is only guaranteed to work properly on spec files where applying all the patches is the last thing done in the %prep section. This is a design limitation due to the fact that quilt can only operate on patches. If other commands in the %prep section modify the patched files, they must come first, otherwise you won't be able to push the patch series.
For example, a %prep section where you first unpack a tarball, then apply patches, and lastly perform a tree-wide string substitution, is not OK. For "quilt setup" to work, it would have to be changed to unpacking the tarball, then performing the tree-wide string substitution, and lastly applying the patches.
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'.
Print the name of the topmost patch on the current stack of applied patches.
Print a list of patches that are not applied, or all patches that follow the specified patch in the series file.
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 contains old-format meta-data. In that case, quilt will request to run `quilt upgrade'.
These options are common to all quilt commands.
The exit status is 0 if the requested operation completed successfully, or 1 in case of error.
An exit status of 2 indicates that quilt did not do anything to complete the command. This happens in particular when asking quilt to push when the whole stack is already pushed, or to pop when the whole stack is already popped. This behavior is intended to ease scripting with quilt.
Quilt recognizes the following variables:
project-1.2.3/ ├── patches/ │ ├── series (list of patches to apply) │ ├── patch1.diff (one particular patch) │ ├── patch2.diff │ └── ... ├── .pc/ │ ├── .quilt_patches (content of QUILT_PATCHES) │ ├── .quilt_series (content of QUILT_SERIES) │ ├── patch1.diff/ (copy of patched files) │ │ └── ... │ ├── patch2.diff/ │ │ └── ... │ └── ... └── ...
The patches directory is precious as it contains all your patches as well as the order in which they should be applied.
The .pc directory contains metadata about the current state of your patch series. Changing its content is not advised. This directory can usually be regenerated from the initial files and the content of the patches directory (provided that all patches were regenerated before the removal).
Upon startup, quilt evaluates the file specified with the “--quiltrc” option; if that option is not given, the file .quiltrc in the user's home directory is used, and if that does not exist, /etc/quilt.quiltrc is read. This file is a bash(1) script. EDITOR and LESS can be overridden here if desired; see ENVIRONMENT, above.
Define a variable of the form QUILT_COMMAND_ARGS to specify default options to be passed to any quilt command (in uppercase). For example,
QUILT_DIFF_ARGS="--color=auto"
| format-name | command | context | default |
| diff_add | diff | added lines | 36 (cyan) |
| diff_cctx | diff | asterisk sequences | 33 (yellow) |
| diff_ctx | diff | text after hunk | 35 (magenta) |
| diff_hdr | diff | index line | 32 (green) |
| diff_hunk | diff | hunk header | 33 (yellow) |
| diff_mod | diff | modified lines | 35 (magenta) |
| diff_rem | diff | removed lines | 35 (magenta) |
| patch_fail | push | failure message | 31 (red) |
| patch_fuzz | push | fuzz information | 35 (magenta) |
| patch_offs | push | offset information | 33 (yellow) |
| series_app | series | applied patch names | 32 (green) |
| series_top | series | top patch name | 33 (yellow) |
| series_una | series | unapplied patch names | 0 (none) |
QUILT_DIFF_ARGS="--color" # Render diff file headers in bold blue over yellow. # Render diff hunk headers in "negative image" yellow. # Render failed patches with a red background. QUILT_COLORS="diff_hdr=1;34;43:diff_hunk=7;33:patch_fail=41"
Quilt started as a series of scripts written by Andrew Morton (patch-scripts). Based on Andrew's ideas, Andreas Grünbacher completely rewrote the scripts, with the help of several other contributors (see the file AUTHORS in the distribution).
This man page was written by Martin Quinson, based on information found in the PDF documentation, and in the help message of each command.
Please refer to the PDF documentation for a full example of use (under SEE ALSO below).
How to Survive with Many Patches, or: Introduction to Quilt is installed at /usr/share/doc/quilt/quilt.pdf. Note that some distributors compress this file. zxpdf(1) can be used to display compressed PDF files.
The GNU Diffutils manual, Comparing and Merging Files, documents diff and patch in detail.
Control Functions for Coded Character Sets (ECMA-48) specifies the ANSI escape sequences used by QUILT_COLORS; section 8.3.117 will be of the most interest. See console_codes(4) for a more convenient, if less canonical, resource.
| December 17, 2013 | quilt |