patch(1) patch(1)
NAME
patch - use diff list
SYNOPSIS
patch [option ...] [file] [+ [option ...] [file]]
DESCRIPTION
patch will take a patch file containing any of the three forms of
difference listing (normal, with context or in the ed format), pro-
duced by the diff(1) program and apply those differences to an origi-
nal file, producing a patched version. By default, the patched version
is put in the place of the original. If you specify the -b option, the
original file is stored under the same name with the extension .orig.
You may also specify where you want the output to go with an -o
option.
Upon startup, patch will attempt to determine the type of the diff
listing, unless overruled by a -c, -e or -n option. Context diffs and
normal diffs are applied by the patch program itself, while -e diffs
are simply fed to the ed(1) editor via a pipe.
patch will try to skip any leading extraneous material, apply the
diff, and then skip any trailing extraneous material. 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
can detect when the line numbers mentioned in the patch instructions
are incorrect, and will attempt to find the correct place to apply
each hunk of the patch. As a first guess, patch 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 position, patch will scan a
maximum of 1,000 bytes forwards and backwards for a set of lines
matching the context given in the hunk. First patch looks for a place
where all lines of the context match. If no such place is found, and
it is a context diff, and the maximum fuzz factor is set to 1 or more,
then another scan takes place ignoring the first and last line of con-
text. If that fails, and the maximum fuzz factor is set to 2 or more,
the first two and last two lines of context are ignored, and another
scan is made. (The default maximum fuzz factor is 2.)
If patch still cannot find a place to install that hunk of the patch,
it will write the hunk to a reject file, which normally is the name of
the output file plus .rej. Note that the rejected hunk will come out
in context diff form whether the input patch was a context diff or a
normal diff. If the input was a normal diff, many of the contexts will
simply be null.) The line numbers on the hunks in the reject file may
be different than those in the patch file: they reflect the approxi-
mate location patch thinks the failed hunks belong in the new file
rather than the old one.
Page 1 Reliant UNIX 5.44 Printed 11/98
patch(1) patch(1)
As each hunk is completed, you will be told whether the hunk succeeded
or failed, and in which line (in the new file) patch thought 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 may 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 careful.
If patch is called with an ed list, this list is forwarded to the
ed(1) editor. Incorrect ed instructions cannot be diagnosed with the
result that no .rej error file is created and the status 1 is not
returned (see EXIT STATUS).
If no original file is specified, patch will try to figure out from
the leading extraneous material what the name of the file to edit is.
In the header of a context diff, the filename is found from lines
beginning with "***" or "---". If patch cannot determine the filename
in this way, it searches for an "Index:" line and attempts to use the
filename contained in this line. Filenames found are then truncated in
accordance with the -p option. patch searches the file(s) in the
current directory (or the directory specified with the -d option). If
the original file cannot be found, and a matching SCCS or RCS file is
available, patch tries to retrieve and edit this file. If no filename
can be determined from the leading extraneous material, you will be
asked for the name of the file to patch.
If the leading extraneous material contains a "Prereq:" line, patch
will take the first word from the prerequisites line (normally a ver-
sion number) and check the input file to see if that word can be
found. If not, patch will ask for confirmation before proceeding.
If the patch file contains more than one patch, patch will try to
apply each of them as if they came from separate patch files. For
every patch, patch tries to determine the name of the file to be
corrected and scans the leading and trailing extraneous material for
relevant specifications (like for example, filenames and revision
level). You can specify options (and another original filename) for
the second or subsequent patches by separating the corresponding argu-
ment lists with a "+".
OPTIONS
The options -c, -e and -n cannot be combined.
-b Saves all original files with a .orig suffix before the patch is
applied. The backup file is overwritten if it already exists; if
patch is executed several times, a backup file is only created on
the first execution. The additional option -o does not save the
original file, but saves the output file if it already exists.
-B backup
Saves the original file in backup.orig before the patch instruc-
tions are executed.
Page 2 Reliant UNIX 5.44 Printed 11/98
patch(1) patch(1)
-c Interprets the patch file as a context diff (output from diff, if
-c or -C is specified).
-d directory
patch changes to the directory directory before further actions
take place.
-D define
Marks changes with the C preprocessor construct:
#ifdef define
...
#endif
The argument define will be used as the differentiating symbol.
Note that, unlike with the C compiler, there must be a space
between the -D option and the argument.
-e Interprets the patch file as an ed script.
-f patch assumes that the user knows exactly what he or she is
doing, and asks no questions. It does not suppress commentary,
however. Use -s for that.
-F lines
Sets the maximum fuzz factor. This option only applies to context
diffs, and causes patch to ignore up to that many lines in look-
ing for places to install a hunk. Note that a larger fuzz factor
increases the odds of a faulty patch. The default fuzz factor is
2, and it may not be set to more than the number of lines os con-
text in the context diff, ordinarily 3.
-i patchfile
patch reads the patch from the patchfile file. If you enter a
dash for patchfile patch reads from the standard input.
A patch file contains one or more patches and maybe some addi-
tional information. If a patch file contains several patches,
each patch should contain information about filenames (like with
diff -c) so that patch can find affected files automatically.
patch evaluates the following information:
Index: pathname
pathname names the file to be corrected
*** pathname
pathname specifies the "old" file on which the patch is
based
Page 3 Reliant UNIX 5.44 Printed 11/98
patch(1) patch(1)
--- pathname
pathname specifies the file to be corrected (has priority
over Index:)
Each patch contains patch instructions, which correspond to one
of the three kinds of diff.
-i not specified: patch reads from the standard input.
-l Any sequence of tabs and blanks in the patch file will match any
sequence of tabs and blanks in the input file. However, normal
characters must still match exactly.
-n Interprets the patch file as a normal diff.
-N Ignores patches that have already been applied. Such patch
instructions are rejected by default.
-o output-file
The corrected version is written to output-file. Several
corrected files are appended one after the other. If different
patches affect the same original file, the following scripts are
applied to a temporary file. Several versions of the original
file are then written to output-file accordingly.
-p number
Controls the handling of pathnames found in the patch file.
number specifies how many slashes are to be stripped from the
front of the pathname. (Any intervening directory names are also
removed.) For relative pathnames, the search takes place in the
current directory or in the directory specified by the -d option.
-p not specified: Only the basic name, without path, is used.
For example, supposing the filename in the patch file was
/u/howard/src/blurfl/blurfl.c
Setting the -p 0 gives the entire pathname unmodified, while -p 1
gives
u/howard/src/blurfl/blurfl.c
without the leading slash, -p 4 gives
blurfl/blurfl.c
and not specifying -p at all just gives you blurfl.c.
Page 4 Reliant UNIX 5.44 Printed 11/98
patch(1) patch(1)
-r rejectfile
Specifies the file to which the rejected patchs should be sent.
-r not specified:
The rejected files are sent to one file, which has the same name
as the output file, but with the suffix .rej.
-R patch swaps the patch instructions before they are applied to the
original file. This is necessary if the old and new files were
exchanged when creating the patch. patch attempts to swap each
hunk before it is applied. Rejects are written to the error file
in swapped format. The -R option cannot be used for ed scripts,
as the information is insufficient for reconstructing the swapped
operation.
If the first hunk of a patch fails, patch swaps the patch
instructions to see if they can be applied in this way. If this
is possible, you are asked whether the -R option should be set.
If this is not possible, patch enters the hunk in the error file
and continues as normal. (Note: reversed patch instructions can-
not be detected with this method in the case of a normal diff and
where the first command is an append, i.e. it should in fact have
been a delete.)
-s patch does not output any messages if no errors occur.
-S If the patch file contains several patches, a script can be
skipped using -S. The next script is then applied to the original
file.
patch -S + -S + file
ignores, e.g. the first two of approximately three patches.
-v Outputs information on the version of the active patch program.
-x flag
Sets internal debugging flags. This option can be used for test-
ing the patch file.
file Pathname of the file to be patched.
file not specified:
patch attempts to determine the filename from the leading
extraneous material.
Page 5 Reliant UNIX 5.44 Printed 11/98
patch(1) patch(1)
NOTES FOR PATCH SENDERS
If you create patch files on a regular basis, it is recommended that
the revision level be included as the first patch instruction. If you
add the line "Prereq: " to the patch file, you can prevent users
applying incorrect patches without being warned.
Check whether the filenames have been specified correctly in the con-
text diff header or in the "Index:" line. If you wish to make correc-
tions in a subdirectory, inform the patch user that the -p option must
be set.
Avoid reversed patches where possible.
Place patches that need to be together in the event of an error in
separate files where possible.
If patch files are created with rejected hunks, patch terminates with
a non-zero exit status. If you want to apply a set of patches in a
loop, you should check this exit status so that a subsequent patch
will not be performed on a partly corrected file.
If code was duplicated (e.g. using "#ifdef OLDCODE ... #else ...
#endif"), patch cannot correct both versions. If the command can be
executed at all, it may correct the wrong version and inform you that
the corrections have been made successfully.
If you use an already applied patch again, patch assumes that the
patch in question is a reversed patch and offers to un-apply the
patch.
ENVIRONMENT VARIABLES
The following environment variables have an effect on the execution of
patch:
LANG Specifies a default value for the locale variables that
are unset or null. If LANG is unset or null, the corre-
sponding locale default value is used. If the locale
variable contains an invalid setting, patch behaves as if
no variables had been set.
LCALL If this value is set, i.e. is not empty, this value
overwrites the values of all other locale variables.
LCCTYPE Determines the locale for the interpretation of byte
sequences as characters (e.g. single-byte as opposed to
multibyte characters in arguments).
LCMESSAGES Determines the format and content of error messages.
NLSPATH Determines the position of the message catalog for the
processing of LCMESSAGES.
Page 6 Reliant UNIX 5.44 Printed 11/98
patch(1) patch(1)
EXIT STATUS
0 Successful completion.
1 One or more rejected patch instructions were written to the error
file.
>1 An error occurred.
FILES
/tmp/patch*
SEE ALSO
diff(1), ed(1).
Page 7 Reliant UNIX 5.44 Printed 11/98