quilt(1)

NAME
quilt \- manage a series of patches

SYNOPSIS
quilt [\-\-quiltrc file] [\-\-trace] command [options]
quilt [command] \-h
quilt \-\-version

DESCRIPTION
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 \[lq]quilt command\[rq]. 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 \[lq]\-h\[rq] 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 (\[lq]quilt push\[rq]), and popped off the stack (\[lq]quilt pop\[rq]). Commands are available for querying the contents of the stack (\[lq]quilt applied\[rq], \[lq]quilt previous\[rq], \[lq]quilt top\[rq]) and the patches that are not applied at a particular moment (\[lq]quilt next\[rq], \[lq]quilt unapplied\[rq]). 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 \[lq]quilt series\[rq]. 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., \[lq]\-p2\[rq]). 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 (\[lq]quilt refresh\[rq]), 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 (\[lq]quilt new\[rq]); 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 (\[lq]quilt edit\[rq]). After editing, inspect the impact of your changes (\[lq]quilt diff\[rq]); the changes stay local to your working tree until you call \[lq]quilt refresh\[rq] to write them to the patch file.

Documentation related to a patch can be put at the beginning of its patch file (\[lq]quilt header\[rq]). 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.

  Quilt commands reference
@REFERENCE@

OPTIONS
These options are common to all quilt commands.

\-h Print a usage message (for the given command, if one is specified, otherwise for quilt itself) and exit.

\-\-quiltrc file
    Use file as the configuration file instead of \[ti]/.quiltrc (or /etc/quilt.quiltrc if \[ti]/.quiltrc does not exist). The special value \[lq]\-\[rq] causes quilt not to read any configuration file.

\-\-trace
    Run the command in the shell's trace mode (\-x) for debugging of internal operations.

\-\-version
    Print the version number and exit.

EXIT STATUS
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.

ENVIRONMENT
Quilt recognizes the following variables:

EDITOR
    Specify the program to run to edit files; for instance, with \[lq]quilt edit\[rq] or \[lq]quilt header \-e\[rq].

LESS
    Specify the arguments used to invoke the less(1) pager. Defaults to \[lq]\-FRSX\[rq].

FILES

  Example of working tree
    project\-1.2.3/
    \[u251C]\[u2500]\[u2500] patches/
    \[u2502]    \[u251C]\[u2500]\[u2500] series         (list of patches to apply)
    \[u2502]    \[u251C]\[u2500]\[u2500] patch1.diff    (one particular patch)
    \[u2502]    \[u251C]\[u2500]\[u2500] patch2.diff
    \[u2502]    \[u2514]\[u2500]\[u2500] ...
    \[u251C]\[u2500]\[u2500] .pc/
    \[u2502]    \[u251C]\[u2500]\[u2500] .quilt_patches (content of QUILT_PATCHES)
    \[u2502]    \[u251C]\[u2500]\[u2500] .quilt_series  (content of QUILT_SERIES)
    \[u2502]    \[u251C]\[u2500]\[u2500] patch1.diff/   (copy of patched files)
    \[u2502]    \[u2502]    \[u2514]\[u2500]\[u2500] ...
    \[u2502]    \[u251C]\[u2500]\[u2500] patch2.diff/
    \[u2502]    \[u2502]    \[u2514]\[u2500]\[u2500] ...
    \[u2502]    \[u2514]\[u2500]\[u2500] ...
    \[u2514]\[u2500]\[u2500] ...

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).

  Configuration file
Upon startup, quilt evaluates the file specified with the \[lq]\-\-quiltrc\[rq] 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"
causes the output of \[lq]quilt diff\[rq] to be syntax-colored when writing to a terminal.

QUILT_DIFF_OPTS
    Additional options that quilt shall pass to GNU diff when generating patches. A useful setting for C source code is \[lq]\-p\[rq], 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 \[lq]\-\-reject\-format=unified\[rq] option for generating reject files in \[lq]unified diff\[rq] style (older patch versions used \[lq]\-\-unified\-reject\-files\[rq] for that).

    You may also want to add the \[lq]\-E\[rq] option if you have issues with quilt not deleting empty files when you think it should. The documentation of GNU patch says that \[lq]normally this option is unnecessary\[rq], but when patch is in POSIX mode or if the patch format doesn't distinguish empty files from deleted files, patch deletes empty files only if the \[lq]\-E\[rq] option is given. Beware that when passing \[lq]\-E\[rq] to patch, quilt will no longer be able to deal with empty files, which is why using \[lq]\-E\[rq] is no longer the default.

QUILT_DIFFSTAT_OPTS
    indicates additional options that quilt shall pass to diffstat(1) when generating patch statistics. For example, \[lq]\-f0\[rq] can be used for an alternative output format. Recent versions of diffstat also support alternative rounding methods (\[lq]\-r1\[rq], \[lq]\-r2\[rq]).

QUILT_PC
    The location of backup files and any other data relating to the current state of the working directory from quilt's perspective. Defaults to \[lq].pc\[rq].

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
    Boolean flag; if set to anything, quilt will prefix any patch name it prints with its directory (QUILT_PATCHES).

QUILT_NO_DIFF_INDEX
    Boolean flag; if set to anything, no \[lq]Index:\[rq] line is prepended to patches generated by quilt. This is shorthand for adding \[lq]\-\-no\-index\[rq] to both QUILT_DIFF_ARGS and QUILT_REFRESH_ARGS.

QUILT_NO_DIFF_TIMESTAMPS
    Boolean flag; if set to anything, no timestamps are included in headers when generating patches. This is shorthand for adding \[lq]\-\-no\-timestamps\[rq] to both QUILT_DIFF_ARGS and QUILT_REFRESH_ARGS.

QUILT_PAGER
    The pager quilt shall use for commands which produce paginated output. If unset, the value of GIT_PAGER or, failing that, PAGER is used. If none of these variables is set, \[lq]less \-R\[rq] is used. An empty value indicates that no pager should be used.

QUILT_COLORS
    A sequence of definitions that directs quilt which ANSI escape sequences to associate with an output context, overriding the defaults. The most common use is to set colors (thus the name of this variable), but other attributes exist, such as bold or reverse.

    To override one or more settings, set QUILT_COLORS to a colon-separated list of elements, each of the form \[lq]format-name\c =digit-sequence\c [;...]\[rq].

    Each digit-sequence should be a SGR (Select Graphic Rendition) value supported by your terminal. The standardized SGR values were specified by ANSI and incorporated into ISO-6429 and ECMA-48 (\[sc]8.3.117). The colors have standard names but their values were not defined within a color space; their precise appearance will vary and may be customizable in your terminal (emulator).

    Recognized format-names, along with the quilt commands that use them, their use contexts, and default values, follow.
    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)

    All format-names used by the series command are also used by the patches command.

    The special format-name \[lq]clear\[rq] is used to turn off special graphic renditions and return to the terminal defaults. Changing its definition should not be necessary for any terminal that claims to support ANSI escape sequences. If your terminal is corrupted despite your best efforts, try the command \[lq]tput sgr0\[rq] to restore the default graphic rendition.

    As an example, one can put the following in \[ti]/.quiltrc (or /etc/quilt.quiltrc):
        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"

AUTHORS
Quilt started as a series of scripts written by Andrew Morton (patch\-scripts). Based on Andrew's ideas, Andreas Gr\[:u]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.

EXAMPLES
Please refer to the PDF documentation for a full example of use (under SEE ALSO below).

SEE ALSO
How to Survive with Many Patches, or: Introduction to Quilt is installed at @DOCSUBDIR@/\: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 (https://\:www.gnu.org/\:software/\:diffutils/\:manual/), documents diff and patch in detail.

Control Functions for Coded Character Sets (ECMA-48) (https://\:www.ecma\-international.org/\:publications/\:standards/\:Ecma\-048.htm) 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.

diff(1), diffstat(1), guards(1), patch(1)