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

FreeBSD Manual Pages

  
 
  

home | help
patch(1)		    General Commands Manual		      patch(1)

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

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

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

DESCRIPTION
       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
       account.

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

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

       forces
	    patch to interpret the patch file as a context diff.

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

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

       forces
	    patch to interpret the patch file as an ed script.

       forces
	    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
       to
	    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.

       forces
	    patch to interpret the patch file as a normal diff.

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

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

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

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

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

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

RETURN VALUE
       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.

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.

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

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

FILES
SEE ALSO
       diff(1),	ed(1).

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

BUGS
       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
       patch.

STANDARDS CONFORMANCE
								      patch(1)

NAME | SYNOPSIS | DESCRIPTION | EXTERNAL INFLUENCES | Environment Variables | RETURN VALUE | DIAGNOSTICS | WARNINGS | FILES | SEE ALSO | NOTES FOR PATCH SENDERS | BUGS | STANDARDS CONFORMANCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=patch&sektion=1&manpath=HP-UX+11.22>

home | help