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

FreeBSD Manual Pages


home | help
patch(1)		    General Commands Manual		      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  ac-

       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  an-
       other 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 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.  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 en-
	    ables 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 do-
	    ing, 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 ig-
	    nore  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 in-
	    put	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 ap-
	    plied.  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 al-
	    ways  succeed, due to the fact that	a null context will match any-
	    where.  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