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

FreeBSD Manual Pages

  
 
  

home | help
PATCH(1)		    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	|  none]  [-x  number]
	     [-z backup-ext] [--posix] [origfile [patchfile]]
       patch <patchfile

DESCRIPTION
       patch will take a patch file containing any of the four forms  of  dif-
       ference listing produced	by the diff(1) program and apply those differ-
       ences  to  an original file, producing a	patched	version.  If patchfile
       is omitted, 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) edi-
       tor 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  de-
	       fault  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 specify-
	       ing "-V existing".  This	option is currently the	 default,  un-
	       less --posix is specified.

       -C, --check, --dry-run
	       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 differen-
	       tiating 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
	       following:  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	multi-
	       ple 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 se-
	       quence of whitespace in the pattern line	 will  match  any  se-
	       quence  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  di-
	       rectory	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
	       pathname	 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 am afraid that  does  happen  occasion-
	       ally,  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	recon-
	       struct 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 | none, --version-control t |	nil | never | none
	       Causes the next argument	to be interpreted as a method for cre-
	       ating  backup file names.  The type of backups made can also be
	       given in	the PATCH_VERSION_CONTROL or VERSION_CONTROL  environ-
	       ment  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  abbrevia-
	       tions 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.

		     none    Do	not make 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 spec-
		    ified.

	       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
       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 ac-
       count.

       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 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	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".	 (Note that the	rejected hunk will come	out in
       context	diff form whether the input patch was a	context	diff or	a nor-
       mal 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 loca-
       tion 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 suitable file	was found to patch, the	patch file is  a  con-
	    text  or  unified  diff, and the old file was zero length, the new
	    file name is created and used.

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

       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  environment  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  op-
       tion; 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
       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.	If the file you	want to	create
       already exists in the target directory when the diff is	applied,  then
       patch  will identify the	patch as potentially reversed and offer	to re-
       verse the patch.

       Fourth, take care not to	send out reversed patches, since it makes peo-
       ple 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 op-
       tion.

       The flags [-BCEFfstVvxz]	and [--posix] are extensions to	that  specifi-
       cation.

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 indi-
       cation 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
       succeeded 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  con-
       strued as a feature.

FreeBSD	13.2		       November	3, 2019			      PATCH(1)

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

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

home | help