quilt(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | QUILT COMMANDS REFERENCE | COMMON OPTIONS TO ALL COMMANDS | EXIT STATUS | EXAMPLE OF WORKING TREE | EXAMPLE | CONFIGURATION FILE | AUTHORS | SEE ALSO | COLOPHON

quilt(1)                 General Commands Manual                quilt(1)

NAME         top

       quilt - tool to manage series of patches

SYNOPSIS         top

       quilt [-h] command [options]

DESCRIPTION         top

       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 invoked from anywhere within the source tree.
       They are of the form quilt cmd similar to CVS, svn or git
       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. When not found in the current directory, that
       subdirectory is searched recursively in the parent directories
       (this is similar to the way git searches for its configuration
       files). 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 path names 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.
       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. -p2). 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 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 .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.

       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         top

       import [-p num] [-R] [-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)

           -R

               Apply patch in reverse.

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

       new [-p n|-p ab] {patchname}

           Create a new patch with the specified file name, and insert
           it after the topmost patch. The name can be prefixed with a
           sub-directory name, allowing for grouping related patches
           together.

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

               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.

       setup [-d path-prefix] [-v] [--sourcedir dir] [--fuzz=N]
       [--slow|--fast] {specfile|seriesfile}

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

           -d  Optional path prefix for the resulting source tree.

           --sourcedir

               Directory that contains the package sources. Defaults to
               `.'.

           -v  Verbose debug output.

           --fuzz=N

               Set the maximum fuzz factor (needs rpm 4.6 or later).

           --slow
               Use the original, slow method to process the spec file.
               In this mode, rpmbuild generates a working tree in a
               temporary directory while all its actions are recorded,
               and then everything is replayed from scratch in the
               target directory.

           --fast
               Use the new, faster method to process the spec file. In
               this mode, rpmbuild is told to generate a working tree
               directly in the target directory. This is now the
               default.

       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         top

       --trace

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

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

       --version

               Print the version number and exit immediately.

EXIT STATUS         top

       The exit status is 0 if the sub-command was successfully
       executed, and 1 in case of error.

       An exit status of 2 denotes that 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 quilt.

EXAMPLE OF WORKING TREE         top

              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/
              │    │    └── ...
              │    └── ...
              └── ...

       The patches/ directory is precious as it contains all your
       patches as well as the order in which it should be applied.

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

EXAMPLE         top

       Please refer to the pdf documentation for a full example of use.

CONFIGURATION FILE         top

       Upon startup, 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, 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:

       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.

       LESS

           The arguments used to invoke the pager.  Inherits the
           existing value of $LESS if LESS is already set in the
           environment, otherwise defaults to "-FRSX".

       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, recent versions of GNU patch
           support the "--reject-format=unified" option for generating
           reject files in unified diff style (older patch versions used
           "--unified-reject-files" for that).

           You may also want to add the "-E" option if you have issues
           with quilt not deleting empty files when you think it should.
           The documentation of GNU patch says that "normally this
           option is unnecessary", but when patch is in POSIX mode or if
           the patch format doesn't allow to distinguish empty files
           from deleted files, patch deletes empty files only if the -E
           option is given. Beware that when passing -E to patch, quilt
           will no longer be able to deal with empty files, which is why
           using -E is no longer the default.

       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_PC

           The location of backup files and any other data relating to
           the current state of the working directory from quilt's
           perspective. Defaults to ".pc".

       QUILT_PATCHES

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

       QUILT_SERIES

           The name of the series file, defaulting to "series". Unless
           an absolute path is used, the search algorithm described
           above applies.

       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.

       QUILT_PAGER

           The pager 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, "less -R" is
           used.  An empty value indicates that no pager should be used.

       QUILT_COLORS

           By default, quilt uses its predefined color set in order to
           be more comprehensible when distiguishing various types of
           patches, eg.  applied/unapplied, failed, etc.

           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>]

           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

           diff_hdr  Used in 'quilt diff' to color the index line.
                     Defaults to 32 (green).

           diff_add  Used in 'quilt diff' to color added lines. Defaults
                     to 36 (azure).

           diff_mod  Used in 'quilt diff' to color modified lines.
                     Defaults to 35 (purple).

           diff_rem  Used in 'quilt diff' to color removed lines.
                     Defaults to 35 (purple).

           diff_hunk Used in 'quilt diff' to color hunk header. Defaults
                     to 33 (brown/orange).

           diff_ctx  Used in 'quilt diff' to color the text after end of
                     hunk header (diff --show-c-function generates
                     this). Defaults to 35 (purple).

           diff_cctx Used in 'quilt diff' to color the 15-asterisk
                     sequence before or after a hunk. Defaults to 33
                     (brown/orange).

           patch_fuzz
                     Used in 'quilt push' to color the patch fuzz
                     information. Defaults to 35 (purple).

           patch_fail
                     Used in 'quilt push' to color the fail message.
                     Defaults to 31 (red).

           series_app
                     Used in 'quilt series' and 'quilt patches' to color
                     the applied patch names. Defaults to 32 (green).

           series_top
                     Used in 'quilt series' and 'quilt patches' to color
                     the top patch name. Defaults to 33 (brown/orange).

           series_una
                     Used in 'quilt series' and 'quilt patches' to color
                     unapplied patch names. Defaults to 0 (no special
                     color).

           In addition, the clear format name is used to turn off
           special coloring. Its value is 0; it is not advised to modify
           it.

           The content of QUILT_COLORS supersedes default values. So the
           value diff_hdr=35;44 will get you the diff headers in magenta
           over blue instead of the default green over unchanged
           background. For that, add the following content to ~/.quiltrc
           (or /etc/quilt.quiltrc):

           QUILT_DIFF_ARGS="--color"
           QUILT_COLORS='diff_hdr=35;44'

AUTHORS         top

       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         top

       The pdf documentation, which should be under
       /usr/local/share/doc/quilt/quilt.pdf.  Note that some
       distributors compress this file.  zxpdf(1) can be used to display
       compressed pdf files.

       diff(1), patch(1), guards(1).

COLOPHON         top

       This page is part of the quilt (tool to manage series of patches)
       project.  Information about the project can be found at 
       ⟨http://savannah.nongnu.org/projects/quilt⟩.  If you have a bug
       report for this manual page, see
       ⟨http://savannah.nongnu.org/bugs/?group=quilt⟩.  This page was
       obtained from the project's upstream Git repository
       ⟨git://git.savannah.nongnu.org/quilt.git⟩ on 2021-04-01.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2020-12-09.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

quilt                         Dec 17, 2013                      quilt(1)