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

   Non-XPG4 version
       [options] orig patchfile	options] orig]

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

       will  take a patch file containing any of the three forms of difference
       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	exist-
       ing  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	prece-
       dence 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
       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:

       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  the	-o option. See the description of this
       option for more details.

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

       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.

       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.

       The result obtained from	the XPG4 options which forces the  patch  com-
       mand  to	 interpret  the	diff file either as a context diff or as an ed
       script or as a normal diff respectively is unspecified. For example, if
       one  forces  the	 patch command to treat	the context diff file as an ed
       script, the result is unspecified. The same is true if one forces patch
       to  treat  an  ed  script as a context file and so on..	When a diff is
       forced with the above options, the diff file is searched	 for  patterns
       that  are  specific  to that type of diff file. If the diff file	is not
       what was	specified by the option, the file is checked for ed  commands.
       If  ed  commands	are present in the diff	file, then the file is assumed
       to be an	ed_diff	file and the patch proceeds.

       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