patch(1) CLIX patch(1)
NAME
patch - Applies the changes from a diff listing to an original file
SYNOPSIS
patch [flags] orig_file patchfile [+ [flags] orig_file]
patch < patchfile
FLAGS
-b extension Specifies the backup extension, to be used in place of
.orig or ~.
-B prefix Specifies a prefix to the backup file name. Any argument
from the -b flag is ignored.
-c Interprets the patch file as a context diff listing.
-d dir_name Changes to the specified directory before performing any
other tasks.
-D symbol Uses the #ifdef...#endif construct to mark changes. The
argument following the flag is used as the differentiating
symbol (for example, a greater than sign >). Note that,
unlike the C compiler, there must be a space between the -D
flag and the argument.
-e Interprets the patch file as an ed script.
-f Supresses all prompts. However, this flag does not supress
messages. (See the -s flag.)
-Fnumber Sets the maximum number of lines to ignore when installing
a piece of a patch. (The ignored lines are sometimes
called the fuzz factor.) This flag only applies to context
difference listings. Note that a larger number of ignored
lines increases the odds of a faulty patch. The default
number of lines to ignore is 2. The ignored number of
lines cannot be set to more than the number of lines of
context in the context diff listing (this number is usually
3 lines).
-l Does the pattern matching loosely, in case the <Tab>
characters and spaces have been deleted in the input file.
Any sequence of whitespace in the pattern line matches any
sequence in the input file. Alphanumeric characters must
still match exactly. Each line of the context file must
still match a line in the input file.
2/94 - Intergraph Corporation 1
patch(1) CLIX patch(1)
-n Interprets the patch file as a normal diff listing.
-N Ignores patches that seem to be reversed or already
applied. See also the -R flag.
-o Specifies the output file name.
-pnumber Sets the pathname strip count. The strip count controls
how pathnames found in the patch file are treated. The
strip count specifies how many slashes are to be stripped
from the front of the pathname. Any intervening directory
names are removed.
For example, the following filename is in the patch file:
/usr/glenn/src/rebar/rebar.c
The following examples show how the pathname changes with
the -p flag:
Using -p or -p0 does not strip any slashes or directory
names from the pathname, so the pathname remains
/usr/glenn/src/rebar/rebar.c.
Using -p1 removes the first slash, so the pathname is
usr/glenn/src/rebar/rebar.c.
Using -p4 removes four slashes and the intervening
directories, so the pathname is rebar/rebar.c.
However, not using the -p flag at all makes the pathname
simply the name of the file, which is rebar.c.
Whatever pathname results from using or not using the -p
flag, that pathname is used to search the current
directory, or the directory specified with the -d flag.
-r Specifies the name of the reject file. The reject file
contains the pieces of the patch that could not be applied
to the original file.
-R Reverses each piece of a patch before applying it to the
original file. (This flag is useful is the patch was
created with the old and new files swapped.)
When the original file is patched, patch tries to apply one
piece of the patch at a time. If the first piece of a
patch fails, patch reverses the piece to see if it can be
applied that way. If it can, the user is then asked is the
-R flag is to be set to reverse every subsequent piece.
2 Intergraph Corporation - 2/94
patch(1) CLIX patch(1)
If the piece of the patch cannot be applied in reverse,
patch places the piece in the reject file and continues
with the next piece of the patch.
The -R flag does not work with ed scripts because there is
too little information to reconstruct the reverse
operation.
Note: the -R flag cannot detect a reversed patch if the
patch is a normal diff listing, and if the first command is
an append. The append commands always succeed, since a
null context matches anything. Most patches add or change
lines rather then delete them; so most normal diff
listings begin with a delete, which causes patch to try
reversing the patch.
-s Suppresses all messages, unless an error occurs.
-S Ignores the current piece of the patch from the patch file,
but continues to look for the next piece in the file. The
following command ignores the first and second pieces in a
patch file. (The plus sign + separates flag lists; see
the DESCRIPTION section for more information.)
patch -S + -S + <patchfile
-v Prints the revision header and patch level of the patch.
-xnumber Sets internal debugging flags.
DESCRIPTION
The patch command takes a patch file (that is, a file containing any of
the three forms of difference listings produced by the diff command), and
applies those differences in the file to an original file. The final file
produced is a patched version of the original file. By default, the
patched version is put in place of the original file. The original file
is backed up to a file with the same name, and has the extension .orig or
~. (Another extension may be specified with the -b flag.)
The user may also specify an output file with the -o flag. If the name of
the patch file is omitted, or is a hyphen, the patch command reads from
stdin.
Upon startup, patch attempts to determine the type of the diff listing,
unless overruled by the -c, -e, or -n flags. Context diff listings and
normal diff listings are applied by the patch utility itself, while diff
listings interpreted as ed scripts are simply piped to the ed editor.
The patch command tries to skip any leading text, apply the changes, and
2/94 - Intergraph Corporation 3
patch(1) CLIX patch(1)
then skip any trailing text. Thus, a user could give an article or
message containing a diff listing to patch, and it should work. If the
entire diff listing is indented by a consistent amount of space, patch
takes this into account. For example, while the user is using a news
interface, the following command can be used:
| patch -d /usr/src/local/fixes
This command patches a file in the fixes directory directly from the
article containing the patch.
With context diff listings, and to a lesser extent with normal diff
listings, patch can detect when the line numbers in the patch are
incorrect, and will attempt to find the correct place to apply each piece
of the patch. As a first guess, patch takes the line number for the
piece, plus or minus any offset used in applying the previous piece. If
that is not the correct place, patch scans both forwards and backwards for
a set of lines matching the context given in the piece. First, patch
looks for a place where all lines of the context match. If no such place
is found, and it is a context diff listing, and the maximum number of
lines to ignore (the fuzz factor) is set to 1 or more, then another scan
takes place, ignoring the first and last line of context. If that scan
fails, and the maximum number of lines to ignore is set to 2 or more, the
first two and last two lines of context are ignored, and another scan is
made.
If patch cannot find a place to install a piece of the patch, it puts the
piece in a reject file, which normally is the name of the output file plus
.rej or #. (Note: the rejected piece is in the form of a context diff
listing even if the input patch was a context diff listing or a normal
diff listing. If the input was a normal diff listing, many of the contexts
will simply be null.) The line numbers of the pieces in the reject file
may be different than in the patch file; they reflect the approximate
location patch thinks the failed pieces belong in the new file rather than
the old one.
As each piece is completed, the user is told whether the piece was
successfully applied or not, and on which line (in the new file) patch
thought the piece should go on. If this line number is different from the
line number specified in the diff listing, the user is told about the
offset. A single large offset may be an indication that a piece was
installed in the wrong place. The user is also told if lines were ignored
to make the match, which may also indicate the piece was put in the wrong
place.
If no original file is specified on the command line, patch tries to
figure out from the leading text what the filename is. In the header of a
context diff listing, the filename is found from lines beginning with
three asterisks *** or three dashes ---. The shortest name of an existing
file is used. Only context diff listings have such lines, but if there is
4 Intergraph Corporation - 2/94
patch(1) CLIX patch(1)
an Index: line in the leading text, patch tries to use the filename from
that line. The context diff listing header takes precedence over an
Index: line. If no filename can be found in the leading text, the user is
asked for the name of the file to patch. (If the original file cannot be
found, but a suitable SCCS or RCS file is found, patch attempts to check
out the file.)
Additionally, if the leading text contains a Prereq: line, patch takes the
first word from the line (usually a version number) and checks the input
file to see if that word can be found. If not, patch asks the user for
confirmation before proceeding.
If the patch file contains more than one patch, the patch command tries to
apply each patch as if it came from a separate patch file. It is assumed
that the name of the file to patch must be determined for each diff
listing, and that the text before each diff listing will be examined for
filenames and revision levels. The user can give flags (and another
original file name) for the second and subsequent patches by separating
the corresponding flag lists with a plus sign +. (The flag list for a
second or subsequent patch can not specify a new patch file, however.)
EXAMPLES
This example shows a typical use of patch. The following is the original
program named test.c:
main()
{
int a,b;
int c;
a=10;
b=30;
c=40;
printf("%d0,a*b);
printf("%d0,a+b);
printf("%d0,a/b);
printf("%d0,c-b);
}
The revised version of the test.c file is as follows, and is named
test2.c:
main()
{
int a,b;
int c;
a=10;
b=30;
2/94 - Intergraph Corporation 5
patch(1) CLIX patch(1)
c=40;
printf("%d0,a*b);
printf("%d0,a+b);
printf("%d0,a/b);
printf("%d0,c-b);
}
A patch file can be created from test.c and test2.c using the following
command:
diff -e test.c test2.c > patch.1
The file patch.1 contains a script of the a, c, and d commands for the
editor ed. The patch.1 file can now be used by the patch command to
recreate test2.c from test.c. To recreate test2.c from test.c, use the
following command:
patch test.c patch.1
The test.c file is now identical to the test2.c file.
FILES
/tmp/patch*
NOTES
There are several things users should keep in mind if they are going to be
sending out file patches:
1. The user can prevent mistakes by maintaining a patchlevel.h file,
which is patched to increment the patch level as the first difference
in the patch file to be distributed. If the user places a Prereq:
line in with the patch, patch will not let other users apply patches
out of order without some warning.
2. Make sure the filenames are specified correctly, either in a context
diff header, or with an Index: line. If the patch affects a file in a
subdirectory, be sure to tell other users to specify a -p flag as
needed.
3. The user can create a file by distributing a diff file that compares a
null file to the file the user wants to create. This method only
works if the file the user wants to create does not exist already in
the target directory.
4. Take care not to send out reversed patches. This may confuse other
users, who may think they have already applied the patch.
6 Intergraph Corporation - 2/94
patch(1) CLIX patch(1)
5. While the user may be able to put up to 582 diff listings into one
file, it is probably wiser to group related patches into separate
files.
CAUTIONS
Compiling without errors is a good indication that the patch worked, but
not always.
The patch command cannot tell if the line numbers are off in an ed script,
and can only detect bad line numbers in a normal diff file when it finds a
change or a delete command. A context diff using the -F3 flag may have
the same problem. The user should check the context in these cases to see
if the changes seem correct.
The patch command usually produces the correct results, even when it has
to do a lot of guessing. However, the results are guaranteed to be
correct only when the patch is applied to exactly the same version of the
file that the patch was generated from.
The patch command sometimes produces errors with partial matches,
nonstandard offsets, and swapped code.
If code has been duplicated (for example, with #ifdef OLDCODE ... #else
... #endif), patch is incapable of patching both versions. If the patch
works at all, patch will likely patch the wrong one, and tell the user
that it succeeded.
If the user applies a patch that has been already applied, patch will
think it is a reversed patch, and offer to remove the existing patch.
DIAGNOSTICS
The diagnostics of the patch are intended to be self-explanatory.
The message "Hmm..." indicates that the patch command has found some
unprocessed text in the patch file, and is attempting to find a patch in
that text and decide what kind of patch it is.
EXIT VALUES
The patch command exits with a non-zero status if any reject files are
created. When applying a set of patches in a loop, the user should check
this exit status so that a later patch is not applied to a partially-
patched file.
RELATED INFORMATION
Commands: diff(1), ed(1)
2/94 - Intergraph Corporation 7