."Created by Martin Quinson from the tex documentation
."
.TH quilt 1 "February 21, 2004" "quilt"
.SH NAME
quilt - tool to manage series of patches
.SH SYNOPSIS
.B quilt
[-h] command [options]
.SH DESCRIPTION
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.
With quilt, all work occurs within a single directory tree. Commands can be
be invoqued from anywhere within the source tree. They are of the form
.B quilt cmd
similar to CVS 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.
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.
Patch files are located in the
.I patches
sub-directory of the source tree (see EXAMPLE OF WORKING TREE below). The
.I QUILT_PATCHES
environment variable can be used to override this location. The
.I patches
directory may contain sub-directories. It may also be a symbolic link
instead of a directory.
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 pathnames that are relative to the
.I patches
directory; patches may be in sub-directories below the this directory. Lines
in the series file that start with a hash character (#) are ignored. 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.
Different series files can be used to assemble patches in different ways,
corresponding for example to different development branches.
Before a patch is applied (or ``pushed on the stack''), 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 diff.
Documentation related to a patch can be put at the beginning of a patch
file. 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
.B diff
documentation).
The series file is looked up in the root of the source tree, in the patches
directory, and in the .pc 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.
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 textsf{.pc} directory are automatically removed when they are
no longer needed, so there is no need to clean up manually.
.SH QUILT COMMANDS REFERENCE
.IP "\fBadd\fP [-p patch] {file} ... " 4
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 on top of the specified patch cannot be added.
.IP " -p patch" 8
Patch to add files to.
.IP "\fBapplied\fP [-n] [patch] " 4
Print a list of applied patches, or all patches up to and including the
specified patch in the file series.
.IP " -n" 8
Print patch file names instead of patch names.
.IP "\fBdelete\fP [patch] " 4
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.)
.IP "\fBdiff\fP [-p n] [-c patch|-z] [-R] [-P patch] [--diff=utility] [file ...] " 4
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.
.IP " -p n" 8
Create a -p n style patch (-p0 or -p1 are supported).
.IP " -P patch" 8
Create a diff for the specified patch. (Defaults to the topmost
patch.)
.IP " -c patch" 8
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.
.IP " -R" 8
Create a reverse diff.
.IP " -z" 8
Write to standard output the changes that have been made
relative to the topmost or specified patch.
.IP " --diff=utility" 8
Use the specified utility for generating the diff. The utility
is invoked with the original and new file name as arguments.
.IP "\fBfiles\fP [-v] [patch] " 4
Print the list of files that the topmost or specified patch changes.
.IP " -v" 8
Verbose, more user friendly output.
.IP "\fBimport\fP [-f] [-p num] [-n patch] [patchfile] " 4
Import an external patch. If a patch file name is specified, the patch
will be stored in this relative path in the patches/ directory. Else,
if an input file name is given this name is used as the patch name.
.IP " -p num" 8
Number of directory levels to strip when aplying (default=1)
.IP " -n patch" 8
File name relative to patches/ to use.
.IP " -f" 8
Overwite/update existing patches.
.IP "\fBnew\fP {patchname} " 4
Create a new patch with the specified file name, and insert it after the
topmost patch in the patch series file.
.IP "\fBnext\fP [patch] " 4
Print the name of the next patch after the specified or topmost patch in
the series file.
.IP " -n" 8
Print patch file names instead of patch names.
.IP "\fBpatches\fP {file} " 4
Print the list of patches that modify the specified file. (Uses a
heuristic to determine which files are modified by unapplied patches.
Note that this heuristic is much slower than scanning applied patches.)
.IP " -n" 8
Print the patch file names instead of the patch names.
.IP " -v" 8
Verbose, more user friendly output.
.IP "\fBpop\fP [-afRqv] [num|patch] " 4
Remove patch(es) from the current stack. A number of patches to remove,
or a patch name can be specified. If a patch name is given, remove all
patches applied on top of the named patch. If neither a number nor a
patch name is specified, remove the next patch from the series file.
.IP " -a" 8
Remove all applied patches.
.IP " -f" 8
Force remove. The state before the patch(es) were applied will
be restored from backup files.
.IP " -R" 8
Remove the patch with `patch -R' and check if the patch reverts
all changes properly.
.IP " -q" 8
Quiet operation.
.IP " -v" 8
Verbose operation.
.IP "\fBprevious\fP [-n] [patch] " 4
Print the name of the previous patch before the specified or topmost
patch in the series file.
.IP " -n" 8
Print patch file names instead of patch names.
.IP "\fBpush\fP [-afqv] [--leave-rejects] [num|patch] " 4
Apply patch(es) from the series file. A number of patches to apply, or
a patch name can be specified. If a patch name is given, apply all
patches up to and including the named patch. If neither a number nor a
patch name is specified, apply the next patch from the series file.
.IP " -a" 8
Apply all patches in the series file.
.IP " -f" 8
Force apply, even if the patch has rejects.
.IP " -q" 8
Quiet operation.
.IP " -v" 8
Verbose operation.
.IP " --leave-rejects" 8
Leave around the reject files patch produced, even if the patch
is not actually applied.
.IP " --interactive" 8
Allow the patch utility to ask how to deal with conflicts. If
this option is not given, the option -f will be passed to the
patch program.
.IP "\fBrefresh\fP [-p n] [-f] [patch] " 4
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.
.IP " -p n" 8
Create a -p n style patch (-p0 or -p1 supported).
.IP " -f" 8
Force refresh, even if more recent patches modify
some of the same files.
.IP "\fBremove\fP [-p patch] {file} ... " 4
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.
.IP " -p patch" 8
Patch to remove files from.
.IP "\fBseries\fP [-v] " 4
Print the names of all patches in the series file.
.IP " -n" 8
Print patch file names instead patch names.
.IP " -v" 8
Verbose, more user friendly output.
.IP "\fBsetup\fP [-d sourcedir] {seriesfile|specfile} " 4
Initializes a source tree from a patch series file. The patch series
file must contain the name of the relevant tar archive, in addition to
the list of patches.
.IP " -d" 8
The directory that contains the archives and patches. Defaults
to the directory of the series/spec file.
.IP " -l" 8
Make the patches directory a symbolic link. If a series file is
specified, also create a symlink to the series file.
.IP "\fBtop\fP " 4
Print the name of the topmost patch on the current stack of applied
patches.
.IP "\fBunapplied\fP [patch] " 4
Print a list of patches that are not applied, or all patches that follow
the specified patch in the series file.
.IP " -n" 8
Print patch file names instead of patch names.
.IP "\fBfold\fP [-p strip-level] " 4
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).
.IP " -p strip-level" 8
The number of pathname components to strip from file names
when applying patchfile.
.IP "\fBfork\fP [new_name] " 4
Fork the next patch. 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).
.IP "\fBsnapshot\fP [-d] " 4
Take a snapshot of the current working state.
.IP " -d" 8
Remove current snapshot.
.IP "\fBedit\fP file ... " 4
Edit the specified file(s) in vi after adding it (them) to the
topmost patch.
.SH EXAMPLE OF WORKING TREE
.nf
+- work/ -+- ...
| |- patches/ -+- series
| | |- patch2.diff
| | |- patch1.diff
| | +- ...
| +- .pc/ -+- applied-patches
| |- patch1/ -+- ...
| |- patch2/ -+- ...
| +- ...
.fi
.SH EXAMPLE
Please refere to the pdf documentation for an example.
.SH FILES
.IP ~/.quiltrc 4
Configuration (see pdf documentation for more details).
.SH AUTHORS
Quilt started as a series of scripts written by Andrew Morton
(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).
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 SEE ALSO
The pdf documentation, which should be under /usr/share/doc/quilt/quilt.pdf.
.BR diff ( 1 ),
.BR patch ( 1 )
