User Commands PATCH(1)
NAME
patch - apply a diff file to an original
SYNOPSIS
patch [options] [originalfile [patchfile]
but usually just
patch -pnum (1985-01).
NOTES FOR PATCH SENDERS
There are several things you should bear in mind if you are
going to be sending out patches.
Create your patch systematically. A good method is the com-
mand diff -Naur old new where old and new identify the old
and new directories. The names old and new should not con-
tain any slashes. The diff command's headers should have
dates and times in Universal Time using traditional Unix
format, so that patch recipients can use the -Z or --set-utc
GNU Last change: 2002/05/25 10
User Commands PATCH(1)
option. Here is an example command, using Bourne shell syn-
tax:
LCAL=C TZ=UTC0 diff -Naur gcc-2.7 gcc-2.8
Tell your recipients how to apply the patch by telling them
which directory to cd to, and which patch options to use.
The option string -Np1 is recommended. Test your procedure
by pretending to be a recipient and applying your patch to a
copy of the original files.
You can save people a lot of grief by keeping a patchlevel.h
file which 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 won't let them apply
patches out of order without some warning.
You can create a file by sending out a diff that compares
/dev/null or an empty file dated the Epoch (1970-01-01
00:00:00 UTC) to the file you want to create. This only
works if the file you want to create doesn't exist already
in the target directory. Conversely, you can remove a file
by sending out a context diff that compares the file to be
deleted with an empty file dated the Epoch. The file will
be removed unless patch is conforming to POSIX and the -E or
--remove-empty-files option is not given. An easy way to
generate patches that create and remove files is to use GNU
diff's -N or --new-file option.
If the recipient is supposed to use the -pN option, do not
send output that looks like this:
diff -Naur v2.0.29/prog/README prog/README
--- v2.0.29/prog/README Mon Mar 10 15:13:12 1997
] prog/README Mon Mar 17 14:58:22 1997
because the two file names have different numbers of
slashes, and different versions of patch interpret the file
names differently. To avoid confusion, send output that
looks like this instead:
diff -Naur v2.0.29/prog/README v2.0.30/prog/README
--- v2.0.29/prog/README Mon Mar 10 15:13:12 1997
] v2.0.30/prog/README Mon Mar 17 14:58:22 1997
Avoid sending patches that compare backup file names like
README.orig, since this might confuse patch into patching a
backup file instead of the real file. Instead, send patches
that compare the same base file names in different direc-
tories, e.g. old/README and new/README.
GNU Last change: 2002/05/25 11
User Commands PATCH(1)
Take care not to send out reversed patches, since it makes
people wonder whether they already applied the patch.
Try not to have your patch modify derived files (e.g. the
file configure where there is a line configure: configure.in
in your makefile), since the recipient should be able to
regenerate the derived files anyway. If you must send diffs
of derived files, generate the diffs using UTC, have the
recipients apply the patch with the -Z or --set-utc option,
and have them remove any unpatched files that depend on
patched files (e.g. with make clean).
While you may be able to get away with putting 582 diff
listings into one file, it may be wiser to group related
patches into separate files in case something goes haywire.
DIAGNOSTICS
Diagnostics generally indicate that patch couldn't parse
your patch file.
If the --verbose option is given, the message Hmm... indi-
cates that there is unprocessed text in the patch file and
that patch is attempting to intuit whether there is a patch
in that text and, if so, what kind of patch it is.
patch's exit status is 0 if all hunks are applied success-
fully, 1 if some hunks cannot be applied, and 2 if there is
more serious trouble. When applying a set of patches in a
loop it behooves you to check this exit status so you don't
apply a later patch to a partially patched file.
CAVEATS
Context diffs cannot reliably represent the creation or
deletion of empty files, empty directories, or special files
such as symbolic links. Nor can they represent changes to
file metadata like ownership, permissions, or whether one
file is a hard link to another. If changes like these are
also required, separate instructions (e.g. a shell script)
to accomplish them should accompany the patch.
patch cannot tell if the line numbers are off in an ed
script, and can detect bad line numbers in a normal diff
only when it finds a change or deletion. A context diff
using fuzz factor 3 may have the same problem. Until a
suitable interactive interface is added, you should probably
do a context diff in these cases to see if the changes made
sense. Of course, compiling without errors is a pretty good
indication that the patch worked, but not always.
patch usually produces the correct results, even when it has
to do a lot of guessing. However, the results are
guaranteed to be correct only when the patch is applied to
GNU Last change: 2002/05/25 12
User Commands PATCH(1)
exactly the same version of the file that the patch was gen-
erated from.
COMPATIBILITY ISUES
The POSIX standard specifies behavior that differs from
patch's traditional behavior. You should be aware of these
differences if you must interoperate with patch versions 2.1
and earlier, which do not conform to POSIX.
]o In traditional patch, the -p option's operand was
optional, and a bare -p was equivalent to -p0. The -p
option now requires an operand, and -p 0 is now
equivalent to -p0. For maximum compatibility, use
options like -p0 and -p1.
Also, traditional patch simply counted slashes when
stripping path prefixes; patch now counts pathname com-
ponents. That is, a sequence of one or more adjacent
slashes now counts as a single slash. For maximum porta-
bility, avoid sending patches containing / in file
names.
]o In traditional patch, backups were enabled by default.
This behavior is now enabled with the -b or --backup
option.
Conversely, in POSIX patch, backups are never made, even
when there is a mismatch. In GNU patch, this behavior is
enabled with the --no-backup-if-mismatch option, or by
conforming to POSIX with the --posix option or by setting
the POSIXLYCORECT environment variable.
The -b suffix option of traditional patch is equivalent
to the -b -z suffix options of GNU patch.
]o Traditional patch used a complicated (and incompletely
documented) method to intuit the name of the file to be
patched from the patch header. This method did not con-
form to POSIX, and had a few gotchas. Now patch uses a
different, equally complicated (but better documented)
method that is optionally POSIX-conforming; we hope it
has fewer gotchas. The two methods are compatible if the
file names in the context diff header and the Index: line
are all identical after prefix-stripping. Your patch is
normally compatible if each header's file names all con-
tain the same number of slashes.
]o When traditional patch asked the user a question, it sent
the question to standard error and looked for an answer
from the first file in the following list that was a ter-
minal: standard error, standard output, /dev/tty, and
standard input. Now patch sends questions to standard
GNU Last change: 2002/05/25 13
User Commands PATCH(1)
output and gets answers from /dev/tty. Defaults for some
answers have been changed so that patch never goes into
an infinite loop when using default answers.
]o Traditional patch exited with a status value that counted
the number of bad hunks, or with status 1 if there was
real trouble. Now patch exits with status 1 if some
hunks failed, or with 2 if there was real trouble.
]o Limit yourself to the following options when sending
instructions meant to be executed by anyone running GNU
patch, traditional patch, or a patch that conforms to
POSIX. Spaces are significant in the following list, and
operands are required.
-c
-d dir
-D define
-e
-l
-n
-N
-o outfile
-pnum
-R
-r rejectfile
BUGS
Please report bugs via email to .
patch 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 OLD-
CODE ... #else ... #endif), patch is incapable of patching
both versions, and, if it works at all, will likely patch
the wrong one, and tell you that it succeeded to boot.
If you apply a patch you've already applied, patch thinks it
is a reversed patch, and offers to un-apply the patch. This
could be construed as a feature.
COPYING
Copyright (C) 1984, 1985, 1986, 1988 Larry Wall.
Copyright (C) 1989, 1990, 1991, 1992, 1993, 1994, 1995,
1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foun-
dation, Inc.
Permission is granted to make and distribute verbatim copies
of this manual provided the copyright notice and this per-
mission notice are preserved on all copies.
GNU Last change: 2002/05/25 14
User Commands PATCH(1)
Permission is granted to copy and distribute modified ver-
sions of this manual under the conditions for verbatim copy-
ing, provided that the entire resulting derived work is dis-
tributed under the terms of a permission notice identical to
this one.
Permission is granted to copy and distribute translations of
this manual into another language, under the above condi-
tions for modified versions, except that this permission
notice may be included in translations approved by the copy-
right holders instead of in the original English.
AUTHORS
Larry Wall wrote the original version of patch. Paul Eggert
removed patch's arbitrary limits; added support for binary
files, setting file times, and deleting files; and made it
conform better to POSIX. Other contributors include Wayne
Davison, who added unidiff support, and David MacKenzie, who
added configuration and backup support.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWgpch
Interface Stability Committed
NOTES
Source for GNU patch is available on http:/opensolaris.org.
GNU Last change: 2002/05/25 15
|
