[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Commands Reference, Volume 4
patch Command
Purpose
Applies changes to files.
Syntax
patch [ -b [ -B Prefix ] ] [ -f ] [ -l ] [ -N ]
[ -R ] [ -s ] [ -v ] [ -c | -e |
-n ] [ -d Directory ] [ -D Define ] [ -F Number ] [ -i PatchFile ] [ -o OutFile ] [ -p Number ] [ -r RejectFile ] [ -x Number ] [ File ]
Description
The patch command reads a source
file's instructions on how to change a file, then applies the changes. The
source file contains difference listings (or diff
listings) produced by the diff
command. The diff listings are the result of comparing two files and building
instructions about how to reconcile the differences. By default, the patch command uses the source file read from standard input, but this
can be overridden using the -i flag and the PatchFile variable.
Diff listings come in three formats: normal, context,
or in the style of the ed editor. The patch command
determines the diff listing format, unless overruled by the -c, -e, or -n flags.
By default, the patched version of a file replaces
the original version. When the -b flag is specified,
the original of each patched file is saved in a file of the same name with
the suffix .orig appended to it. You may also specify
where you want the output to go with the -o flag.
The -p flag makes it possible
to customize a patch file to local user directory structures without manually
editing the patch file. This is done by specifying how many components to
remove from the full path name. For example, if the patch file contained the
path name /curds/whey/src/blurfl/blurfl.c, then:
- -p 0 causes the entire
path name to be used.
- -p 1 removes the leading
slash, leaving curds/whey/src/blurfl/blurfl.c.
- -p 4 removes leading
slashes and the first three directories, leaving blurfl/blurfl.c.
Not specifying the -p flag causes
the patch command to use the base name. In the above
example, that would be blurfl.c.
Patch File Format
The patch file must contain one or more lines of header
information followed by one or more patches. Each patch must contain one or
more lines of file name identification in the format produced by the diff -c command, and one or more
sets of diff command output, customarily called hunks.
The patch command skips any
leading text in a patch file, applies the actual diff listing, and skips any
trailing text. Thus, you could use as a patch file an article or message that
includes a diff listing, and the patch command would
still work. In such a case, if the entire diff listing is indented by a consistent
amount, the patch command will also adjust for that
spacing.
To change a line range within the original file, each
hunk within a patch must be a separate diff listing. The line numbers for
successive hunks within a patch must occur in ascending order.
File Name Determination
If no File parameter is specified,
the patch command performs the following steps to obtain
the name of the file to edit:
- In the header of a context diff listing,
the file name is determined from lines beginning with *** (three asterisks)
or --- (three dashes). A line beginning with *** indicates the name of
the file from which the patches were taken, while a line beginning with ---
indicates the name of the file to which the patches should be applied. The
shortest name of an existing file is selected.
- If there is an Index: line in the leading text, the patch command tries
to use the file name from that line.
- A context diff header takes precedence over
an Index: line.
- If no file name can be determined from the
leading text, the patch command prompts 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, the patch
command attempts to get or check out the file.
- If the leading text contains a Prereq: line, the patch command 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, the patch command prompts you for confirmation before proceeding.
Patch Application
If the patch file contains more than one patch, the patch command tries to apply each diff listing as if it
came from a separate patch file. In this case, the name of the file to patch
is determined for each diff listing, and the header text before each diff
listing is examined for information such as file name and revision level.
If you specify the -c, -e, or -n flag, the patch
command interprets information within each hunk as a context difference, an
ed editor difference, or a normal difference, respectively. Otherwise, the patch command determines the type of difference based on
the format of the information within the hunk.
The patch command searches for
the place to apply each hunk by taking the first line number of the hunk and
adding or subtracting any line offset caused by applying the previous hunk.
If an exact match is not possible at this line location, the patch command scans both forward and backward for a set of lines matching
the hunk's content exactly.
If no such place is found, and if the patch command is applying a context diff listing, the patch command can search for a less exact match. A fuzz factor specifies how many lines can be inexactly matched. If the
fuzz factor is set to 1 or more, the patch command performs
a second scan, this time ignoring the first and last line of context. If no
match results, and the maximum fuzz factor is set to 2 or more, the patch command performs a third scan, this time ignoring the first two
lines and the last two lines of the context. (The default maximum fuzz factor
is 2.) If no match is found, the patch command places
the hunk in a reject file. The reject file is created with the same name as
the output file and the suffix .rej. This naming convention
can be overridden by using the -r flag.
The rejected hunk is written in context diff listing
form, regardless of the format of the patch file. If the input was a normal
or ed editor style difference, the reject file may contain differences with
zero lines of context format. The line numbers on the hunks in the reject
file may be different from the line numbers in the patch file. This is because
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, the patch command tells you whether the hunk succeeded or failed. You are also
informed of the new line number assumed for each hunk. If this is different
from the line number specified in the diff listing, you are notified of the
offset. The patch command also tells you if a fuzz factor
was used to make the match.
Note: A single large
offset may be an indication that a hunk was installed in the wrong place.
Use of a fuzz factor may also indicate bad placement.
Preparing Patches for Other Users
Programmers preparing patches that will be shipped
to other users should consider the following additional guidelines:
- If you try to apply the same patch twice,
the patch command assumes the second application should
be a reverse patch and prompts you for confirmation of this reversal. Therefore,
avoid sending out reversed patches, since this makes users wonder whether
they already applied the patch.
- It is recommended that you keep a patchlevel.h file that is updated with the latest patch level. The patch
level can then be used as the first diff listing in the patch file you send
out. If your patch includes a Prereq: line, users
cannot apply patches out of order without receiving a warning.
- Make sure you specify the file names correctly,
either in a context diff listing 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 flag as needed.
- You can create a file by sending out a diff
listing that compares a null file to the file you want to create. However,
this only works if the file you want to create does not already exist in the
target directory.
- While you may be able to put many diff listings
into one file, it is advisable to group related patches into separate files.
- The patch command cannot
tell if the line numbers are incorrect in an ed script, and can only detect
bad line numbers in a normal diff listing when it finds a change or a delete
command. A context diff listing using a fuzz factor of 3 may have the same
line-number problem. Until a suitable interactive interface is added, use
a context diff listing in such cases to check the changes for accuracy. Compilation
without errors usually means that the patch worked, but it is not an infallible
indicator.
- The results of the patch command are guaranteed only when the patch is applied to exactly the
same version of the file from which the patch was generated.
- If the code has been duplicated, for example:
#ifdef
... NEWCODE
#else
... OLDCODE
# endif
the patch command is incapable of patching
both versions. If the patch command succeeds, it may
have patched the wrong version and return a successful exit status.
Flags
-b |
Saves a copy of each modified file before the differences are applied.
The copied original is filed with the same name and the suffix .orig. If a file by that name already exists, it is overwritten. If multiple
patches are applied to the same file, only one copy is made of the original
file at the time of the first patch. If the -o OutFile flag is also specified, the .orig file
is not created. But if the specified out file already exists, OutFile.orig is created. |
-B Prefix |
Specifies a prefix to the backup file name. This flag only works
in conjunction with the -b flag. |
-c |
Interprets the patch file as a context diff listing (the output of
the diff -c or diff -C command).
This flag cannot be used with the -e or -n flag. |
-d Directory |
Changes the current directory to the specified directory before processing. |
-D Define |
Marks changes with the following C preprocessor construct:
#ifdef Define
... (NEWCODE)
#else
... (OLDCODE)
#endif /* Define */
The Define variable is used as the differentiating symbol. This flag only
works when the normal or context form of diff listing is used as a patch file. |
-e |
Interprets the patch file as an ed editor script. This flag cannot
be used with the -c or -n flag. |
-f |
Suppresses queries to the user. To suppress commentary, use the -s flag. |
-F Number |
Sets the maximum fuzz factor. This flag applies to context diff listings
only and causes the patch command to ignore the specified
number of lines when determining where to install a hunk. If the -F flag is not specified, the default fuzz factor is 2. The factor may
not be set to more than the number of lines of content in the context diff
listing (ordinarily 3).
Note: A larger fuzz factor
increases the odds of a faulty patch. |
-i PatchFile |
Reads the patch information from the specified file, rather than
from standard input. |
-l |
(lowercase L) Causes any sequence of blank characters in the diff
listing script to match any sequence of blank characters in the input file.
Other characters are matched exactly. |
-n |
Interprets the script as a normal diff listing. This flag cannot
be used with the -c or -e flag. |
-N |
Ignores patches where the differences have already been applied to
the file. By default, already-applied patches are rejected. |
-o OutFile |
Copies the files to be patched, applies the changes, then writes
the modified version to the specified output file. Multiple patches for a
single file are applied to the intermediate versions of the file created by
any previous patches. Therefore, multiple patches result in multiple, concatenated
versions of the output file. |
-p Number |
Sets the path name strip count, which controls how path names found
in the patch file are treated. This flag is useful if you keep your files
in a directory different from the specified path. The strip count specifies
how many slashes are stripped from the front of the path name. Any intervening
directory names are also stripped. For example, assume a patch file specified /u/leon/src/blurf1/blurf1.c:
- -p 0 leaves
the entire path name unmodified.
- -p 1 removes
the leading slash, leaving u/leon/src/blurf1/blurf1.c.
- -p 4 removes four slashes and
three directories, leaving blurf1/blurf1.c.
If the -p flag is not specified,
only the base name (the final path name component) is used. This flag works
only when the File parameter is not specified. |
-r RejectFile |
Overrides the default reject file name. The default reject file name
is formed by appending the suffix .rej to the original
file name. |
-R |
Reverses the sense of the patch script. For example, if the diff
listing was created from new version to old version, using the -R flag causes the patch command to reverse each
portion of the script before applying it. Rejected differences are saved in
swapped format. The -R flag cannot be used with ed scripts,
because there is too little information to reconstruct the reverse operation.
If the -R flag is not specified, the patch command attempts to apply each portion in its reversed sense as
well as in its normal sense, until a portion of the patch file is successfully
applied. If the attempt is successful, the user is prompted to determine if
the -R flag should be set.
Note: This method cannot detect a reversed patch if used with a normal
diff listing where the first command is an append (that is, would have been
a delete). Appends always succeed because a null context matches anywhere.
Fortunately, most patches add or change lines rather than delete lines. Therefore
most reversed normal diff listings begin with a delete, causing a failure
and triggering heuristics. |
-s |
Patches silently unless an error occurs. |
-v |
Prints the revision header and patch level. If the -v flag is used with other flags, the other flags are ignored. |
-x Number |
Sets internal debugging flags. This flag is only for patch command developers. |
Exit Status
The following exit values are returned:
0 |
Successful completion. |
1 |
An error occurred. |
Examples
- To apply diff listings in the difflisting file to the prog.c file, enter:
patch -i difflisting prog.c
- To save the original version of the prog.c file, enter:
patch -b -i difflisting prog.c
This applies changes to prog.c and saves
the original contents of prog.c in the file prog.c.orig.
- To patch the prog.c file without altering the original version, enter:
patch -i difflisting -o prog.new prog.c
This uses prog.c as a source file, but the changed version is written to a file
named prog.new.
Files
/usr/bin/patch |
Contains the patch command. |
Related Information
The diff command, ed command.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]