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

   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  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	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  op-
       tion 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 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.)	 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 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 re-
	      ject 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