'\\" t
.\\" Created by Martin Quinson from the tex documentation
.\\"
.TH quilt 1 "Dec 17, 2013" "quilt"
.
.SH NAME
quilt \\- manage a series of patches
.
.SH SYNOPSIS
.SY quilt
.RB [ \\-\\-quiltrc
.IR file ]
.OP \\-\\-trace
.I command
.RI [ options ]
.YS
.SY quilt
.RI [ command ]
\\-h
.SY "quilt \\-\\-version"
.YS
.
.SH DESCRIPTION
.I 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.
.PP
With
.IR quilt ,
all work occurs within a single directory tree.
Commands can be invoked from anywhere within the source tree.
Like
.IR CVS ,
.IR Subversion ,
or
.IR Git ,
.I quilt
takes commands of the form \\[lq]quilt
.IR command \\[rq].
A command can be truncated (abbreviated) as long as the specified part
of the command is unambiguous.
If
.I command
is ambiguously short,
.I 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.
.PP
.I 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.
.PP
Patch files are located in the
.I patches
subdirectory of the source tree (see
.BR "Example of working tree" ,
under
.BR FILES ,
below).
The
.I 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
.I Git
searches for its configuration files).
The
.I patches
directory may contain subdirectories.
It may also be a symbolic link instead of a directory.
.PP
.I Quilt
creates and maintains a file called
.IR series ,
which defines the order in which patches are applied.
The
.I 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
.I 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
.I quilt
adds, removes, or renames patches, it automatically updates the series
file.
Users of
.I 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
.IR quilt -managed
patches you distribute.
Different series files can be used to assemble patches in different
ways, corresponding (for example) to different development branches.
.PP
Before a patch is applied, copies of all files the patch modifies are
saved to the
.IR .pc/ patch-name
directory, where
.I patch-name
is the name of the patch (for example,
.IR fix\\-buffer\\-overflow.patch ).
The patch is added to the list of currently applied patches
.RI ( .pc/applied\\-patches ).
Later, when a patch is regenerated (\\[lq]quilt refresh\\[rq]), the
backup copies in
.IR .pc/ patch-name
are compared with the current versions of the files in the source tree
using GNU
.BR diff (1).
.PP
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.
.PP
Documentation related to a patch can be put at the beginning of its
patch file (\\[lq]quilt header\\[rq]).
.I 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
.I Diffutils
manual.)
.PP
The series file is looked up in the
.I .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.
.PP
The
.I .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
.I .pc
directory are automatically removed when they are no longer needed, so
there is no need to clean up manually.
.
.SS Quilt commands reference
@REFERENCE@
.
.SH OPTIONS
These options are common to all
.I quilt
commands.
.TP
.B \\-h
Print a usage message (for the given
.IR command ,
if one is specified, otherwise for
.I quilt
itself) and exit.
.TP
.BI "\\-\\-quiltrc " file
Use
.I file
as the configuration file instead of
.I \\[ti]/.quiltrc
(or
.I /etc/quilt.quiltrc
if
.I \\[ti]/.quiltrc
does not exist).
The special value \\[lq]\\-\\[rq] causes
.I quilt
not to read any configuration file.
.TP
.B \\-\\-trace
Run the command in the shell's trace mode (\\-x) for debugging of
internal operations.
.TP
.B \\-\\-version
Print the version number and exit.
.
.SH "EXIT STATUS"
The exit status is 0 if the requested operation completed successfully,
or 1 in case of error.
.PP
An exit status of 2 indicates that
.I quilt
did not do anything to complete the command.
This happens in particular when asking
.I 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
.IR quilt .
.
.SH ENVIRONMENT
.I Quilt
recognizes the following variables:
.TP 4
.I EDITOR
Specify the program to run to edit files;
for instance,
with \\[lq]quilt edit\\[rq] or \\[lq]quilt header \\-e\\[rq].
.TP 4
.I LESS
Specify the arguments used to invoke the
.BR less (1)
pager.
Defaults to \\[lq]\\-FRSX\\[rq].
.
.SH FILES
.SS "Example of working tree"
.\\" Many roff output devices do not have font support for Unicode's
.\\" box-drawing characters (U+2500 to U+257F).
.schar \\[u2500] \\-
.schar \\[u2502] |
.schar \\[u2514] +
.schar \\[u251C] +
.EX
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] ...
.EE
.PP
The
.I patches
directory is precious as it contains all your patches as well as the
order in which they should be applied.
.PP
The
.I .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
.I patches
directory (provided that all patches were regenerated before the
removal).
.
.SS "Configuration file"
Upon startup,
.I quilt
evaluates the file specified with the \\[lq]\\-\\-quiltrc\\[rq] option;
if that option is not given, the file
.I .quiltrc
in the user's home directory is used, and if that does not exist,
.I /etc/quilt.quiltrc
is read.
This file is a
.BR bash (1)
script.
.I EDITOR
and
.I LESS
can be overridden here if desired;
see
.BR ENVIRONMENT ,
above.
.PP
Define a variable of the form
.IR QUILT_ COMMAND _ARGS
to specify default options to be passed to any
.I quilt
command (in uppercase).
For example,
.EX
.RS
QUILT_DIFF_ARGS="\\-\\-color=auto"
.RE
.EE
causes the output of \\[lq]quilt diff\\[rq] to be syntax-colored when
writing to a terminal.
.TP 4
.I QUILT_DIFF_OPTS
Additional options that
.I quilt
shall pass to GNU
.I diff
when generating patches.
A useful setting for C source code is \\[lq]\\-p\\[rq], which causes GNU
.I diff
to show in the resulting patch which function a change is in.
.TP 4
.I QUILT_PATCH_OPTS
Additional options that
.I quilt
shall pass to GNU
.I patch
when applying patches.
For example, recent versions of GNU
.I patch
support the \\[lq]\\-\\-reject\\-format=unified\\[rq] option for
generating reject files in \\[lq]unified diff\\[rq] style (older
.I patch
versions used \\[lq]\\-\\-unified\\-reject\\-files\\[rq] for that).
.IP
You may also want to add the \\[lq]\\-E\\[rq] option if you have issues
with
.I quilt
not deleting empty files when you think it should.
The documentation of GNU
.I patch
says that \\[lq]normally this option is unnecessary\\[rq], but when
.I patch
is in POSIX mode or if the patch format doesn't distinguish empty files
from deleted files,
.I patch
deletes empty files only if the \\[lq]\\-E\\[rq] option is given.
Beware that when passing \\[lq]\\-E\\[rq] to
.IR patch ,
.I quilt
will no longer be able to deal with empty files, which is why using
\\[lq]\\-E\\[rq] is no longer the default.
.TP 4
.I QUILT_DIFFSTAT_OPTS
indicates additional options that
.I quilt
shall pass to
.BR diffstat (1)
when generating patch statistics.
For example, \\[lq]\\-f0\\[rq] can be used for an alternative output
format.
Recent versions of
.I diffstat
also support alternative rounding methods (\\[lq]\\-r1\\[rq],
\\[lq]\\-r2\\[rq]).
.TP 4
.I QUILT_PC
The location of backup files and any other data relating to the current
state of the working directory from
.IR quilt 's
perspective.
Defaults to \\[lq].pc\\[rq].
.TP 4
.I QUILT_PATCHES
The location of patch files, defaulting to
.IR patches .
.TP 4
.I QUILT_SERIES
The name of the series file, defaulting to
.IR series .
Unless an absolute path is used, the search algorithm described above
applies.
.TP 4
.I QUILT_PATCHES_PREFIX
Boolean flag; if set to anything,
.I quilt
will prefix any patch name it prints with its directory
.RI ( QUILT_PATCHES ).
.TP 4
.I QUILT_NO_DIFF_INDEX
Boolean flag; if set to anything,
no \\[lq]Index:\\[rq] line is prepended to patches generated by
.IR quilt .
This is shorthand for adding \\[lq]\\-\\-no\\-index\\[rq] to both
.I QUILT_DIFF_ARGS
and
.IR QUILT_REFRESH_ARGS .
.TP 4
.I 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
.I QUILT_DIFF_ARGS
and
.IR QUILT_REFRESH_ARGS .
.TP 4
.I QUILT_PAGER
The pager
.I quilt
shall use for commands which produce paginated output.
If unset, the value of
.I GIT_PAGER
or, failing that,
.I 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.
.TP 4
.I QUILT_COLORS
A sequence of definitions that directs
.I 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.
.IP
To override one or more settings, set
.I QUILT_COLORS
to a colon-separated list of elements,
each of the form
.RI \\[lq] format-name\\c
.BI = digit-sequence\\c
.RB [ ; ...]\\[rq].
.IP
Each
.I 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).
.IP
Recognized
.IR format-name s,
along with the
.I quilt
commands that use them,
their use contexts,
and default values, follow.
.TS
box;
lI l l l.
format-name command context default
_
.T&
lB l l l.
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)
.TE
.IP
All
.IR format-name s
used by the series command are also used by the patches command.
.IP
The special
.I 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.
.IP
As an example, one can put the following in
.I \\[ti]/.quiltrc
(or
.IR /etc/quilt.quiltrc ):
.RS 12
.EX
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"
.EE
.RE
.
.SH AUTHORS
.fchar \\[:u] ue
.I Quilt
started as a series of scripts written by Andrew Morton
.RI ( 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
.I AUTHORS
in the distribution).
.PP
This man page was written by Martin Quinson, based on information found
in the PDF documentation, and in the help message of each command.
.
.SH EXAMPLES
Please refer to the PDF documentation for a full example of use (under
.B "SEE ALSO"
below).
.
.SH "SEE ALSO"
.I "How to Survive with Many Patches, or: Introduction to Quilt"
is installed at
.IR "@DOCSUBDIR@/\\:quilt.pdf" .
Note that some distributors compress this file.
.BR zxpdf (1)
can be used to display compressed PDF files.
.PP
The GNU
.I Diffutils
manual,
.UR https://\\:www.gnu.org/\\:software/\\:diffutils/\\:manual/
.I "Comparing and Merging Files"
.UE ,
documents
.I diff
and
.I patch
in detail.
.PP
.UR https://\\:www.ecma\\-international.org/\\:publications/\\:standards/\\:Ecma\\-048.htm
.I Control Functions for Coded Character Sets
(ECMA-48)
.UE
specifies the ANSI escape sequences used by
.IR QUILT_COLORS ;
section 8.3.117 will be of the most interest.
See
.BR console_codes (4)
for a more convenient, if less canonical, resource.
.PP
.BR diff (1),
.BR diffstat (1),
.BR guards (1),
.BR patch (1)
