patch -- change file using diff output

SYNOPSIS

patch [-bceflNnRsv] [-B prefix] [-D symbol] [-d dir] [-F n] [-i patchfile] [-o outfile] [-p n] [-r rejectfile] [file]

patch reads a patchfile which contains output from diff describing changes from an old text file to a new text file. patch then applies those changes to another text file. Typically, you use patch if you are keeping parallel versions of a file. When you make changes to one file, you can use patch to incorporate those changes into other versions of the file.

On Window systems, when this reference page indicates adding a suffix to a file name, patch replaces any suffix with the indicated suffix. Thus, if the original file was hello.c, rather than producing a file hello.c.orig, a file hello.orig would be produced.

If you do not specify either the -b or -B options, patch tries to change the original file directly. If you do not specify -c, -e, or -n, patch looks at the format of the diff output and tries to determine which type of output the patchfile contains.

If you do not specify a file to be patched and the patchfile is not in context format, patch prompts you for the name of the file you want to patch.

If the patchfile is in context format, patch tries to determine the file name on its own. The first two lines of a context patchfile give the names of the old and new files that diff compared. If only one of the files exists, patch patches that file. if neither exists or both do, patch checks for a line starting with the string Index: and if one exists, obtains the name of the file to patch from the contents of that line. Once patch has determined the file to patch, it checks for an SCCS subdirectory in the current directory and if one exists, it attempts to obtain an editable version of that file by performing the SCCS command get -e. If patch cannot determine the file to patch, it prompts you for the name of the file to use.

With a context format patchfile, patch can recognize when line numbers given in the patchfile do not match line numbers in the file being patched. Thus it can patch a file with line counts that do not match the old file that was used by diff. To do this, it takes these steps:

For each section to be changed, patch starts with the line number found in the patchfile, plus or minus any adjustment that must be made for the previous section.

If the line at this location does not match the line in the patchfile, patch scans forward and backward for a line that does match. If it finds a matching line, patch makes the appropriate changes. patch also remembers the adjustment it had to make to find the matching line, and uses this adjustment in the next section to be changed.

If patch cannot find a line matching the one in the patchfile, it tries to find the line using the lines given as context. It ignores the first and last lines of the context and searches again. If it finds a match this time, it makes the change and remembers the adjustment.

If a search ignoring the first and last lines of the context fails, patch searches one more time, ignoring the first two and last two lines of the context. If it finds a match, it makes the changes and remembers the adjustment.

If patch still cannot find a match, it writes the unmatching portion to the reject file. It then tries to process the next section of changes. Thus the reject file contains the sections that patch is not able to change. Line numbers on sections in the reject file may be different than those in the patchfile, since patch adjusts them using the adjustment that patch calculated for preceding sections.

To some extent, patch tries the same process if the patchfile is in normal rather than context format. Because the patchfile does not contain the context information, patch has less to work with and probably creates more rejects. patch always writes the rejectfile in context format, regardless of the format of the patchfile.

By default, the rejectfile has the same name as the original file, plus the suffix .rej. You can use -r to specify a different rejectfile on the command line. If the rejectfile already exists, patch overwrites it.

If you do not specify -R, patch starts out with the assumption that the patchfile could be normal or reversed. Therefore if the first change is rejected, patch tries the reverse change to see if that one works. If the reverse change is also rejected, patch continues on with other changes in the file, trying both forward and reverses changes until one of them works. If the one that works is a forward change, patch only attempts forward changes for the rest of the file. If the one that works is a reverse change, patch issues a message to this effect and asks if it should treat all changes as reverse ones.

The patchfile can contain output from several diff comparisons. patch treats each collection of changes as a separate patchfile, and with each, patch may prompt you for the name of the file to be patched.

Options

-B prefix

saves a copy of the original file in a back-up file. The back-up file name is the name of the original file preceded by the string prefix. If there is already a file with this name, patch overwrites it. When applying more than one patch to the same file, patch only copies the original for the first patch. When you also specify -o outfile, patch does not create prefixfile, but if outfile already exists, it creates prefixoutfile.

-b

saves a copy of the original file in a back-up file. The back-up file name is the name of the original file plus the suffix .orig. If there is already a file with this name, patch overwrites it. When applying more than one patch to the same file, patch only creates file.orig for the first patch. When you also specify -o outfile, patch does not create file.orig, but if outfile already exists, it creates outfile.orig.

-c

interprets the patchfile as a context diff file (the output of diff when -c or -C is specified). You cannot use this option with -e or -n.

-D symbol

marks changes with the C preprocessor construct

#ifdef symbol
      ...
#endif

When you compile the resulting (patched) file, you get the original file if symbol is not defined, and the changed file if symbol is defined.

-d dir

changes the current directory to dir before processing the patch.

-e

interprets the patchfile as an ed script (the output of diff when -e is specified). You cannot use this option with -c or -n.

-F n

specifies the number of lines of a context diff to ignore when searching for a place to install a patch.

-f

forces processing without requesting additional information from the user.

-i patchfile

reads information from patchfile. If you do not specify patchfile, patch reads the information from the standard input.

-l

matches any sequences of blanks in the patchfile to any sequence of blanks in the input file. In other words, patch considers two lines equivalent if the only difference between them is their spacing.

-N

ignores any patches which have already been applied. By default, patch rejects already-applied patches.

-n

interprets the patchfile as normal diff output. You cannot use this option with -c or -e.

-o outfile

writes patched output to outfile instead of the original file. When you specify more than one patch to a single file, patch applies the patches to intermediate versions of the file created by previous patches, resulting in multiple, concatenated versions of the file being written to outfile.

-p n

deletes n components from the beginning of all path names in the patchfile. If a path name is an absolute path name (that is, starts with a slash), patch treats the leading slash as the first component of the path, and patch -p 1 deletes the leading slash. Specifying -p 0 tells patch to use the full path names given in the patchfile. If you do not specify this option, patch only uses the base name (the final path name component).

-R

reverses the sense of the patch script. In other words, patch behaves as if the patch script shows the changes that make the new version into the old version. You cannot use -R if the patchfile is in ed script format.

With -R, patch attempts to reverse each change recorded in the script before applying the change. patch saves rejected differences in reversed format (which means that you can check the rejections to see if patch made the reversals correctly).

-r rejectfile

records rejects in the file rejectfile instead of the default rejectfile name. By default, the rejectfile has the same name as the original file, plus the suffix .rej.

-s

tells patch to remain silent until an error occurs. Normally, patch writes information on the results of the patching process to standard error (stderr).

-v

displays the version number of patch, then exits.

DIAGNOSTICS

patch may return the following status values:

0: Successful completion.
1: There were one or more rejects.
>1: An error occurred.

PORTABILITY

POSIX.2. x/OPEN Portability Guide 4.0. All UNIX systems. Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.

The -B, -F, -f, -s and -v options are not part of the POSIX standard.

ACKNOWLEDGEMENT

patch was written by Larry Wall.

AVAILABILITY

PTC MKS Toolkit for Power Users
PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

patch
change file using diff output

Command