patch - a program for applying a diff file to an original
patch [-bEflNRrsTtvZ] [-c|-e|n|u] [-d dir] [-D define]
[-i patchfile] [-o outfile] [-p number]
[-r rejectfile] orig patchfile
[+ [options] orig]
patch < patchfile
The patch(1) utility will take a patch file containing any of the three forms of difference listing produced by the diff(1) program and apply those differences to an original file (orig), producing a patched version. By default, the patched version replaces the original, with the original file backed up to the same name with the extension .orig, or as specified by the -b switch. You can also specify where you want the output to go with a -o switch. If patchfile is omitted, or is a hyphen (-), the patch will be read from standard input.
Upon startup, patch will try to determine the type of the diff listing, unless it is overruled by a -c, -e, or -n switch. Context diffs and normal diffs are applied by the patch(1) program itself; ed diffs are simply provided to the ed(1) editor through a pipe.
The patch(1) utility will try to skip any leading garbage, apply the diff, and then skip any trailing garbage. You could provide an article or message containing a diff listing to patch(1), and it should work. If the entire diff is indented by a consistent amount, this will be taken into account.
With context diffs, and to a lesser extent with normal diffs, patch(1) can detect line numbers mentioned in the patch that are incorrect. It will attempt to find the correct place to apply each hunk of the patch. In its first attempt, it 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(1) scans forwards and backwards for a set of lines matching the context given in the hunk.
First patch(1) looks for a place where all lines of the
context match. If no such place is found, it is a context diff, and
the maximum fuzz factor is set to 1 or more, another scan takes
place ignoring the first and last line of context. (For more
information about the "fuzz factor," see
The line numbers on the hunks in the reject file might be different from those in the patch file: they reflect the approximate location where patch determines that the failed hunks belong in the new file rather than in the old one.
As each hunk is completed, you will be told whether the hunk succeeded or failed, and on which line (in the new file) patch(1) determined that the hunk should go. If this is different from the line number specified in the diff, you will be told the offset. A single large offset can be an indication that a hunk was installed in the wrong place. You will also be told if a fuzz factor was used to make the match, in which case you should also be slightly suspicious.
If no original file is specified on the command line, patch(1) will use the leading garbage to try to determine the name of the file to edit. In the header of a context diff, the file name is found from lines beginning with *** or ---, with the shortest name of an existing file being the one selected. Only context diffs have lines like that, but if there is an Index: line in the leading garbage, patch(1) will try 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 garbage, you will be asked for the name of the file to patch.
(If the original file cannot be found, but a suitable SCCS or RCS file is handy, patch(1) will attempt to get or check out that file.)
Additionally, if the leading garbage contains a Prereq: line, patch(1) takes the first word from the prerequisites line (usually a version number) and checks the input file to see if that word can be found. If not, patch(1) asks for confirmation before proceeding.
For example, while in a net news reader, you should be able to use the following:
| patch -d /usr/src/local/blurfl
and patch a file in the blurfl directory directly from the article containing the patch.
If the patch file contains more than one patch, patch(1) will try to apply each of them as if they came from separate patch files. This assumes that the name of the file to patch must be determined for each diff listing, and that the garbage before each diff listing will be examined for things such as file names and revision level, as mentioned previously. You can give switches (and another original file name) for the second and subsequent patches by separating the corresponding argument lists with a plus sign (+). The argument list for a second or subsequent patch cannot specify a new patch file, however.
The patch(1) utility recognizes the following switches:
/u/howard/src/blurfl/blurfl.c
setting -p or -p 0 gives the entire path name
unmodified.
-p 1 gives:
u/howard/src/blurfl/blurfl.c
without the leading slash.
-p 4 gives:
blurfl/blurfl.c
Not specifying -p at all just gives you:
blurfl.c
Whatever you end up with is looked for, either in the current directory or the directory specified by the -d switch.
If the first hunk of a patch fails, patch(1) will reverse the hunk to see if it can be applied that way. If it can, you will be asked whether you want to have the -R switch set. If it cannot do so, the patch will continue to be applied normally. 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) because appends always succeed and also because a null context will match anywhere. It is fortunate that patches add or change lines rather than delete them; most reversed normal diffs will begin with a delete, which will fail, triggering the heuristic.
The patch(1) utility is affected by the following environment variable, if set:
There are several things you should know if you are going to send out patches.
You can prevent many problems for your recipients by keeping 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, it will not let recipients of your patches apply them out of order without a warning. Second, make sure you have specified 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 switch as needed.
You can create a file by sending out a diff that compares a null file to the file you want to create. This will only work if the file you want to create does not already exist in the target directory. Patches against /dev/null will work if POSIXLY_CORRECT is 0.
Take care not to send out reversed patches, since doing so can make recipients wonder whether they have already applied the patch.
Although you might be able to put 582 diff listings successfully into one file, it is probably better to group related patches into separate files in case something goes wrong.
Too many to list here, but generally indicate that patch(1) could not parse your patch file.
The message Hmm... indicates that there is unprocessed text in the patch file and that patch(1) is attempting to determine whether there is a patch in that text, and if so, what kind of patch it is.
The patch(1) utility cannot tell whether the line numbers are inaccurate in an ed script, and can only detect bad line numbers in a normal diff when it finds a change or a delete command. A context diff using fuzz factor 3 might have the same problem. Until a suitable interactive interface is added, do a context diff in these cases to determine whether the changes made sense. Compiling without errors is a often good indication that the patch worked, but not always.
The patch(1) utility usually produces the correct results, even when it has difficulty parsing the input data. However, the results 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.
The patch(1) utility could be smarter about partial matches, excessively deviant offsets and swapped code, but that would take an extra pass.
If code has been duplicated (for instance with #ifdef OLDCODE ... #else ... #endif), patch(1) is incapable of patching both versions. In this case, if patch works, it will likely patch the wrong one, and tell you that it succeeded.
If you apply a patch you have already applied, patch(1) will think it is a reversed patch, and offer to un-apply the patch. This could be construed as a feature.
diff(1)
ed(1)