Import of patch-2.3.tar.gzv2.3

1 files changed, 235 insertions, 74 deletions

diff --git a/patch.man b/patch.man
index 6b2fcfb..a145cf9 100644
--- a/patch.man
+++ b/patch.man
@@ -2,7 +2,7 @@
 .de Id
 .ds Dt \\$4
 ..
-.Id $Id: patch.man,v 1.8 1997/04/17 17:08:15 eggert Exp $
+.Id $Id: patch.man,v 1.16 1997/05/30 08:03:48 eggert Exp $
 .ds = \-\^\-
 .de Sp
 .if t .sp .3
@@ -20,7 +20,7 @@ patch \- apply a diff file to an original
 .Sp
 but usually just
 .Sp
-.BI "patch \-p" number
+.BI "patch \-p" "number"
 .BI < patchfile
 .SH DESCRIPTION
 .B patch
@@ -94,12 +94,16 @@ cannot find a place to install that hunk of the patch, it puts the
 hunk out to a reject file, which normally is the name of the output file
 plus a
 .B \&.rej
-suffix
-(or
+suffix, or
 .B #
 if
 .B \&.rej
-would generate a file name that is too long).
+would generate a file name that is too long
+(if even appending the single character
+.B #
+makes the file name too long, then
+.B #
+replaces the file name's last character).
 (The rejected hunk comes out in ordinary context diff form regardless of
 the input patch's form.
 If the input was a normal diff, many of the contexts are simply null.)
@@ -132,24 +136,37 @@ tries to figure out from the leading garbage what the name of the file
 to edit is.
 If the header is that of a context diff,
 .B patch
-tests for the existence of the old and new files named in the header.
-If there is an
-.B Index:
+takes the old and new file names in the header,
+and if there is an
+.B Index:\&
 line in the leading garbage,
 .B patch
-tests for the existence of the file named in that line.
-If none of the file names refer to existing files, but the patch appears
-to create a file, then
+obtains the name in that line; any
+.B /dev/null
+names are ignored.
+These names are considered to be in the order (old, new, index),
+regardless of the order that they appear in the header.
+If some of the named files exist,
 .B patch
-tries the same file names again, this time testing only for the
-existence of the file names' directory prefix;
+uses the first name if the
+.B POSIXLY_CORRECT
+environment variable is set, and the best name otherwise.
+If no named files exist, some names are given,
+.B POSIXLY_CORRECT
+is not set, and the patch appears to create a file,
 .B patch
-uses the first name with the longest existing prefix.
-If no file name can be intuited from the leading garbage, you are asked
+uses the best name requiring the creation of the fewest directories.
+If no file name results from the above heuristics, you are asked
 for the name of the file to patch.
+To determine the best of a nonempty list of file names,
+.B patch
+first takes all the names with the fewest path name components;
+of those, it then takes all the names with the shortest basename;
+of those, it then takes all the shortest names;
+finally, it takes the first remaining name.
 .PP
 Additionally, if the leading garbage contains a
-.B Prereq:
+.B Prereq:\&
 line,
 .B patch
 takes the first word from the prerequisites line (normally a version
@@ -158,8 +175,10 @@ If not,
 .B patch
 asks for confirmation before proceeding.
 .PP
-If the original file cannot be found or is read-only, but a suitable
+If an
 \s-1RCS\s0 file is handy,
+and the original file cannot be found
+or is read-only and matches the default version,
 and if version control
 (see the
 .B \-V
@@ -169,7 +188,7 @@ option)
 is set to
 .BR existing ,
 .B patch
-attempts to check out and lock the file.
+attempts to get and lock the file.
 \s-1SCCS\s0 is treated in a similar way.
 .PP
 The upshot of all this is that you should be able to say, while in a news
@@ -218,6 +237,15 @@ the simple backup file name for
 is
 .BR /junk/src/patch/util.c .
 .TP
+\fB\*=binary\fP
+Read and write all files in binary mode,
+except for standard output and
+.BR /dev/tty .
+This option has no effect on \s-1POSIX\s0-compliant systems.
+On systems like \s-1DOS\s0 where this option makes a difference,
+the patch should be generated by
+.BR "diff\ \-a\ \*=binary" .
+.TP
 \fB\-c\fP  or  \fB\*=context\fP
 Interpret the patch file as a ordinary context diff.
 .TP
@@ -232,7 +260,7 @@ anything else.
 .TP
 \fB\-D\fP \fIsym\fP  or  \fB\*=ifdef=\fP\fIsym\fP
 Use the
-.B "#ifdef .\|.\|. #endif"
+.BR #ifdef " .\|.\|. " #endif
 construct to mark changes, with
 .I sym
 as the differentiating symbol.
@@ -247,13 +275,25 @@ script.
 .TP
 \fB\-E\fP  or  \fB\*=remove\-empty\-files\fP
 Remove output files that are empty after the patches have been applied.
+Normally this option is unnecessary, since
+.B patch
+can examine the timestamps on the header to determine whether a file
+should exist after patching.
+However, if the input is not a context diff or if the
+.B POSIXLY_CORRECT
+environment variable is set,
+.B patch
+does not remove empty patched files unless this option is given.
+When
+.B patch
+removes a file, it also attempts to remove any empty ancestor directories.
 .TP
 \fB\-f\fP  or  \fB\*=force\fP
 Assume that the user knows exactly what he or she is doing, and do not
 ask any questions.  Skip patches whose headers
 do not say which file is to be patched; patch files even though they have the
 wrong version for the
-.B Prereq:
+.B Prereq:\&
 line in the patch; and assume that
 patches are not reversed even if they look like they are.
 This option does not suppress commentary; use
@@ -269,6 +309,20 @@ Note that a larger fuzz factor increases the odds of a faulty patch.
 The default fuzz factor is 2, and it may not be set to more than
 the number of lines of context in the context diff, ordinarily 3.
 .TP
+\fB\-g\fP  or  \fB\*=get\fP
+If a file does not exist or is read-only and matches the default version,
+get it from \s-1RCS\s0 if it is under \s-2RCS\s0 control;
+similarly for \s-1SCCS\s0.
+If the
+.B PATCH_GET
+environment variable is set, this is the default.
+.TP
+\fB\-G\fP  or  \fB\*=no\-get\fP
+Do not get files from \s-1RCS\s0 or \s-2SCCS\s0.
+This is the default unless the
+.B PATCH_GET
+environment variable is set.
+.TP
 .B "\*=help"
 Print a summary of options and exit.
 .TP
@@ -295,7 +349,7 @@ Interpret the patch file as a normal diff.
 \fB\-N\fP  or  \fB\*=forward\fP
 Ignore patches that seem to be reversed or already applied.
 See also
-.B \-R .
+.BR \-R .
 .TP
 \fB\-o\fP \fIfile\fP  or  \fB\*=output=\fP\fIfile\fP
 Send output to
@@ -335,7 +389,7 @@ Whatever you end up with is looked for either in the current directory,
 or the directory specified by the
 .B \-d
 option.
-With GNU
+With \s-1GNU\s0
 .BR patch ,
 the two-argument
 .BI "\-p " N
@@ -390,7 +444,7 @@ Suppress questions like
 but make some different assumptions:
 skip patches whose headers do not contain file names (the same as \fB\-f\fP);
 skip patches for which the file has the wrong version for the
-.B Prereq:
+.B Prereq:\&
 line
 in the patch; and assume that patches are reversed if they look like
 they are.
@@ -408,12 +462,14 @@ Use
 .I method
 when creating
 backup file names.  The type of backups made can also be given in the
-.B VERSION_CONTROL
+.B PATCH_VERSION_CONTROL
+(or, if that's not set, the
+.BR VERSION_CONTROL )
 environment variable, which is overridden by this option.
 .Sp
 The value of
 .I method
-is like the GNU
+is like the \s-1GNU\s0
 Emacs `version-control' variable;
 .B patch
 also recognizes synonyms that
@@ -426,9 +482,6 @@ accepted):
 \fBexisting\fP  or  \fBnil\fP
 Make numbered backups of files that already have them,
 otherwise simple backups.
-If a file is read-only or does not exist,
-check it out from \s-1RCS\s0 if it is under \s-2RCS\s0 control;
-similarly for \s-1SCCS\s0.
 .TP
 \fBnone\fP
 Do not make backups.
@@ -467,13 +520,13 @@ environment variable if set, and is
 otherwise.
 .PP
 With numbered or simple backups,
-if the backup file name is just another name for the original file,
-.B patch
-creates a new backup file name by changing the first lowercase letter
-in the last component of the file's name into uppercase.  If there are
-no more lowercase letters in the name, it removes the first character
-from the name.  It repeats this process until it fails, or comes up with a
-backup file that is not just another name for the original file.
+if the backup file name is too long, the backup suffix
+.B ~
+is used instead; if even appending
+.B ~
+would make the name too long, then
+.B ~
+replaces the last character of the file name.
 .RE
 .TP
 \fB\-x\fP \fInumber\fP  or  \fB\*=debug=\fP\fInumber\fP
@@ -498,35 +551,57 @@ as the simple backup suffix.
 The backup extension may also be specified by the
 .B SIMPLE_BACKUP_SUFFIX
 environment variable, which is overridden by this option.
-If the backup suffix would create a file name that is too long,
-the backup suffix
-.B ~
-is used instead.
 .SH ENVIRONMENT
 .TP 3
 .B POSIXLY_CORRECT
 If set,
 .B patch
-conforms more strictly to the Posix standard:
-i.e. it requires that all options precede the
+conforms more strictly to the \s-1POSIX\s0 standard:
+it takes the first existing file when intuiting file names from diff headers,
+it does not remove files that are empty after patching,
+and it requires that all options precede the
 files in the command line.
 .TP
-.B TMPDIR
-Directory to put temporary files in; default is
-.BR /tmp .
-.TP
 .B SIMPLE_BACKUP_SUFFIX
 Extension to use for simple backup file names instead of
 .BR \&.orig .
 .TP
-.B VERSION_CONTROL
+\fBTMPDIR\fP, \fBTMP\fP, \fBTEMP\fP
+Directory to put temporary files in;
+.B patch
+uses the first environment variable in this list that is set.
+If none are set, the default is system-dependent;
+it is normally
+.B /tmp
+on Unix hosts.
+.TP
+\fBPATCH_VERSION_CONTROL\fP or \fBVERSION_CONTROL\fP
 Selects version control style; see the
 .B \-v
 or
-.B \*=version_control
+.B \*=version\-control
 option.
+.TP
+\fBPATCH_GET\fP
+If set,
+.B patch
+gets missing or read-only files from \s-1RCS\s0 or \s-1SCCS\s0
+by default; see the
+.B \-g
+or
+.B \*= get
+and the
+.B \-G
+or
+.B \*= no\-get
+options.
 .SH FILES
-.IB $TMPDIR "/patch\(**"
+.TP 3
+.IB $TMPDIR "/p\(**"
+temporary files
+.TP
+.B /dev/tty
+console; used to get answers to questions asked of the user
 .SH "SEE ALSO"
 .BR diff (1),
 .BR ed (1)
@@ -534,35 +609,46 @@ option.
 There are several things you should bear in mind if you are going to
 be sending out patches.
 .PP
-Tell your recipients how to apply the patches.
-This should include which directory to
+Create your patch systematically.
+A good method is the command
+.BI "diff\ \-Naur\ " "old\ new"
+where
+.I old
+and
+.I new
+identify the old and new directories.
+The names
+.I old
+and
+.I new
+should not contain any slashes.
+Here is an example:
+.Sp
+	\fBdiff \-Naur version\-2.2 version\-2.3\fP
+.PP
+Tell your recipients how to apply the patch
+by telling them which directory to
 .B cd
 to, and which
 .B patch
-options to use.  Normally you should specify the
-.BI \-p N
-option with the proper value of
-.IR N .
-The
-.B \-E
-and
-.B \-N
-options are also common.
+options to use.  The option string
+.B "\-Np1"
+is recommended.
 Test your procedure by pretending to be a recipient and applying
-your patches to a copy of the original files.
+your patch to a copy of the original files.
 .PP
 You can save people a lot of grief by keeping a
 .B patchlevel.h
 file which is patched to increment the patch level
 as the first diff in the patch file you send out.
 If you put a
-.B Prereq:
+.B Prereq:\&
 line in with the patch, it won't let them apply
 patches out of order without some warning.
 .PP
 Make sure you've specified the file names right, either in a
 context diff header, or with an
-.B Index:
+.B Index:\&
 line.
 .PP
 You can create a file by sending out a diff that compares an
@@ -573,12 +659,15 @@ This only works if the file you want to create doesn't exist already in
 the target directory.
 Conversely, you can remove a file by sending out a diff that compares the
 file to be deleted with an empty file.
-The file will be left empty, but not actually be removed unless the
+The file will be removed unless the
+.B POSIXLY_CORRECT
+environment variable is set and the
 .B \-E
 or
 .B \*=remove\-empty\-files
-option is given.
-An easy way to generate patches that create and remove files is to use GNU
+option is not given.
+An easy way to generate patches that create and remove files
+is to use \s-1GNU\s0
 .BR diff 's
 .B \*=new\-file
 option.
@@ -588,11 +677,12 @@ If the recipient is supposed to use the
 option, do not send output that looks like this:
 .Sp
 .ft B
-	diff \-uNR v2.0.29/prog/README prog/README
+.ne 3
+	diff \-Naur v2.0.29/prog/README prog/README
 .br
-	\-\-\- v2.0.29/prog/README   Mon Mar 10 15:13:12 1997
+	\-\^\-\^\- v2.0.29/prog/README   Mon Mar 10 15:13:12 1997
 .br
-	+++ prog/README   Mon Mar 17 14:58:22 1997
+	+\^+\^+ prog/README   Mon Mar 17 14:58:22 1997
 .ft
 .Sp
 because the two file names have different numbers of slashes,
@@ -602,19 +692,83 @@ interpret the file names differently.
 To avoid confusion, send output that looks like this instead:
 .Sp
 .ft B
-	diff \-uNR v2.0.29/prog/README v2.0.30/prog/README
+.ne 3
+	diff \-Naur v2.0.29/prog/README v2.0.30/prog/README
 .br
-	\-\-\- v2.0.29/prog/README   Mon Mar 10 15:13:12 1997
+	\-\^\-\^\- v2.0.29/prog/README   Mon Mar 10 15:13:12 1997
 .br
-	+++ v2.0.30/prog/README   Mon Mar 17 14:58:22 1997
+	+\^+\^+ v2.0.30/prog/README   Mon Mar 17 14:58:22 1997
 .ft
 .Sp
 .PP
+Avoid sending patches that compare backup file names like
+.BR README.orig ,
+since this might confuse
+.B patch
+into patching a backup file instead of the real file.
+Instead, send patches that compare the same base file names
+in different directories, e.g.\&
+.B old/README
+and
+.BR new/README .
+.PP
 Take care not to send out reversed patches, since it makes people wonder
 whether they already applied the patch.
 .PP
+Try not to have your patch modify derived files
+(e.g. the file
+.B configure
+where there is a line
+.B "configure: configure.in"
+in your makefile), since the recipient should be
+able to regenerate the derived files anyway.
+If you must send diffs of derived files,
+ensure that the diffs for each derived file
+follow the diffs for the files that it depends on,
+so that the dependencies will be preserved as
+.B patch
+updates the files one by one.
+Here is a sample shell script that output patches in an order that
+should preserve dependencies:
+.nf
+.Sp
+.ft B
+.in +3n
+#! /bin/sh
+.Sp
+.ne 2
+old=${1?}
+new=${2?}
+.Sp
+.ne 10
+fs=
+for f in `
+  diff \-Nqr $old $new |
+  sed \-e "s,.\(** $new/,," \-e 's, differ$,,'`
+do
+  if [ \-f $new/$f ]
+  then fs="$fs $f"
+  else diff \-au $old/$f /dev/null
+  fi
+done
+.Sp
+.ne 10
+case $fs in
+?\(**)
+  for f in `cd $new; ls \-rt $fs`
+  do
+    if [ \-f $old/$f ]
+    then diff \-au $old/$f $new/$f
+    else diff \-au /dev/null $new/$f
+    fi
+  done
+esac
+.in
+.ft
+.fi
+.PP
 While you may be able to get away with putting 582 diff listings into
-one file, it is probably wiser to group related patches into separate files in
+one file, it may be wiser to group related patches into separate files in
 case something goes haywire.
 .SH DIAGNOSTICS
 Diagnostics generally indicate that
@@ -639,6 +793,13 @@ and 2 if there is more serious trouble.
 When applying a set of patches in a loop it behooves you to check this
 exit status so you don't apply a later patch to a partially patched file.
 .SH CAVEATS
+Context diffs cannot reliably represent the creation or deletion of
+empty files, empty directories, or special files such as symbolic links.
+Nor can they represent changes to file metadata like ownership, permissions,
+or whether one file is a hard link to another.
+If changes like these are also required, separate instructions
+(e.g. a shell script) to accomplish them should accompany the patch.
+.PP
 .B patch
 cannot tell if the line numbers are off in an
 .B ed
@@ -662,7 +823,7 @@ could be smarter about partial matches, excessively deviant offsets and
 swapped code, but that would take an extra pass.
 .PP
 If code has been duplicated (for instance with
-.BR "#ifdef OLDCODE .\|.\|. #else .\|.\|. #endif" ),
+\fB#ifdef OLDCODE\fP .\|.\|. \fB#else .\|.\|. #endif\fP),
 .B patch
 is incapable of patching both versions, and, if it works at all, will likely
 patch the wrong one, and tell you that it succeeded to boot.
@@ -700,6 +861,6 @@ Larry Wall wrote the original version of
 Paul Eggert removed
 .BR patch 's
 arbitrary limits, added support for binary files,
-and made it conform better to Posix.
+and made it conform better to \s-1POSIX\s0.
 Other contributors include Wayne Davison, who added unidiff support,
 and David MacKenzie, who added configuration and backup support.