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:

1. 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.
2. If there is an Index: line in the leading text, the patch command tries to use the file name from that line.
3. A context diff header takes precedence over an Index: line.
4. If no file name can be determined from the leading text, the patch command prompts you for the name of the file to patch.
5. 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.
6. 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

#ifdef Define
...  (NEWCODE)
#else
...  (OLDCODE)
#endif /* Define */

Exit Status

The following exit values are returned:

Examples

1. To apply diff listings in the difflisting file to the prog.c file, enter:

   patch -i difflisting prog.c
   

2. 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.

3. 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

Related Information

The diff command, ed command.