Also reflow input lines to 72 columns. Index: quilt/doc/quilt.1.in =================================================================== --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@ -8,19 +8,24 @@ quilt \\- tool to manage series of patch [-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. -.PP -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 +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 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 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 +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 .B quilt cmd -h. .PP -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 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" ). @@ -34,63 +39,74 @@ By default, most commands apply to the t .PP Patch files are located in the .I patches -sub-directory of the source tree (see EXAMPLE OF WORKING TREE below). The +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. When not -found in the current directory, that subdirectory is searched +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 +searches for its configuration files). +The .I patches -directory may contain sub-directories. It may also be a symbolic link -instead of a directory. +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 +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. +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 +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. .PP -Different series files can be used to assemble patches in different ways, +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 ``pushed on the stack''), copies of all files -the patch modifies are saved to the +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 +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. +are compared with the current versions of the files in the source tree +using GNU diff. .PP 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 +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). .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. +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 +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" ). @@ -100,13 +116,13 @@ no longer needed, so there is no need to @REFERENCE@ .SH COMMON OPTIONS TO ALL COMMANDS .IP \"\\fB--trace\\fP\" 8 -Runs the command in bash trace mode (-x). For internal debugging. +Runs the command in bash trace mode (-x). +For internal debugging. .IP \"\\fB--quiltrc\\fP file\" 8 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. +/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. .IP \"\\fB--version\\fP\" 8 Print the version number and exit immediately. .SH EXIT STATUS @@ -114,10 +130,10 @@ The exit status is 0 if the sub-command 1 in case of error. .PP 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. +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. .SH EXAMPLE OF WORKING TREE .fam C .RS @@ -145,82 +161,91 @@ The patches/ directory is precious as it well as the order in which it should be applied. .PP The .pc/ directory contains some metadata about the current state of -your patch serie. Changing its content is not advised. This directory -can usually be regenerated from the initial files and the +your patch serie. +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). .SH EXAMPLE Please refer to the pdf documentation for a full example of use. .SH 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. +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. .PP In addition to that, 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. +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 "-FRSX". +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". .IP QUILT_DIFF_OPTS 4 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. +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. .IP QUILT_PATCH_OPTS 4 Additional options that quilt shall pass to GNU patch when applying -patches. For example, recent versions of GNU patch support the +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). +diff style (older patch versions used "--unified-reject-files" for +that). .IP 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. +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. .IP QUILT_DIFFSTAT_OPTS 4 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"). +patch statistics. +For example, "-f0" can be used for an alternative output format. +Recent versions of diffstat also support alternative rounding methods +("-r1", "-r2"). .IP QUILT_PATCHES 4 The location of patch files, defaulting to "patches". .IP QUILT_SERIES 4 -The name of the series file, defaulting to "series". Unless an absolute path -is used, the search algorithm described above applies. +The name of the series file, defaulting to "series". +Unless an absolute path is used, the search algorithm described above +applies. .IP QUILT_PATCHES_PREFIX 4 If set to anything, quilt will prefix patch names it prints with their directory (QUILT_PATCHES). .IP QUILT_NO_DIFF_INDEX 4 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 +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, 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 +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. .IP QUILT_PAGER 4 -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. +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. .IP QUILT_COLORS 4 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. .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>] +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). @@ -228,39 +253,57 @@ Color codes(values) are standard bash co See more at http://tldp.org/LDP/abs/html/colorizing.html#AEN20229 .RS 4 .IP \\fBdiff_hdr\\fP 10 -Used in 'quilt diff' to color the index line. Defaults to 32 (green). +Used in 'quilt diff' to color the index line. +Defaults to 32 (green). .IP \\fBdiff_add\\fP 10 -Used in 'quilt diff' to color added lines. Defaults to 36 (azure). +Used in 'quilt diff' to color added lines. +Defaults to 36 (azure). .IP \\fBdiff_mod\\fP 10 -Used in 'quilt diff' to color modified lines. Defaults to 35 (purple). +Used in 'quilt diff' to color modified lines. +Defaults to 35 (purple). .IP \\fBdiff_rem\\fP 10 -Used in 'quilt diff' to color removed lines. Defaults to 35 (purple). +Used in 'quilt diff' to color removed lines. +Defaults to 35 (purple). .IP \\fBdiff_hunk\\fP 10 -Used in 'quilt diff' to color hunk header. Defaults to 33 (brown/orange). +Used in 'quilt diff' to color hunk header. +Defaults to 33 (brown/orange). .IP \\fBdiff_ctx\\fP 10 -Used in 'quilt diff' to color the text after end of hunk header (diff --show-c-function generates this). Defaults to 35 (purple). +Used in 'quilt diff' to color the text after end of hunk header (diff +--show-c-function generates this). +Defaults to 35 (purple). .IP \\fBdiff_cctx\\fP 10 -Used in 'quilt diff' to color the 15-asterisk sequence before or after a hunk. Defaults to 33 (brown/orange). +Used in 'quilt diff' to color the 15-asterisk sequence before or after a +hunk. +Defaults to 33 (brown/orange). .IP \\fBpatch_fuzz\\fP 10 -Used in 'quilt push' to color the patch fuzz information. Defaults to 35 (purple). +Used in 'quilt push' to color the patch fuzz information. +Defaults to 35 (purple). .IP \\fBpatch_fail\\fP 10 -Used in 'quilt push' to color the fail message. Defaults to 31 (red). +Used in 'quilt push' to color the fail message. +Defaults to 31 (red). .IP \\fBseries_app\\fP 10 -Used in 'quilt series' and 'quilt patches' to color the applied patch names. Defaults to 32 (green). +Used in 'quilt series' and 'quilt patches' to color the applied patch +names. +Defaults to 32 (green). .IP \\fBseries_top\\fP 10 -Used in 'quilt series' and 'quilt patches' to color the top patch name. Defaults to 33 (brown/orange). +Used in 'quilt series' and 'quilt patches' to color the top patch name. +Defaults to 33 (brown/orange). .IP \\fBseries_una\\fP 10 -Used in 'quilt series' and 'quilt patches' to color unapplied patch names. Defaults to 0 (no special color). +Used in 'quilt series' and 'quilt patches' to color unapplied patch +names. +Defaults to 0 (no special color). .RE .RS 4 .PP In addition, the \\fBclear\\fP format name is used to turn off special -coloring. Its value is 0; it is not advised to modify it. +coloring. +Its value is 0; it is not advised to modify it. .PP -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): +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): .PP .nf QUILT_DIFF_ARGS="--color" @@ -269,12 +312,13 @@ the following content to ~/.quiltrc (or .RE .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). +(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. +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 @DOCSUBDIR@/quilt.pdf. Note that some distributors compress this file.
_______________________________________________ Quilt-dev mailing list Quilt-dev@nongnu.org https://lists.nongnu.org/mailman/listinfo/quilt-dev