Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PATCH(1)		FreeBSD	General	Commands Manual		      PATCH(1)

NAME
     patch -- apply a diff file	to an original

SYNOPSIS
     patch [-bCcEeflNnRstuv] [-B backup-prefix]	[-D symbol] [-d	directory]
	   [-F max-fuzz] [-i patchfile]	[-o out-file] [-p strip-count]
	   [-r rej-name] [-V t | nil | never] [-x number] [-z backup-ext]
	   [--posix] [origfile [patchfile]]
     patch <patchfile

DESCRIPTION
     patch will	take a patch file containing any of the	four forms of differ-
     ence listing produced by the diff(1) program and apply those differences
     to	an original file, producing a patched version.	If patchfile is	omit-
     ted, or is	a hyphen, the patch will be read from the standard input.

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

     If	the patchfile 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
     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 (see the section on Filename Determination
     below).

     The options are as	follows:

     -B	backup-prefix, --prefix	backup-prefix
	     Causes the	next argument to be interpreted	as a prefix to the
	     backup file name.	If this	argument is specified, any argument to
	     -z	will be	ignored.

     -b, --backup
	     Save a backup copy	of the file before it is modified.  By default
	     the original file is saved	with a backup extension	of ".orig"
	     unless the	file already has a numbered backup, in which case a
	     numbered backup is	made.  This is equivalent to specifying	"-V
	     existing".	 This option is	currently the default, unless --posix
	     is	specified.

     -C, --check
	     Checks that the patch would apply cleanly,	but does not modify
	     anything.

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

     -D	symbol,	--ifdef	symbol
	     Causes patch to use the "#ifdef...#endif" construct to mark
	     changes.  The argument following will be used as the differenti-
	     ating symbol.  Note that, unlike the C compiler, there must be a
	     space between the -D and the argument.

     -d	directory, --directory directory
	     Causes patch to interpret the next	argument as a directory, and
	     change the	working	directory to it	before doing anything else.

     -E, --remove-empty-files
	     Causes patch to remove output files that are empty	after the
	     patches have been applied.	 This option is	useful when applying
	     patches that create or remove files.

     -e, --ed
	     Forces patch to interpret the patch file as an ed(1) script.

     -F	max-fuzz, --fuzz max-fuzz
	     Sets the maximum fuzz factor.  This option	only applies to	con-
	     text 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.

     -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 follow-
	     ing: skip patches for which a file	to patch cannot	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 that.

     -i	patchfile, --input patchfile
	     Causes the	next argument to be interpreted	as the input file name
	     (i.e. a patchfile).  This option may be specified multiple	times.

     -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, --forward
	     Causes patch to ignore patches that it thinks are reversed	or
	     already applied.  See also	-R.

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

     -o	out-file, --output out-file
	     Causes the	next argument to be interpreted	as the output file
	     name.

     -p	strip-count, --strip strip-count
	     Sets the pathname strip count, which controls how pathnames found
	     in	the patch file are treated, in case 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 /u/howard/src/blurfl/blurfl.c:

	     Setting -p0 gives the entire pathname unmodified.

	     -p1 gives

		   u/howard/src/blurfl/blurfl.c

	     without the leading slash.

	     -p4 gives

		   blurfl/blurfl.c

	     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 path-
	     name unmodified.  Whatever	you end	up with	is looked for either
	     in	the current directory, or the directory	specified by the -d
	     option.

     -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 operation.

	     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 cannot, 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.)

     -r	rej-name, --reject-file	rej-name
	     Causes the	next argument to be interpreted	as the reject file
	     name.

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

     -t, --batch
	     Similar to	-f, in that it suppresses questions, but makes some
	     different assumptions: skip patches for which a file to patch
	     cannot 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.

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

     -V	t | nil	| never, --version-control t | nil | never
	     Causes the	next argument to be interpreted	as a method for	creat-
	     ing backup	file names.  The type of backups made can also be
	     given in the PATCH_VERSION_CONTROL	or VERSION_CONTROL environment
	     variables,	which are overridden by	this option.  The -B option
	     overrides this option, causing the	prefix to always be used for
	     making backup file	names.	The values of the
	     PATCH_VERSION_CONTROL and VERSION_CONTROL environment variables
	     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, numbered
			   Always make numbered	backups.

		   nil,	existing
			   Make	numbered backups of files that already have
			   them, simple	backups	of the others.

		   never, simple
			   Always make simple backups.

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

     -x	number,	--debug	number
	     Sets internal debugging flags, and	is of interest only to patch
	     patchers.

     -z	backup-ext, --suffix backup-ext
	     Causes the	next argument to be interpreted	as the backup exten-
	     sion, to be used in place of ".orig".

     --posix
	     Enables strict IEEE Std 1003.1-2008 (``POSIX.1'') conformance,
	     specifically:

	     1.	  Backup files are not created unless the -b option is speci-
		  fied.

	     2.	  If unspecified, the file name	used is	the first of the old,
		  new and index	files that exists.

   Patch Application
     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 contain-
     ing 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,
     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 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 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 out-
     put file plus ".rej".  (Note that the rejected hunk will come out in con-
     text 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	dif-
     ferent 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.

   Filename Determination
     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.
     When checking a prospective file name, pathname components	are stripped
     as	specified by the -p option and the file's existence and	writability
     are checked relative to the current working directory (or the directory
     specified by the -d option).

     If	the diff is a context or unified diff, patch is	able to	determine the
     old and new file names from the diff header.  For context diffs, the
     ``old'' file is specified in the line beginning with "***"	and the
     ``new'' file is specified in the line beginning with "---".  For a	uni-
     fied diff,	the ``old'' file is specified in the line beginning with "---"
     and the ``new'' file is specified in the line beginning with "+++".  If
     there is an "Index:" line in the leading garbage (regardless of the diff
     type), patch will use the file name from that line	as the ``index'' file.

     patch will	choose the file	name by	performing the following steps,	with
     the first match used:

     1.	  If patch is operating	in strict IEEE Std 1003.1-2008 (``POSIX.1'')
	  mode,	the first of the ``old'', ``new'' and ``index''	file names
	  that exist is	used.  Otherwise, patch	will examine either the
	  ``old'' and ``new'' file names or, for a non-context diff, the
	  ``index'' file name, and choose the file name	with the fewest	path
	  components, the shortest basename, and the shortest total file name
	  length (in that order).

     2.	  If no	file exists, patch checks for the existence of the files in an
	  SCCS or RCS directory	(using the appropriate prefix or suffix) using
	  the criteria specified above.	 If found, patch will attempt to get
	  or check out the file.

     3.	  If no	suitable file was found	to patch, the patch file is a context
	  or unified diff, and the old file was	zero length, the new file name
	  is created and used.

     4.	  If the file name still cannot	be determined, patch will prompt the
	  user for the file name to use.

     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	con-
     taining the patch.

   Backup Files
     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", or
     as	specified by the -B, -V, or -z options.	 The extension used for	making
     backup files may also be specified	in the SIMPLE_BACKUP_SUFFIX environ-
     ment variable, which is overridden	by the options above.

     If	the backup file	is a symbolic or hard link to the original file, 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 or is not linked to the original file.

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

   Notes For Patch Senders
     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	will not let them apply	patches	out of order without some warning.

     Second, make sure you have	specified the file names right,	either in a
     context diff header, or with an "Index:" line.  If	you are	patching some-
     thing 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 does not 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 sepa-
     rate files	in case	something goes haywire.

ENVIRONMENT
     POSIXLY_CORRECT	    When set, patch behaves as if the --posix option
			    has	been specified.
     SIMPLE_BACKUP_SUFFIX   Extension to use for backup	file names instead of
			    ".orig".
     TMPDIR		    Directory to put temporary files in; default is
			    /tmp.
     PATCH_VERSION_CONTROL  Selects when numbered backup files are made.
     VERSION_CONTROL	    Same as PATCH_VERSION_CONTROL.

FILES
     $TMPDIR/patch*  patch temporary files
     /dev/tty	     used to read input	when patch prompts the user

EXIT STATUS
     The patch utility exits with one of the following values:

	   0	   Successful completion.
	   1	   One or more lines were written to a reject file.
	   >1	   An error occurred.

     When applying a set of patches in a loop it behooves you to check this
     exit status so you	do not apply a later patch to a	partially patched
     file.

DIAGNOSTICS
     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.

SEE ALSO
     diff(1)

STANDARDS
     The patch utility is compliant with the IEEE Std 1003.1-2008
     (``POSIX.1'') specification (except as detailed above for the --posix
     option), though the presence of patch itself is optional.

     The flags [-BCEFfstVvxz] and [--posix] are	extensions to that specifica-
     tion.

AUTHORS
     Larry Wall	with many other	contributors.

CAVEATS
     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
     Could be smarter about partial matches, excessively deviant offsets and
     swapped code, but that would take an extra	pass.

     Check patch mode (-C) will	fail if	you try	to check several patches in
     succession	that build on each other.  The entire patch code would have to
     be	restructured to	keep temporary files around so that it can handle this
     situation.

     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 suc-
     ceeded to boot.

     If	you apply a patch you have already applied, patch will think it	is a
     reversed patch, and offer to un-apply the patch.  This could be construed
     as	a feature.

FreeBSD	9.3		       January 29, 2013			   FreeBSD 9.3

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | FILES | EXIT STATUS | DIAGNOSTICS | SEE ALSO | STANDARDS | AUTHORS | CAVEATS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=patch&sektion=1&manpath=FreeBSD+10.0-RELEASE>

home | help