patch - Applies changes to files
patch [-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, context, or ed-style) and applies those
differences to an original file, producing a patched version.
Interfaces documented on this reference page conform to
industry standards as follows:
patch: XCU5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
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 construct to mark changes. The define argument
is used as the differentiating 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 number 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 outfile. 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. Entering -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 current 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
differences 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.)
The file to be patched.
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 context, 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 message 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 information
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 different 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.
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 create 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 duplicated (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.
[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.
The following exit values are returned: Successful completion.
One or more lines were written to a reject file.
An error occurred.
ENVIRONMENT VARIABLES [Toc] [Back] The following environment variables affect the execution
of patch: Provides 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 variables
contain an invalid setting, the utility behaves as if none
of the variables had been defined. If set to a non-empty
string value, overrides 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 multibyte
characters in arguments). Determines the locale for the
format and contents of diagnostic messages written to
standard error. Determines 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.
Commands: diff(1)
Standards: standards(5)
patch(1)
[ Back ] |
