path: root/doc/quilt.1.in

.\\" 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
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
.I 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
.I 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
.I \\[ti]/.quiltrc
(or
.IR /etc/quilt.quiltrc ):
.PP
.EX
.RS
QUILT_DIFF_ARGS="\\-\\-color"
QUILT_COLORS='diff_hdr=35;44'
.RE
.EE
.
.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
.BR diff (1),
.BR diffstat (1),
.BR guards (1),
.BR patch (1)