*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> patch (1)              


PATCH(1)							      PATCH(1)

NAME    [Toc]    [Back]

     patch - apply a diff file to an original

SYNOPSIS    [Toc]    [Back]

     patch [options] [origfile [patchfile]] [+ [options] [origfile]]...

     but usually just

     patch <patchfile

DESCRIPTION    [Toc]    [Back]

     Patch will	take a patch file containing any of the	four forms of
     difference	listing	produced by the	diff program and apply those
     differences to an original	file, producing	a patched version.  By
     default, the patched version is put in place of the original, with	the
     original file backed up to	the same name with the extension ".orig" ("~"
     on	systems	that do	not support long file names), or as specified by the
     -b, -B (--prefix),	or -V (--version-control) options.  The	extension used
     for making	backup files may also be specified in the SIMPLE_BACKUP_SUFFIX
     environment variable, which is overridden by the above options.

     If	the backup file	already	exists,	patch creates a	new backup file	name
     by	changing the first lowercase letter in the last	component of the
     file's name into uppercase.  If there are no more lowercase letters in
     the name, it removes the first character from the name.  It repeats this
     process until it comes up with a backup file that does not	already	exist.

     You may also specify where	you want the output to go with a -o (--output)
     option; if	that file already exists, it is	backed up first.

     If	patchfile is omitted, or is a hyphen, the patch	will be	read from
     standard input.

     Upon startup, patch will attempt to determine the type of the diff
     listing, unless over-ruled	by a -c	(--context), -e	(--ed),	-n (--normal),
     or	-u (--unified) option.	Context	diffs (old-style, new-style, and
     unified) and normal diffs are applied by the patch	program	itself,	while
     ed	diffs are simply fed to	the ed editor via a pipe.

     Patch will	try to skip any	leading	garbage, apply the diff, and then skip
     any trailing garbage.  Thus you could feed	an article or message
     containing	a diff listing to patch, and it	should work.  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 are incorrect,	and
     will attempt to find the correct place to apply each hunk of the patch.
     As	a first	guess, it 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 place,	patch will scan	both 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,

									Page 1

PATCH(1)							      PATCH(1)

     and it's 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
     context.  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 cannot	find a
     place to install that hunk	of the patch, it will put the hunk out to a
     reject file, which	normally is the	name of	the output file	plus ".rej"
     ("#" on systems that do not support long file names).  (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 in the patch file: they reflect
     the approximate location patch thinks the failed hunks belong in the new
     file rather than the old one.

     As	each hunk is completed,	you will be told whether the hunk succeeded or
     failed, and which line (in	the new	file) patch thought the	hunk should go
     on.  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
     slightly suspicious.

     If	no original file is specified on the command line, patch will try to
     figure out	from the leading garbage what the name of the file to edit is.
     In	the header of a	context	diff, the file name is found from lines
     beginning with "***" or "---", with the shortest name of an existing file
     winning.  Only context diffs have lines like that,	but if there is	an
     "Index:"  line in the leading garbage, patch will try to use the file
     name from that line.  The context diff header takes precedence over an
     Index line.  If no	file name can be intuited from the leading garbage,
     you will be asked for the name of the file	to patch.

     If	the original file cannot be found or is	read-only, but a suitable SCCS
     or	RCS file is handy, patch will attempt to get or	check out the file.

     Additionally, if the leading garbage contains a "Prereq: "	line, patch
     will take the first word from the prerequisites line (normally a version
     number) and check the input file to see if	that word can be found.	 If
     not, patch	will ask for confirmation before proceeding.

     The upshot	of all this is that you	should be able to say, while in	a news
     interface,	the following:

	  | patch -d /usr/src/local/blurfl

     and patch a file in the blurfl directory directly from the	article
     containing	the patch.

     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.  This means,
     among other things, that it is assumed that the name of the file to patch

									Page 2

PATCH(1)							      PATCH(1)

     must be determined	for each diff listing, and that	the garbage before
     each diff listing will be examined	for interesting	things such as file
     names and revision	level, as mentioned previously.	 You can give options
     (and another original file	name) for the second and subsequent patches by
     separating	the corresponding argument lists by a '+'.  (The argument list
     for a second or subsequent	patch may not specify a	new patch file,

     Patch recognizes the following options:

     -b	  explicitly specify ".orig" as	the backup file	extension.

     -B	pref, --prefix=pref
	  causes pref to be interpreted	as a prefix to the backup file name.
	  If this argument is specified, any argument from -b will be ignored.

     -c, --context
	  forces patch to interpret the	patch file as a	context	diff.

     -d	dir, --directory=dir
	  causes patch to interpret dir	as a directory,	and cd to it before
	  doing	anything else.

     -D	sym, --ifdef=sym
	  causes patch to use the "#ifdef...#endif" construct to mark changes.
	  sym will be used as the differentiating symbol.

     -e, --ed
	  forces patch to interpret the	patch file as an ed script.

     -E, --remove-empty-files
	  causes patch to remove output	files that are empty after the patches
	  have been applied.

     -f, --force
	  forces patch to assume that the user knows exactly what he or	she is
	  doing, and to	not ask	any questions.	It assumes the following: skip
	  patches for which a file to patch can't be found; patch files	even
	  though they have the wrong version for the ``Prereq:'' line in the
	  patch; and assume that patches are not reversed even if they look
	  like they are.  This option does not suppress	commentary; use	-s for

     -t, --batch
	  similar to -f, in that it suppresses questions, but makes some
	  different assumptions:  skip patches for which a file	to patch can't
	  be found (the	same as	-f); skip patches for which the	file has the
	  wrong	version	for the	``Prereq:'' line in the	patch; and assume that
	  patches are reversed if they look like they are.

									Page 3

PATCH(1)							      PATCH(1)

     -F	number,	--fuzz=number
	  sets the maximum fuzz	factor.	 This option only applies to context
	  diffs, and causes patch to ignore up to that many lines in looking
	  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 of context in
	  the context diff, ordinarily 3.

     -l, --ignore-whitespace
	  causes the pattern matching to be done loosely, in case the tabs and
	  spaces have been munged in your input	file.  Any sequence of
	  whitespace in	the pattern line will match any	sequence in the	input
	  file.	 Normal	characters must	still match exactly.  Each line	of the
	  context must still match a line in the input file.

     -n, --normal
	  forces patch to interpret the	patch file as a	normal diff.

     -N, --forward
	  causes patch to ignore patches that it thinks	are reversed or
	  already applied.  See	also -R	.

     -o	file, --output=file
	  causes file to be interpreted	as the output file name.

     -p	number,	--strip[=number]
	  sets the pathname strip count, which controls	how pathnames found in
	  the patch file are treated, in case the you keep your	files in a
	  different directory than the person who sent out the patch.  The
	  strip	count specifies	how many slashes are to	be stripped from the
	  front	of the pathname.  (Any intervening directory names also	go
	  away.)  For example, supposing the file name in the patch file was


	  setting -p0 gives the	entire pathname	unmodified, -p1	gives


	  without the leading slash, -p4 gives


	  and not specifying -p	at all just gives you "blurfl.c", unless all
	  of the directories in	the leading path (u/howard/src/blurfl) exist
	  and that path	is relative, in	which case you get the entire pathname
	  unmodified.  Whatever	you end	up with	is looked for either in	the
	  current directory, or	the directory specified	by the -d option.

     -r	file, --reject-file=file
	  causes file to be interpreted	as the reject file name.

									Page 4

PATCH(1)							      PATCH(1)

     -R, --reverse
	  tells	patch that this	patch was created with the old and new files
	  swapped.  (Yes, I'm afraid that does happen occasionally, human
	  nature being what it is.)  Patch will	attempt	to swap	each hunk
	  around before	applying it.  Rejects will come	out in the swapped
	  format.  The -R option will not work with ed diff scripts because
	  there	is too little information to reconstruct the reverse

	  If the first hunk of a patch fails, patch will reverse the hunk to
	  see if it can	be applied that	way.  If it can, you will be asked if
	  you want to have the -R option set.  If it can't, the	patch will
	  continue to be applied normally.  (Note: this	method cannot detect a
	  reversed patch if it is a normal diff	and if the first command is an
	  append (i.e. it should have been a delete) since appends always
	  succeed, due to the fact that	a null context will match anywhere.
	  Luckily, most	patches	add or change lines rather than	delete them,
	  so most reversed normal diffs	will begin with	a delete, which	will
	  fail,	triggering the heuristic.)

     -s, --silent, --quiet
	  makes	patch do its work silently, unless an error occurs.

     -S, --skip
	  causes patch to ignore this patch from the patch file, but continue
	  on looking for the next patch	in the file.  Thus

	       patch -S	+ -S + <patchfile

	  will ignore the first	and second of three patches.

     -u, --unified
	  forces patch to interpret the	patch file as a	unified	context	diff
	  (a unidiff).

     -v, --version
	  causes patch to print	out its	revision header	and patch level.

     -V	method,	--version--control=method
	  causes method	to be interpreted as a method for creating backup file
	  names.  The type of backups made can also be given in	the
	  VERSION_CONTROL environment variable,	which is overridden by this
	  option.  The -B option overrides this	option,	causing	the prefix to
	  always be used for making backup file	names.	The value of the
	  VERSION_CONTROL environment variable and the argument	to the -V
	  option are like the GNU Emacs	`version-control' variable; they also
	  recognize synonyms that are more descriptive.	 The valid values are
	  (unique abbreviations	are accepted):

	  `t' or `numbered'
	       Always make numbered backups.

									Page 5

PATCH(1)							      PATCH(1)

	  `nil'	or `existing'
	       Make numbered backups of	files that already have	them, simple
	       backups of the others.  This is the default.

	  `never' or `simple'
	       Always make simple backups.

     -x	number,	--debug=number
	  sets internal	debugging flags, and is	of interest only to patch

AUTHOR    [Toc]    [Back]

     Larry Wall	<lwall@netlabs.com>
     with many other contributors.

ENVIRONMENT    [Toc]    [Back]

	  Directory to put temporary files in; default is /tmp.

     SIMPLE_BACKUP_SUFFIX    [Toc]    [Back]
	  Extension to use for backup file names instead of ".orig" or "~".

     VERSION_CONTROL    [Toc]    [Back]
	  Selects when numbered	backup files are made.

FILES    [Toc]    [Back]


SEE ALSO    [Toc]    [Back]


     There are several things you should bear in mind if you are going to be
     sending out patches.  First, 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.  Second, make sure you've specified the file	names
     right, either in a	context	diff 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 option as needed.	Third, you can create a	file by
     sending out a diff	that compares a	null file to the file you want to
     create.  This will	only work if the file you want to create doesn't exist
     already in	the target directory.  Fourth, take care not to	send out
     reversed patches, since it	makes people wonder whether they already
     applied the patch.	 Fifth,	while you may be able to get away with putting
     582 diff listings into one	file, it is probably wiser to group related
     patches into separate files in case something goes	haywire.

									Page 6

PATCH(1)							      PATCH(1)

     Too many to list here, but	generally indicative that patch	couldn't parse
     your patch	file.

     The message "Hmm..." indicates 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 will	exit with 1 if any reject files	were created.  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.  Patch exits with
     a status bigger than 1 means that an error	occurred.

CAVEATS    [Toc]    [Back]

     Patch cannot tell if the line numbers are off in an ed script, and	can
     only detect bad line numbers in a normal diff when	it finds a "change" or
     a "delete"	command.  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 exactly the same version of the file that the
     patch was generated from.

BUGS    [Toc]    [Back]

     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 OLDCODE ... #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	will think it is a
     reversed patch, and offer to un-apply the patch.  This could be construed
     as	a feature.

									PPPPaaaaggggeeee 7777
[ Back ]
 Similar pages
Name OS Title
patch HP-UX a program for applying a diff file to an original
flock Linux apply or remove an advisory lock on an open file
flock NetBSD apply or remove an advisory lock on an open file
flock IRIX apply or remove an advisory lock on an open file
flock Tru64 Apply or remove an advisory lock on an open file
flock OpenBSD apply or remove an advisory lock on an open file
flock FreeBSD apply or remove an advisory lock on an open file
lockf Linux apply, test or remove a POSIX lock on an open file
DIFFsource IRIX archive of DIFF sources
bdiff HP-UX diff for large files
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service