The scripts in this package simplify working with a series of patches.
The usual tasks like applying, refreshing and reversing are supported.

docco.txt contains Adrew Morton's description of his suite of patch
scripts. These scripts are based on Andrew's scripts, but include many
changes. Please keep this in mind when reading Andrew's documentation.


Concepts
========

(Please see docco.txt.)

The scripts maintain a stack of patches, on top of which additional
patches can be applied, and from with patches can be removed. The list of
patches is kept in a file (searched for in this order in
.pc/series, series, patches/series).

The scripts keep meta information in the .pc/ directory. The .pc/
directory contains:

	.pc/applied-patches
		The list of currently applied patches.

	.pc/patch/.pc (for each applied patch)
		A list of files modified by the patch.

	.pc/patch/ (for each applied patch)
		Copies of the files that the patch modifies,
		before modifying. The original versions of
		the files are needed for refreshing patches,
		and for ensuring that removing a patch does
		recreate the original file contents.


Operation
=========

Patches to be applied must be listed in the series file.

Patches are applied with pushpatch, and are removed with poppatch.

Refpatch refreshes a patch.

New patches can be added at the current position in the patch sequence
with newpatch.

Additional files to be modified can be added to a patch with patchadd.


Installation
============

To start using the scripts the working directory must contain:

	patches/
		Patches to work with.

	series (or patches/series)
		List of patches in order of applying.

The scripts will create the .pc/ directory that contains the meta
information needed for managing the patches automatically.


Series file
===========

The patches that are relevant for a project must be listed in the file
series, which is searched for in .pc/, ./ and patches/ in this order.
The patches will be applied in the order given. The series file has
the following format:

	# Comment
	subdir/patch-file-name.patch [-pN]

The location of patches is specified relative to the patches/ directory.
Optionally a strip level (-p0, -p1, etc.) can be specified. When
refreshing a patch, only levels 0 and 1 are supported.


Command reference
=================
  
quilt 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 on top of the specified
  patch cannot be added.
  
  -p patch
  	Patch to add files to.
  
  
quilt applied [patch]
  
  Print a list of applied patches, or all patches up to and including the
  specified patch in the file series.
  
  
quilt delete [patch]
  
  Remove the specified or topmost patchfrom the series file. If the patch
  is applied, it is first tried to remove it. (Only the topmost patch can
  be removed right now.)
  
  
quilt diff [-p n] [-c patch|-z] [patch]
  
  Produce a diff of the specified patch, or the topmost patch
  by default.
  
  -p n	Create a -p n style patch (-p0 or -p1 supported).
  
  -c patch
  	Create a combined diff for all patches between this
  	patch and the specified or topmost patch.
  
  -z	Write to standard output the changes that have been
  	made relative to the topmost or specified patch.
  
  
quilt files [-v] [patch]
  
  Print the list of files that the topmost or specified patch
  changes.
  
  -v	Verbose, more user friendly output.
  
  
quilt import [-f] [-p num] [-n patch] [patchfile]
  
  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.
  
  -p num
  	Number of directory levels to strip when aplying (default=1)
  
  -n patch
  	File name relative to patches/ to use.
  
  -f	Overwite/update existing patches.
  
  
quilt new {patchname}
  
  Create a new patch with the specified file name, and insert
  it after the topmost patch in the patch series file.
  
  
quilt next [patch]
  
  Print the name of the next patch after the specified or topmost patch in
  the series file.
  
  
quilt contains {file}
  
  Print the list of patches that modify the specified file.
  
  -v	Verbose, more user friendly output.
  
  
quilt pop [-afRqv] [num|patch]
  
  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 up to and
  including the named patch. If neither a number nor a patch
  name is specified, remove the next patch.
  
  -a	Remove all patches in the series file.
  
  -f	Force remove. The state before the patch(es) were
  	applied will be restored from backup files.
  
  -R	Remove the patch with `patch -R' and check if the
  	patch reverts all changes properly.
  
  -q	Quiet operation.
  
  -v	Verbose operation.
  
  
quilt previous [patch]
  
  Print the name of the previous patch before the specified or topmost
  patch in the series file.
  
  
quilt push [-afqv] [num|patch]
  
  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.
  
  -a	Apply all patches in the series file.
  
  -f	Force apply, even if the patch has rejects.
  
  -q	Quiet operation.
  
  -v	Verbose operation.
  
  
quilt refresh [-p n] [-f] [patch]
  
  Refresh an applied patch. Refreshes the specified patch, or
  the topmost patch by default. Documentation on top of the
  actual patch 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, this script prints out the file and patch names.  If
  there are any such conflicts, 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 -pn style patch (-p0 or -p1 supported).
  	
  -f	Force refresh, even if more recent patches modify
  	some of the same files.
  
  
quilt remove [-p patch] {file} ...
  
  Remove one or more files to the topmost or named patch.
  Files that are modified by patches on top of the specified
  patch cannot be removed.
  
  -p patch
  	Patch to add files to.
  
  
quilt rest [patch]
  
  Print a list of patches that are not applied, or all patches that follow
  the specified patch in the series file.
  
  
quilt series [-v]
  
  Print the names of all patches in the file series.
  
  -v	Verbose, more user friendly output
  
quilt setup [-d sourcedir] {seriesfile|specfile}
  
  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.
  
  
quilt top
  
  Print the name of the topmost patch on the current stack of applied
  patches.
  

guards [--prefix=dir] [--path=dir1:dir2:...] [--default=0|1]
       [--check] [--config=file] symbol ...

  Convert a series file with conditional statements into a series
  file as expected; see the guards(1) manual page.


Helper files/scripts
====================

patchfns
	A collection of functions.

apatch
	Add a patch. Used by pushpatch.

rpatch
	Remove a patch. Used by poppatch.

parse-patch {-s|-u} section file [< replacement]
	Select a %section from a patch (-s) or replace a
	%section with the text from standard input (-u).

touched-by-patch filename
	Print a list of files modified by a patch file.

backup-files
	A simple utility that creates / restores / removes
	backup files; this works around a patch bug (see BUGS).

