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

FreeBSD Manual Pages


home | help
patch(1)							      patch(1)

       patch - a program for applying a	diff file to an	original

       For non-XPG4 version

       [options] orig patchfile	options] orig]

       but usually just

       For XPG4	version

       dir] define] patchfile] outfile]	num] rejectfile] [file]

       Patch  will take	a patch	file containing	any of the three forms of dif-
       ference listing produced	by the diff program (normal, context or	in the
       style of	ed) 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", or as specified by the switch. Note  that	 func-
       tionality of this option	varies for XPG4	version.  You may also specify
       where you want the output to go with a switch.  If patchfile  is	 omit-
       ted,  or	 is a hyphen, the patch	will be	read from standard input.  For
       XPG4 version, patchfile has to be specified as argument to  switch.  If
       this  option is omitted or a hyphen is specified	as argument, the patch
       will read from standard input.

       Upon startup, patch will	attempt	to determine  the  type	 of  the  diff
       listing,	 unless	 over-ruled  by	a or switch.  Context diffs and	normal
       diffs are applied by the	patch program itself, while ed diffs are  sim-
       ply 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

       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  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.)  Note
       that for	XPG4 version maximum fuzz factor can not be  specified	as  an
       option  and  the	 default maximum fuzz factor is	used.  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 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 differ-
       ent 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.  Note that XPG4  version  does  not
       support	verbose	 option.  So,  most of the diagnostic messages are not
       printed for this	version. However user  queries	will  always  be  dis-

       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 filename 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
       filename	from that line.	 The context diff header takes precedence over
       an Index	line.  If  no  filename	 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, 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 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:

       and patch a file	in the blurfl directory	directly from the article con-
       taining 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 must be determined	for each diff listing, and  that  the  garbage
       before  each  diff listing will be examined for interesting things such
       as filenames and	revision level,	as mentioned previously.  You can give
       switches	(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, however.)

       With XPG4 version, processing of	multiple patches varies	 considerably.
       You  can	 not  specify different	options	for different patches. Options
       remain same for all the patches.	This also affects the contents of out-
       put  file  specified with -o option. See	the description	of this	option
       for more	details.

       Patch recognizes	the following switches:

       causes the next argument	to be interpreted as the backup	extension,  to
	    used in place of ".orig".  (For XPG4 version this  option  varies.
	    With  this	option	no  argument  is  required and the option only
	    enables the	backup process.	Always default extension is used.)

	    patch to interpret the patch file as a context diff.

	    patch to interpret the next	argument as a directory, and cd	to  it
	    before doing anything else.

	    patch to use the "#ifdef...#endif" construct to mark changes.  The
	    argument following will be used  as	 the  differentiating  symbol.
	    Note  that,	 unlike	 the C compiler, there must be a space between
	    the	and the	argument.  (For	XPG4 version this option varies.  With
	    this version "#ifndef" constructor is not used.)

	    patch to interpret the patch file as an ed script.

	    patch  to  assume  that  the  user knows exactly what he or	she is
	    doing, and to not ask any questions.  It does not suppress commen-
	    tary,  however.   Use  for that.  (This option is not supported by
	    XPG4 version.)

       sets the	maximum	fuzz factor.
	    This switch	only applied 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.  (This option	is not supported by XPG4 version.)

       This  option is supported only by XPG4 version. It causes next argument
	    be interpreted as the patch	file name.

       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.

	    patch to interpret the patch file as a normal diff.

	    patch to ignore patches that it thinks  are	 reversed  or  already
	    applied.  See also

       causes the next argument	to be interpreted as the output	file name.
	    There  are	some  added  features  for  the	XPG4 version. Multiple
	    patches for	a single file will be applied to the intermediate ver-
	    sions of the file created by any previous patches, and will	result
	    in multiple,concatenated versions of the  file  being  written  to
	    output file.

       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
	    backslashes	are to be stripped from	the  front  of	the  pathname.
	    (Any intervening directory names also go away.)  For example, sup-
	    posing the filename	in the patch file was

	    setting or gives the entire	pathname unmodified, gives

	    without the	leading	slash, gives

	    and	not specifying at all just gives you "blurfl.c".  Whatever you
	    end	 up with is looked for either in the current directory,	or the
	    directory specified	by the switch.

       causes the next argument	to be interpreted as the reject	file name.

	    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 switch	will not work with  ed	diff  scripts  because
	    there  is too little information to	reconstruct the	reverse	opera-

	    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 switch 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.)

	    patch  do its work silently, unless	an error occurs.  (This	option
	    is not supported by	XPG4 version.)

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

	    will  ignore  the first and	second of three	patches.  (This	option
	    is not supported by	XPG4 version.)

	    patch to print out it's revision header and	 patch	level.	 (This
	    option is not supported by XPG4 version.)

       sets internal debugging flags, and is of	interest only to
	    patch patchers.  (This option is not supported by XPG4 version.)

Environment Variables
       UNIX95  determines  which version of patch is used. If this variable is
       set, patch exhibits XPG4	behaviour.

       The following exit values are returned for XPG4 version:

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

       For non-XPG4 version exit values	vary as	follows:

       Successful completion or	one or more lines were	written	 to  a	reject
       An error	occurred.

       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.

       Note  that  only	 few diagnostic	messages are printed for XPG4 version,
       since it	does not support verbose option.

       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.

       diff(1),	ed(1).

       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
       filenames  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 switch 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  hay-

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

       One  more  thing	to be noted with respect to XPG4 version of patch.  If
       you are using multiple patches for different files, group patches  that
       have  to	 be applied to a single	file. Otherwise, intermediate versions
       of the previous patches of a file will not  be  used  for  the  current



Want to link to this manual page? Use this URL:

home | help