 |
Index for
Section 1 |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
patch(1)
NAME
patch - Applies changes to files
SYNOPSIS
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.
STANDARDS
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.
OPTIONS
-b 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
.orig appended to it. If the file already exists, it is overwritten.
If multiple patches are applied to the same file, the .orig 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.
-B prefix
[Tru64 UNIX] Specifies a prefix to the backup file name.
-c Interprets the patch file as a context diff (the output of diff when -c
or -C is specified).
-d directory
Changes the current directory to directory before processing.
-D define
Uses the C preprocessor #ifdef define ... #endif construct to mark
changes. The define argument is used as the differentiating symbol.
-e Interprets the patch file as an ed script, rather than as a diff
script.
-f [Tru64 UNIX] Suppresses queries to the user. To suppress commentary,
use the -s option.
-F[number]
[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.
-i patchfile
Reads the patch information from the file named by the specified
patchfile, rather than from standard input.
-l 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.
-n Interprets the script as a normal diff.
-N Ignores patches where the differences have already been applied to the
file; by default, already-applied patches are rejected. (See the -R
option.)
-o outfile
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.
-p number
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.
-r rejectfile
Specifies the reject file name. By default, the reject file name has
the same name as the output file, with the suffix .rej appended to it.
-R 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.)
-s [Tru64 UNIX] Patches silently unless an error occurs.
-S [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).
-v [Tru64 UNIX] Prints out the revision header and patch level.
-xnumber
[Tru64 UNIX] Sets internal debugging flags. (This option is of
interest only to patch patchers.)
+ flags [original_file]
[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
originalfile
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 .orig 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 .rej). The rejected 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.
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 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.
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:
0 Successful completion.
1 One or more lines were written to a reject file.
>1 An error occurred.
ENVIRONMENT VARIABLES
The following environment variables affect the execution of patch:
LANG
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.
LC_ALL
If set to a non-empty string value, overrides the values of all the
other internationalization variables.
LC_CTYPE
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).
LC_MESSAGES
Determines the locale for the format and contents of diagnostic
messages written to standard error.
LC_TIME
Determines the locale for recognizing the format of time stamps written
by the diff command.
NLSPATH
Determines the location of message catalogues for the processing of
LC_MESSAGES.
FILES
/tmp/patch*
SEE ALSO
Commands: diff(1)
Standards: standards(5)
|
Index for
Section 1 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|