.\\" Created by Martin Quinson from the tex documentation
.\\"
.TH quilt 1 "Dec 17, 2013" "quilt"
.
.SH NAME
quilt \\- tool to manage 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, un-applied, refreshed, etc.
The key philosophical concept is that your primary output is patches.
.PP
With
.IR quilt ,
all work occurs within a single directory tree.
Commands can be invoked from anywhere within the source tree.
They are of the form
.B quilt cmd
similar to
.IR CVS ,
.IR Subversion ,
or
.I Git
commands.
They can be abbreviated as long as the specified part of the command is
unique.
All commands print some help text with
.B quilt cmd \\-h.
.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 on top of the stack
.RB ( "quilt push" ),
and popped off the stack
.RB ( "quilt pop" ).
Commands are available for querying the contents of the series file
.RB ( "quilt series" ,
see below), the contents of the stack
.RB ( "quilt applied" , " quilt previous" , " quilt top" ),
and the patches that are not applied at a particular moment
.RB ( "quilt next" , " quilt unapplied" ).
By default, most commands apply to the topmost patch on the stack.
.PP
Patch files are located in the
.I patches
sub-directory of the source tree (see
.BR "Example of working tree" ,
under
.BR FILES ,
below).
The
.I QUILT_PATCHES
environment variable can be used to override this 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 sub-directories.
It may also be a symbolic link instead of a directory.
.PP
A file called
.I 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 path names that are relative to the
.I patches
directory; patches may be in sub-directories 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.
.PP
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 (or \\[lq]pushed on the stack\\[rq]), copies
of all files the patch modifies are saved to the
.RI .pc/ patch
directory.
The patch is added to the list of currently applied patches
(.pc/applied\\-patches).
Later when a patch is regenerated
.RB ( "quilt refresh" ),
the backup copies in
.RI .pc/ patch
are compared with the current versions of the files in the source tree
using GNU
.IR diff .
.PP
Documentation related to a patch can be put at the beginning of a patch
file.
.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 .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, so the
patches sub-directory is a convenient location.
.PP
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
.RB ( "quilt pop" ),
and refreshing patches
.RB ( "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.
.
.SS Quilt commands reference
@REFERENCE@
.
.SH OPTIONS
.TP
.B \\-\\-trace
Runs the command in bash trace mode (\\-x).
For internal debugging.
.TP
.BI "\\-\\-quiltrc " file
Use the specified configuration file instead of \\[ti]/.quiltrc (or
/etc/quilt.quiltrc if \\[ti]/.quiltrc does not exist).
See the pdf documentation for details about its possible contents.
The special value \\[lq]\\-\\[rq] causes
.I quilt
not to read any configuration file.
.TP
.B \\-\\-version
Print the version number and exit immediately.
.
.SH "EXIT STATUS"
The exit status is 0 if the sub-command was successfully executed, and
1 in case of error.
.PP
An exit status of 2 denotes that
.I quilt
did not do anything to complete the command.
This happens in particular when asking to push when the whole stack is
already pushed, or asking to pop when the whole stack is already popped.
This behavior is intended to ease the scripting around
.IR quilt .
.
.SH ENVIRONMENT
In addition to that,
.I quilt
recognizes the following variables:
.IP EDITOR 4
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.
.IP LESS 4
The arguments used to invoke the pager.
Inherits the existing value of $LESS if LESS is already set in the
environment, otherwise defaults to \\[lq]\\-FRSX\\[rq].
.
.SH FILES
.SS "Example of working tree"
.EX
work/
├── 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/
│ │ └── ...
│ └── ...
└── ...
.EE
.PP
The patches/ directory is precious as it contains all your patches as
well as the order in which it should be applied.
.PP
The .pc/ directory contains some 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).
.
.SS "Configuration file"
Upon startup,
.I quilt
evaluates the file .quiltrc in the user's home directory, /etc/quilt.quiltrc
if the former file does not exist, 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, \\[lq]QUILT_DIFF_ARGS="\\-\\-color=auto"\\[rq] causes the
output of \\[lq]quilt diff\\[rq] to be syntax colored when writing to a
terminal.
.PP
.IP QUILT_DIFF_OPTS 4
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.
.IP QUILT_PATCH_OPTS 4
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 allow to 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.
.IP QUILT_DIFFSTAT_OPTS 4
Additional options that
.I quilt
shall pass to
.I diffstat
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]).
.IP QUILT_PC 4
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].
.IP QUILT_PATCHES 4
The location of patch files, defaulting to \\[lq]patches\\[rq].
.IP QUILT_SERIES 4
The name of the series file, defaulting to \\[lq]series\\[rq].
Unless an absolute path is used, the search algorithm described above
applies.
.IP QUILT_PATCHES_PREFIX 4
If set to anything,
.I quilt
will prefix patch names it prints with their
directory (QUILT_PATCHES).
.IP QUILT_NO_DIFF_INDEX 4
By default,
.I quilt
prepends an \\[lq]Index:\\[rq] line to the patches it generates.
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.
.IP QUILT_NO_DIFF_TIMESTAMPS 4
By default,
.I 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.
.IP QUILT_PAGER 4
The pager
.I quilt
shall use for commands which produce paginated output.
If unset, the values of GIT_PAGER or 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.
.IP QUILT_COLORS 4
By default,
.I quilt
uses its predefined color set in order to be more
comprehensible when distiguishing various types of patches, e.g.,
applied/unapplied, failed, etc.
.IP
To override one or more color settings, set the QUILT_COLORS variable in
following syntax - colon (:) separated list of elements, each being of
the form <format name>=<foreground color>[;<background color>]
.IP
Format names with their respective default values are listed below,
along with their usage(s).
Color codes(values) are standard bash coloring escape codes.
See more at http://tldp.org/LDP/abs/html/colorizing.html#AEN20229
.RS 4
.TP
.B diff_hdr
Used in \\[lq]quilt diff\\[rq] to color the index line.
Defaults to 32 (green).
.TP
.B diff_add
Used in \\[lq]quilt diff\\[rq] to color added lines.
Defaults to 36 (azure).
.TP
.B diff_mod
Used in \\[lq]quilt diff\\[rq] to color modified lines.
Defaults to 35 (purple).
.TP
.B diff_rem
Used in \\[lq]quilt diff\\[rq] to color removed lines.
Defaults to 35 (purple).
.TP
.B diff_hunk
Used in \\[lq]quilt diff\\[rq] to color hunk header.
Defaults to 33 (brown/orange).
.TP
.B diff_ctx
Used in \\[lq]quilt diff\\[rq] to color the text after end of hunk
header (\\[lq]diff \\-\\-show\\-c\\-function\\[rq] generates this).
Defaults to 35 (purple).
.TP
.B diff_cctx
Used in \\[lq]quilt diff\\[rq] to color the 15-asterisk sequence before
or after a hunk.
Defaults to 33 (brown/orange).
.TP
.B patch_fuzz
Used in \\[lq]quilt push\\[rq] to color the patch fuzz information.
Defaults to 35 (purple).
.TP
.B patch_fail
Used in \\[lq]quilt push\\[rq] to color the fail message.
Defaults to 31 (red).
.TP
.B series_app
Used in \\[lq]quilt series\\[rq] and \\[lq]quilt patches\\[rq] to color
the applied patch names.
Defaults to 32 (green).
.TP
.B series_top
Used in \\[lq]quilt series\\[rq] and \\[lq]quilt patches\\[rq] to color
the top patch name.
Defaults to 33 (brown/orange).
.TP
.B series_una
Used in \\[lq]quilt series\\[rq] and \\[lq]quilt patches\\[rq] to color
unapplied patch names.
Defaults to 0 (no special color).
.RE
.RS 4
In addition, the
.B clear
format name is used to turn off special coloring.
Its value is 0; it is not advised to modify it.
.PP
The content of QUILT_COLORS supersedes default values.
So the value \\[lq]diff_hdr=35;44\\[rq] will get you the
.I diff
headers in magenta over blue instead of the default green over unchanged
background.
For that, add the following content to \\[ti]/.quiltrc (or
/etc/quilt.quiltrc):
.PP
.EX
.RS
QUILT_DIFF_ARGS="\\-\\-color"
QUILT_COLORS='diff_hdr=35;44'
.RE
.EE
.
.SH AUTHORS
.I Quilt
started as a series of scripts written by Andrew Morton
.RI ( 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).
.PP
This man page was written by Martin Quinson, based on information found
in the pdf documentation, and in the help messages of each commands.
.
.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 @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
.BR diff (1),
.BR diffstat (1),
.BR guards (1),
.BR patch (1)
