patch(1)patch(1)NAMEpatch - Applies changes to files
SYNOPSISpatch [-bflsvNRS] [-c | -e | -n] [-B prefix] [-d directory] [-D
define] [-F] [number] [-i patchfile] [-o outfile] [-p number] [-r
rejectfile] [original_file] [patchfile] [+] [flags] [original_file]
The patch command takes a patch file that contains any of the three
forms of difference listing produced by the diff program (normal, con‐
text, or ed-style) and applies those differences to an original file,
producing a patched version.
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
patch: XCU5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
OPTIONS
Saves a copy of the original contents of each modified file, before the
differences are applied in a file of the same name with the suffix
appended to it. If the file already exists, it is overwritten. If
multiple patches are applied to the same file, the file is written only
for the first patch. If -o outfile is also specified, patchfile.orig
will not be created, but if outfile already exists, outfile.orig is
created. [Tru64 UNIX] Specifies a prefix to the backup file name.
Interprets the patch file as a context diff (the output of diff when -c
or -C is specified). Changes the current directory to directory before
processing. Uses the C preprocessor #ifdef define ... #endif con‐
struct to mark changes. The define argument is used as the differenti‐
ating symbol. Interprets the patch file as an ed script, rather than
as a diff script. [Tru64 UNIX] Suppresses queries to the user. To
suppress commentary, use the -s option. [Tru64 UNIX] Sets the maximum
fuzz factor. This option applies to context diffs only, and causes
patch to ignore up to the specified number of lines when determining
where to install a hunk. If the -F option is not specified, the
default fuzz factor is 2. If the -F option is specified without a num‐
ber argument, the fuzz factor is taken to be 0 (zero). The factor may
not be set to more than the number of lines of context in the context
diff (ordinarily 3).
[Tru64 UNIX] Note that a larger fuzz factor increases the odds
of a faulty patch. Reads the patch information from the file
named by the specified patchfile, rather than from standard
input. Causes any sequence of spaces and tabs (whitespace) in
the diff script to match any sequence of spaces in the input
file. Other characters will be matched exactly. Interprets the
script as a normal diff. Ignores patches where the differences
have already been applied to the file; by default, already-
applied patches are rejected. (See the -R option.) Instead of
modifying the files (specified by the patchfile argument or the
diff listings) directly, write a copy of the file referenced by
each patch, with the appropriate differences applied, to out‐
file. Multiple patches for a single file are applied to the
intermediate versions of the file created by any previous
patches, and result in multiple, concatenated versions of the
file written to outfile. Sets the path name strip count, which
controls how path names found in the patch file are treated.
This option is useful if you keep your files in a different
directory than that specified by the patch. The strip count
specifies how many slashes are to be stripped from the front of
the path name. Any intervening directory names are also
stripped.
For example, if the file name in the patch file was
/u/howard/src/blurfl/blurfl.c, entering -p0 leaves the entire
path name unmodified. Entering -p1 results in
u/howard/src/blurfl/blurfl.c without the leading slash. Enter‐
ing -p4 results in blurfl/blurfl.c. Omitting -p from the patch
command line, results in blurfl.c.
The patch command looks for the resulting path name in the cur‐
rent directory, or in the directory specified by the -d option.
Specifies the reject file name. By default, the reject file
name has the same name as the output file, with the suffix
appended to it. Reverses the sense of the patch script; that
is, patch assumes that the diff script was created from the new
version to the old version. The patch command tries to reverse
each portion of the script before applying it. Rejected differ‐
ences are saved in swapped format. The -R option cannot be used
with ed scripts because there is too little information to
reconstruct the reverse operation.
If this option is not specified, and until a portion of the
patch file is successfully applied, patch tries to apply each
portion in its reversed sense as well as in its normal sense.
If the attempt is successful, you are prompted to determine if
-R should be set.
Note that this method cannot detect a reversed patch if it is a
normal diff and if the first command is an append (that is, it
should have been a delete), since appends always succeed because
a NULL context matches anywhere. Luckily, most patches add or
change lines rather than delete them, so most reversed normal
diffs begin with a delete, which will fail, triggering the
heuristic.) [Tru64 UNIX] Patches silently unless an error
occurs. [Tru64 UNIX] Ignores a patch from the patch file, but
continues looking for the next patch in the file. Thus, patch-S + -S + <patchfile
ignores the first and second patches in patchfile (see the
description of the + offset that follows). [Tru64 UNIX] Prints
out the revision header and patch level. [Tru64 UNIX] Sets
internal debugging flags. (This option is of interest only to
patch patchers.) [Tru64 UNIX] Specifies flags (and possibly
another original file name) for the second and subsequent
patches. The argument list for each patch must be preceded with
a +. (Note, however, that the argument list for a second or
subsequent patch may not specify a new patch file.)
OPERANDS
The file to be patched.
DESCRIPTION
By default, the patched version is put in place of the original. The
original file can be backed up to the same name with the extension by
using the -b option. You may also specify where you want the output to
go with the -o option. If the -i patchfile option is not specified, or
if patchfile is a - (dash), the patch is read from standard input.
The patch command attempts to determine the type of the diff listing,
unless it is overruled by a -c, -e, or -n option, which specify con‐
text, ed, and normal diffs, respectively. Context diffs and normal
diffs are applied by the patch program itself, while ed diffs are fed
to the ed editor by means of a pipe.
The patch file must contain zero or more lines of header information
followed by one or more patches. Each patch must contain zero or more
lines of file name identification in the format produced by diff -c,
and one or more sets of diff output, which are customarily called
“hunks”.
The patch command tries to skip any leading text, apply the diff, and
then skip any trailing text. Thus, you could feed an article or mes‐
sage containing a diff listing to patch, and it would work. If the
entire diff is indented by a consistent amount, patch takes this into
account.
If no original file is specified on the command line, patch tries to
figure out the name of the file to edit from the leading text. In the
header of a context diff, the file name is found from lines beginning
with *** (the name of the file from which the patches arose) or ---
(the name of the file to which the patches should be applied), with the
shortest name of an existing file being selected. If there is an
Index: line in the leading text, patch tries to use the file name from
that line. The context diff header takes precedence over an Index:
line. If no file name can be determined from the leading text, patch
asks you for the name of the file to patch.
If the original file cannot be found, but a suitable SCCS or RCS file
is available, patch attempts to get or check out the file.
Additionally, if the leading text contains a Prereq: line, patch takes
the first word from the prerequisites line (normally a version number)
and checks the input file to see if that word can be found. If not,
patch asks for confirmation before proceeding.
If the patch file contains more than one patch, patch tries to apply
each of them as if they came from separate patch files. In this case,
the name of the file to patch must be determined for each diff listing,
and the header text before each diff listing is examined for informa‐
tion such as file names and revision level. You can give options (and
another original file name) for the second and subsequent patches by
separating the corresponding argument lists with a +.
For each hunk, patch takes the line number mentioned for the hunk, plus
or minus any offset used in applying the previous hunk. If that is not
the correct place, patch scans both forwards and backwards for a set of
lines matching the context given in the hunk. The patch command looks
for a place where all lines of the context match.
If no such place is found, and patch is performing a context diff, and
the maximum fuzz factor is set to 1 or more, patch performs another
scan that ignores the first and last line of context. If that scan
fails, and the maximum fuzz factor is set to 2 or more, patch ignores
the first two and last two lines of context, and makes another scan.
(The default maximum fuzz factor is 2.)
If patch cannot find a place to install that hunk of the patch, it
places the hunk in a reject file (normally, with the same name as the
output file and the suffix hunk is written in context diff form,
regardless of the format of the patch file. If the input was a normal
or ed-style diff, the reject file may contain diffs with zero lines of
context. The line numbers on the hunks in the reject file may be dif‐
ferent from the line numbers in the patch file; the reject file line
numbers reflect the approximate locations for the failed hunks in the
new file rather than the old one.
As each hunk is completed, patch tells you whether the hunk succeeded
or failed, and on which line in the new file patch assumed the hunk
should go. If this is different from the line number specified in the
diff, patch tells you the offset. A single large offset may be an
indication that a hunk was installed in the wrong place. The patch
command also tells you if a fuzz factor was used to make the match, in
which case you should be slightly suspicious.
NOTES
There are several things you should bear in mind if you are going to be
sending out patches: [Tru64 UNIX] It is recommended that you keep a
<patchlevel.h> file that is patched to increment the patch level as the
first diff in the patch file you send out. If you put a Prereq: line
in with the patch, users will not be able to apply patches out of order
without some warning. [Tru64 UNIX] Make sure you specify the file
names correctly, either in a context diff header or with an Index:
line. If you are patching something in a subdirectory, be sure to tell
the patch user to specify a -p option as needed. [Tru64 UNIX] You can
create a file by sending out a diff that compares a null file to the
file you want to create. This works only if the file you want to cre‐
ate does not already exist in the target directory. [Tru64 UNIX] Take
care not to send out reversed patches, since this makes users wonder
whether they already applied the patch. [Tru64 UNIX] While you may be
able to put many diff listings into one file, it is advisable to group
related patches into separate files. [Tru64 UNIX] 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 when it finds a change or a
delete command.
[Tru64 UNIX] A context diff using a fuzz factor of 3 may have
the same problem. Until a suitable interactive interface is
added, you should probably do a context diff in these cases to
see if the changes make sense. Compiling without errors is a
pretty good indication that the patch worked, but this is not an
infallible indicator. [Tru64 UNIX] The results of the patch
command are guaranteed to be correct only when the patch is
applied to exactly the same version of the file from which the
patch was generated. [Tru64 UNIX] If the code has been dupli‐
cated (for example, with #ifdef OLDCODE ... #else ... #endif),
patch is incapable of patching both versions, and, if patch
works at all, it will likely patch the wrong version and tell
you that it succeeded. If you apply a patch you've already
applied, patch assumes it is a reversed patch, and offers to
undo it.
DIAGNOSTICS
[Tru64 UNIX] The message Hmm... indicates that there is unprocessed
text in the patch file and that patch is attempting to determine
whether there is a patch in that text and, if so, what kind of patch it
is.
[Tru64 UNIX] The patch command exits with a nonzero status if any
reject files were created. When applying a set of patches in a loop,
you should check this exit status, so you don't apply a later patch to
a partially patched file.
EXIT STATUS
The following exit values are returned: Successful completion. One or
more lines were written to a reject file. An error occurred.
ENVIRONMENT VARIABLES
The following environment variables affect the execution of patch: Pro‐
vides a default value for the internationalization variables that are
unset or null. If LANG is unset or null, the corresponding value from
the default locale is used. If any of the internationalization vari‐
ables contain an invalid setting, the utility behaves as if none of the
variables had been defined. If set to a non-empty string value, over‐
rides the values of all the other internationalization variables.
Determines the locale for the interpretation of sequences of bytes of
text data as characters (for example, single-byte as opposed to multi‐
byte characters in arguments). Determines the locale for the format
and contents of diagnostic messages written to standard error. Deter‐
mines the locale for recognizing the format of time stamps written by
the diff command. Determines the location of message catalogues for
the processing of LC_MESSAGES.
FILESSEE ALSO
Commands: diff(1)
Standards: standards(5)patch(1)
