quilt

Sommaire

NAME

quilt - tool to manage series of patches

SYNOPSIS

quilt [-h] command [options]

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 invoked from anywhere within the source tree. They are of the form 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 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 (quilt push), and popped off the stack (quilt pop). Commands are available for querying the contents of the series file (quilt series, see below), the contents of the stack (quilt applied, quilt previous, quilt top), and the patches that are not applied at a particular moment (quilt next, quilt unapplied). By default, most commands apply to the topmost patch on the stack.

Patch files are located in the patches sub-directory of the source tree (see EXAMPLE OF WORKING TREE below). The QUILT_PATCHES environment variable can be used to override this location. The patches directory may contain sub-directories. It may also be a symbolic link instead of a directory.

A file called 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 patches directory; patches may be in sub-directories below this directory. Lines in the series file that start with a hash character (#) are ignored. You can also add a comment after each patch file name, 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.

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 .pc/patch directory. The patch is added to the list of currently applied patches (.pc/applied-patches). Later when a patch is regenerated (quilt refresh), the backup copies in .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 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 (quilt pop), and refreshing patches (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.

QUILT COMMANDS REFERENCE

add [-P patch] {file} ...


  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 already applied on top of the specified patch cannot be added.


  -P patch
        Patch to add files to.

annotate [-P patch] {file}


  Print an annotated listing of the specified file showing which
  patches modify which lines. Only applied patches are included.


  -P patch
        Stop checking for changes at the specified rather than the

        topmost patch.

applied [patch]


  Print a list of applied patches, or all patches up to and including the
  specified patch in the file series.

delete [-r] [--backup] [patch|-n]


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


  -n    Delete the next patch after topmost, rather than the specified

        or topmost patch.


  -r    Remove the deleted patch file from the patches directory as well.


  --backup
        Rename the patch file to patch~ rather than deleting it.

        Ignored if not used with `-r'.

diff [-p n|-p ab] [-u|-U num|-c|-C num] [--combine patch|-z] [-R] [-P patch] [--snapshot] [--diff=utility] [--no-timestamps] [--no-index] [--sort] [--color] [file ...]


  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.


  -p n  Create a -p n style patch (-p0 or -p1 are supported).


  -p ab Create a -p1 style patch, but use a/file and b/file as the

        original and new filenames instead of the default

        dir.orig/file and dir/file names.


  -u, -U num, -c, -C num
        Create a unified diff (-u, -U) with num lines of context. Create

        a context diff (-c, -C) with num lines of context. The number of

        context lines defaults to 3.


  --no-timestamps
        Do not include file timestamps in patch headers.


  --no-index
        Do not output Index: lines.


  -z    Write to standard output the changes that have been made

        relative to the topmost or specified patch.


  -R    Create a reverse diff.


  -P patch
        Create a diff for the specified patch.  (Defaults to the topmost

        patch.)


  --combine patch
        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.


  --snapshot
        Diff against snapshot (see `quilt snapshot -h').


  --diff=utility
        Use the specified utility for generating the diff. The utility

        is invoked with the original and new file name as arguments.


  --color[=always|auto|never]
        Use syntax coloring.


  --sort        Sort files by their name instead of preserving the original order.

edit file ...


  Edit the specified file(s) in $EDITOR after adding it (them) to
  the topmost patch.

files [-v] [-a] [-l] [--combine patch] [patch]


  Print the list of files that the topmost or specified patch changes.


  -a    List all files in all applied patches.


  -l    Add patch name to output.


  -v    Verbose, more user friendly output.


  --combine patch
        Create a listing for all patches between this patch and

        the topmost or specified patch. A patch name of `-' is

        equivalent to specifying the first applied patch.

fold [-p strip-level]


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


  -p strip-level
        The number of pathname components to strip from file names

        when applying patchfile.

fork [new_name]


  Fork the topmost patch.  Forking a patch means creating a verbatim copy
  of it under a new name, and use that new name instead of the original
  one in the current series.  This is useful when a patch has to be
  modified, but the original version of it should be preserved, e.g.
  because it is used in another series, or for the history.  A typical
  sequence of commands would be: fork, edit, refresh.


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

graph [--all] [--reduce] [--lines[=num]] [--edge-labels=files] [-T ps] [patch]


  Generate a dot(1) directed graph showing the dependencies between
  applied patches. A patch depends on another patch if both touch the same
  file or, with the --lines option, if their modifications overlap. Unless
  otherwise specified, the graph includes all patches that the topmost
  patch depends on.
  When a patch name is specified, instead of the topmost patch, create a
  graph for the specified patch. The graph will include all other patches
  that this patch depends on, as well as all patches that depend on this
  patch.


  --all Generate a graph including all applied patches and their

        dependencies. (Unapplied patches are not included.)


  --reduce
        Eliminate transitive edges from the graph.


  --lines[=num]
        Compute dependencies by looking at the lines the patches modify.

        Unless a different num is specified, two lines of context are

        included.


  --edge-labels=files
        Label graph edges with the file names that the adjacent patches

        modify.


  -T ps Directly produce a PostScript output file.

grep [-h|options] {pattern}


  Grep through the source files, recursively, skipping patches and quilt
  meta-information. If no filename argument is given, the whole source
  tree is searched. Please see the grep(1) manual page for options.


  -h    Print this help. The grep -h option can be passed after a

        double-dash (--). Search expressions that start with a dash

        can be passed after a second double-dash (-- --).

header [-a|-r|-e] [--backup] [--strip-diffstat] [--strip-trailing-whitespace] [patch]


  Print or change the header of the topmost or specified patch.


  -a, -r, -e
        Append to (-a) or replace (-r) the exiting patch header, or

        edit (-e) the header in $EDITOR. If none of these options is

        given, print the patch header.


  --strip-diffstat
        Strip diffstat output from the header.


  --strip-trailing-whitespace
        Strip trailing whitespace at the end of lines of the header.


  --backup
        Create a backup copy of the old version of a patch as patch~.

import [-p num] [-P patch] [-f] [-d {o|a|n}] patchfile ...


  Import external patches.  The patches will be inserted following the
  current top patch, and must be pushed after import to apply them.


  -p num
        Number of directory levels to strip when applying (default=1)


  -P patch
        Patch filename to use inside quilt. This option can only be

        used when importing a single patch.


  -f    Overwrite/update existing patches.


  -d {o|a|n}
        When overwriting in existing patch, keep the old (o), all (a), or

        new (n) patch header. If both patches include headers, this option

        must be specified. This option is only effective when -f is used.

mail {--mbox file|--send} [-m text] [--prefix prefix] [--sender ...] [--from ...] [--to ...] [--cc ...] [--bcc ...] [--subject ...] [--signature file]


  Create mail messages from all patches in the series file, and either store
  them in a mailbox file, or send them immediately. The editor is opened
  with a template for the introduction. Please see /usr/share/doc/quilt/README.MAIL for details.


  -m text
        Text to use as the text in the introduction. When this option is

        used, the editor will not be invoked, and the patches will be

        processed immediately.


  --prefix prefix
        Use an alternate prefix in the bracketed part of the subjects

        generated. Defaults to `patch'.


  --mbox file
        Store all messages in the specified file in mbox format. The mbox

        can later be sent using formail, for example.


  --send
        Send the messages directly.


  --sender
        The envelope sender address to use. The address must be of the form

        `user@domain.name'. No display name is allowed.


  --from, --subject
        The values for the From and Subject headers to use. If no --from

        option is given, the value of the --sender option is used.


  --to, --cc, --bcc
        Append a recipient to the To, Cc, or Bcc header.


  --signature file


        Append  the specified signature file if it exists.

        Default is ~/.signature

new {patchname}


  Create a new patch with the specified file name, and insert it after the
  topmost patch in the patch series file.


  Quilt can be used in sub-directories of a source tree. It determines the
  root of a source tree by searching for a patches directory above the
  current working directory. Create a patches directory in the intended root
  directory if quilt chooses a top-level directory that is too high up
  in the directory tree.

next [patch]


  Print the name of the next patch after the specified or topmost patch in
  the series file.

patches [-v] {file}


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


  -v    Verbose, more user friendly output.

pop [-afRqv] [num|patch]


  Remove patch(es) from the stack of applied patches.  Without options,
  the topmost patch is removed.  When a number is specified, remove the
  specified number of patches.  When a patch name is specified, remove
  patches until the specified patch end up on top of the stack.  Patch
  names may include the patches/ prefix, which means that filename
  completion can be used.


  -a    Remove all applied patches.


  -f    Force remove. The state before the patch(es) were applied will

        be restored from backup files.


  -R    Always verify if the patch removes cleanly; don't rely on

        timestamp checks.


  -q    Quiet operation.


  -v    Verbose operation.

previous [patch]


  Print the name of the previous patch before the specified or topmost
  patch in the series file.

push [-afqv] [--leave-rejects] [--interactive] [--color[=always|auto|never]] [num|patch]


  Apply patch(es) from the series file.  Without options, the next patch
  in the series file is applied.  When a number is specified, apply the
  specified number of patches.  When a patch name is specified, apply
  all patches up to and including the specified patch.  Patch names may
  include the patches/ prefix, which means that filename completion can
  be used.


  -a    Apply all patches in the series file.


  -f    Force apply, even if the patch has rejects.


  -q    Quiet operation.


  -v    Verbose operation.


  --leave-rejects
        Leave around the reject files patch produced, even if the patch

        is not actually applied.


  --interactive
        Allow the patch utility to ask how to deal with conflicts. If

        this option is not given, the -f option will be passed to the

        patch program.


  --color[=always|auto|never]
        Use syntax coloring.

refresh [-p n|-p ab] [-u|-U num|-c|-C num] [-f] [--no-timestamps] [--no-index] [--diffstat] [--sort] [--backup] [--strip-trailing-whitespace] [patch]


  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.


  -p n  Create a -p n style patch (-p0 or -p1 supported).


  -p ab Create a -p1 style patch, but use a/file and b/file as the

        original and new filenames instead of the default

        dir.orig/file and dir/file names.


  -u, -U num, -c, -C num
        Create a unified diff (-u, -U) with num lines of context. Create

        a context diff (-c, -C) with num lines of context. The number of

        context lines defaults to 3.


  --no-timestamps
        Do not include file timestamps in patch headers.


  --no-index
        Do not output Index: lines.


  --diffstat
        Add a diffstat section to the patch header, or replace the

        existing diffstat section.


  -f    Enforce refreshing of a patch that is not on top.


  --backup
        Create a backup copy of the old version of a patch as patch~.


  --sort        Sort files by their name instead of preserving the original order.


  --strip-trailing-whitespace
        Strip trailing whitespace at the end of lines.

remove [-P patch] {file} ...


  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.


  -P patch
        Remove named files from the named patch.

rename [-P patch] new_name


  Rename the topmost or named patch.


  -P patch
        Patch to rename.

series [-v]


  Print the names of all patches in the series file.


  -v    Verbose, more user friendly output.

setup [-d path-prefix] [-v] [--path dir1:dir2] {specfile|seriesfile}


  Initializes a source tree from an rpm spec file or a quilt series file.


  -d    Optional path prefix.


  --path        Directories to search when looking for tarballs. Defaults to `.'.


  -v    Verbose debug output.

snapshot [-d]


  Take a snapshot of the current working state.  After taking the snapshot,
  the tree can be modified in the usual ways, including pushing and
  popping patches.  A diff against the tree at the moment of the
  snapshot can be generated with `quilt diff --snapshot'.


  -d    Only remove current snapshot.

top


  Print the name of the topmost patch on the current stack of applied
  patches.

unapplied [patch]


  Print a list of patches that are not applied, or all patches that follow
  the specified patch in the series file.

upgrade


  Upgrade the meta-data in a working tree from an old version of quilt to the
  current version. This command is only needed when the quilt meta-data format
  has changed, and the working tree still contains old-format meta-data. In that
  case, quilt will request to run `quilt upgrade'.

COMMON OPTIONS TO ALL COMMANDS

B--traceP

Runs the command in bash trace mode (-x). For internal debugging.

B--quiltrcP file

Use the specified configuration file instead of ~/.quiltrc (or /etc/quilt.quiltrc if ~/.quiltrc does not exist). See the pdf documentation for details about its possible contents. The special value "-" causes quilt not to read any configuration file.

B--versionP

Print the version number and exit immediately.

EXAMPLE OF WORKING TREE

 work/ -+- ...
 |- patches/ -+- series
 |            |- patch2.diff
 |            |- patch1.diff
 |            +- ...
 +- .pc/ -+- applied-patches
 |- patch1.diff/ -+- ...
 |- patch2.diff/ -+- ...
 +- ...

EXAMPLE

Please refer to the pdf documentation for an example.

CONFIGURATION FILE

Upon startup, quilt evaluates the file .quiltrc in the user's home directory, 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, QUILT_DIFF_ARGS="--color=auto" causes the output of quilt diff to be syntax colored when writing to a terminal.

In addition to that, quilt recognizes the following variables:

QUILT_DIFF_OPTS

Additional options that quilt shall pass to GNU diff when generating patches. A useful setting for C source code is "-p", 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, some versions of GNU patch support the "--unified-reject-files" option for generating reject files in unified diff style.

QUILT_DIFFSTAT_OPTS

Additional options that quilt shall pass to diffstat when generating patch statistics. For example, "-f0" can be used for an alternative output format. Recent versions of diffstat also support alternative rounding methods ("-r1", "-r2").

QUILT_PATCHES

The location of patch files, defaulting to "patches".

QUILT_PATCHES_PREFIX

If set to anything, quilt will prefix patch names it prints with their directory (QUILT_PATCHES).

QUILT_NO_DIFF_INDEX

By default, quilt prepends an Index: 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.

QUILT_NO_DIFF_TIMESTAMPS

By default, 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.

EDITOR

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.

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.

SEE ALSO

The pdf documentation, under /usr/share/doc/quilt/quilt.pdf.gz zxpdf(1) can be used to display compressed pdf files.

diff(1), patch(1).