patch(1)

Synopsis

Description

When the patch utility is run without specifying the -c, -e, or -n option, patch tries to determine the type of diff list.

When a patch file contains more than one patch, each patch is applied as if it came from a separate patch file. In this case, the name of the patch file is determined from the diff listing.

Patches that cannot be correctly placed in the file are written to a reject file. The name of this file is formed by appending the suffix .rej to the original filename, unless the -r option is present with a name for the reject file. Then, the specified name overrides the default name.

file is the pathname of the patch file.

The following options are supported:

-b

Save a copy of the original file, 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. When the -o outfile option also is specified, file.orig is not created but, if outfile already exists, outfile.orig is created.

-c

Interpret the patch file as a context difference, that is, it was created by the utility diff when the -c or -C option was specified.

-d dir

Change the current directory to dir before processing.

-D define

Mark changes with the C preprocessor construct:

#ifdef define
. . .
#endif

The option-argument define is used as the differentiating symbol.

-F num

Set the maximum ``fuzz'' factor. This option only applies to diffs that have context, and causes patch to ignore up to num lines when looking for places to install a hunk. Note that a larger fuzz factor increases the odds of a faulty patch. num defaults to 2, and should not be set to more than the number of lines of context in the context diff (ordinarily 3).

-e

Interpret the path file as an ed(1) script, rather than output from diff.

-i patchfile

Read the patch information from the file named by the pathname patchfile, rather than the standard input.

-l

Cause any sequence of blank characters in the difference script to match any sequence of blank characters in the input file. Other characters are matched exactly.

-n

Interpret the script as a normal difference.

-N

Ignore patches where the differences have already been applied to the file; by default, already-applied patches are rejected.

-o outfile

Instead of modifying the input file 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 results in multiple, concatenated versions of the file being written to outfile.

-p num

For all pathnames in the patch file that show the names of files to be patched, delete num pathname components from the beginning of each pathname. If the pathname in the patch file is absolute, any leading slashes are considered the first component (that is, -p 1 removes the leading slashes). Specifying -p 1 causes the full pathname to be used. If -p is not specified, only the basename (the final pathname component) is used.

-R

Reverse the sense of the patch script; that is, assume that the difference script was created from the new version to the old version. The -R option cannot be used with ed scripts. The patch utility attempts to reverse each portion of the script before applying it. Rejected differences are saved in swapped format. If this option is not specified, and until a portion of the patch file is successfully applied, patch attempts to apply each portion in its reversed sense as well as in its normal sense. If the attempt is successful, the user is prompted to determine if the -R option should be set.

-r rejectfile

Use rejectfile to override the default reject filename. The default reject filename is the name of the output file, with the suffix .rej appended to it.

The following environment variables affect the execution of patch:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-specific default locale is used. If any of the internationalization variables contains 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, override the values of all the other internationalization variables.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files).

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output.

LC_TIME

Determine the locale for recognizing the format of file timestamps written by the diff utility in a context-difference input file.

Patchfile format

The patch utility recognizes the following expression in the header information:

   Index: pathname       The file to be patched is named pathname

   *** filename timestamp      The patches arose from filename.
   

   --- filename timestamp      The patches should be applied to filename.

Filename determination

If the patch contains the strings ``***'' and ``---'' patch utility strips components from the beginning of each pathname and then tests for the existence of both files in the current directory or the directory specified with the -d option. If both files exist, patch assumes that no pathname can be obtained from this step.

If the header information contains a line with the string ``Index:'', patch strips components from the beginning of the pathname and then tests for the existence of this file in the current directory or the directory specified with the -d option.

If no pathname can be obtained by applying the previous steps, or if the pathnames obtained do not exist, patch writes a prompt to standard output and requests a filename interactively from standard input.

Patch application

For each hunk, the patch utility begins to search for the place to apply the patch at the line number at the beginning of the hunk, plus or minus an offset used in applying the previous hunk. If line matching the hunk context are not found, patch scans both forwards and backwards at least 1000 bytes for a set of lines that match the hunk context.

If no such place is found and it is a context difference, then another scan takes place, ignoring the first and last line of context. If that fails, the first two and last two lines of context are ignored and another scan is made. Implementations can search more extensively for installation locations.

If no location is found, the patch utility appends the hunk to the reject file. The rejected hunk is written in contest-difference format regardless of the format of the patch file. If the input was a normal or ed-style difference, the reject file can contain differences with zero line of context. The line numbers on the hunks in the reject file can be different from the line numbers in the patch file since they reflect the approximate locations for the failed hunks in the new file rather than the old one.

If the type of patch is an ed diff, the implementation can accomplish the patching by invoking the ed utility.

References

Notices

The -p option makes it possible to customize a patchfile to local user directory structures without manually editing the patchfile. For example, if the filename in the patch file was:

curds/whey/src/blurf1/blurf1.c

Setting -p 0 gives the entire pathname unmodified; -p 1 gives:

/curds/whey/src/blurf1/blurf1.c

without the leading slash, -p 4 gives:

blurf1/blurf1.c

and not specifying -p at all gives:

blurf1.c

When using -b in some file system implementations, the saving of a .orig file can produce unwanted results. In the case of 12, 13, or 14-character filenames, on file systems supporting 14-character maximum filenames, the .orig file overwrites the new file.