


PATCH(1)						 PATCH(1)


NNAAMMEE
       patch - apply a diff file to an original

SSYYNNOOPPSSIISS
       ppaattcchh [options] [origfile [patchfile]] [+ [options] [orig-
       file]]...

       but usually just

       ppaattcchh <patchfile

DDEESSCCRRIIPPTTIIOONN
       _P_a_t_c_h will take a patch file containing any  of	the  four
       forms  of  difference listing produced by the _d_i_f_f program
       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 "~" or as specified by
       the  --bb	(----ssuuffffiixx),  --BB	(----pprreeffiixx),	or   --VV	(----vveerr--
       ssiioonn--ccoonnttrrooll)  options.	The  extension	used  for making
       backup  files  may  also	be   specified	in   the   SSIIMM--
       PPLLEE__BBAACCKKUUPP__SSUUFFFFIIXX  environment variable, which is overrid-
       den by the above options.

       If the backup file already exists,  ppaattcchh  creates  a  new
       backup file name by changing the first lowercase letter in
       the last component of the file's name into uppercase.   If
       there  are  no  more  lowercase	letters	in  the name, it
       removes the first character from	the  name.   It  repeats
       this  process  until  it	comes up with a backup file that
       does not already exist.

       You may also specify where you want the output to go  with
       a --oo (----oouuttppuutt) option; if that file already exists, it is
       backed up first.

       If _p_a_t_c_h_f_i_l_e is omitted, or is a hyphen, the patch will be
       read from standard input.

       Upon  startup, patch will attempt to determine the type of
       the diff listing, unless over-ruled by a	--cc  (----ccoonntteexxtt),
       --ee  (----eedd), --nn (----nnoorrmmaall), or --uu (----uunniiffiieedd) option.  Con-
       text diffs (old-style, new-style, and unified) and  normal
       diffs  are  applied  by the _p_a_t_c_h program itself, while _e_d
       diffs are simply fed to the _e_d editor via a pipe.

       _P_a_t_c_h 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
       _p_a_t_c_h, 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, _p_a_t_c_h can detect when the line numbers mentioned in



			      LOCAL				1





PATCH(1)						 PATCH(1)


       the patch are incorrect, and will attempt to find the cor-
       rect  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, _p_a_t_c_h  will  scan
       both  forwards  and  backwards for a set of lines matching
       the context given in the hunk.  First _p_a_t_c_h  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.)   If	_p_a_t_c_h  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" ("#" on systems that do not support long
       file names).  (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 num-
       bers 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)
       _p_a_t_c_h 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 indica-
       tion 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  suspi-
       cious.

       If  no  original	file  is  specified on the command line,
       _p_a_t_c_h will try to figure out from the leading garbage what
       the  name of the file to edit is.  In the header of a con-
       text diff, the file name 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,
       _p_a_t_c_h will try to use the file name from that  line.   The
       context	diff  header takes precedence over an Index line.
       If no file name 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 or is read-only, but
       a suitable SCCS or RCS file is handy, _p_a_t_c_h  will  attempt
       to get or check out the file.

       Additionally, if the leading garbage contains a "Prereq: "



			      LOCAL				2





PATCH(1)						 PATCH(1)


       line, _p_a_t_c_h will take the first word  from  the	prerequi-
       sites line (normally a version number) and check the input
       file to see if that word can be found.  If not, _p_a_t_c_h 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:

	    | patch -d /usr/src/local/blurfl

       and patch a file in the blurfl directory directly from the
       article containing the patch.

       If the patch file contains more than one patch, _p_a_t_c_h 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  deter-
       mined  for  each diff listing, and that the garbage before
       each diff listing will be examined for interesting  things
       such as file names and revision level, as mentioned previ-
       ously.  You can give options (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.)

       _P_a_t_c_h recognizes the following options:

       --bb ssuuffff,, ----ssuuffffiixx==ssuuffff
	    causes ssuuffff to be interpreted as  the  backup  exten-
	    sion, to be used in place of "~".

       --BB pprreeff,, ----pprreeffiixx==pprreeff
	    causes  pprreeff  to  be  interpreted  as a prefix to the
	    backup file name. If this argument is specified,  any
	    argument from --bb will be ignored.

       --cc,, ----ccoonntteexxtt
	    forces _p_a_t_c_h to interpret the patch file as a context
	    diff.

       --dd ddiirr,, ----ddiirreeccttoorryy==ddiirr
	    causes _p_a_t_c_h to interpret ddiirr as a directory, and  cd
	    to it before doing anything else.

       --DD ssyymm,, ----iiffddeeff==ssyymm
	    causes  _p_a_t_c_h  to use the "#ifdef...#endif" construct
	    to mark changes.  ssyymm will be used as the differenti-
	    ating symbol.

       --ee,, ----eedd
	    forces  _p_a_t_c_h  to  interpret  the patch file as an _e_d
	    script.




			      LOCAL				3





PATCH(1)						 PATCH(1)


       --EE,, ----rreemmoovvee--eemmppttyy--ffiilleess
	    causes _p_a_t_c_h to remove output files	that  are  empty
	    after the patches have been applied.

       --ff,, ----ffoorrccee
	    forces  _p_a_t_c_h  to  assume that the user knows exactly
	    what he or she is doing, and to  not  ask  any  ques-
	    tions.   It	assumes  the following: skip patches for
	    which a file to patch can't	be  found;  patch  files
	    even  though  they	have  the  wrong  version for the
	    ``Prereq:''	line  in  the	patch;	and  assume  that
	    patches  are not reversed even if they look like they
	    are.  This option does not suppress	commentary;  use
	    --ss for that.

       --tt,, ----bbaattcchh
	    similar  to	--ff, in that it suppresses questions, but
	    makes some different assumptions:  skip  patches  for
	    which  a  file  to	patch can't be found (the same as
	    --ff); skip patches for which the file  has  the  wrong
	    version  for  the  ``Prereq:'' line in the patch; and
	    assume that patches are reversed if	they  look  like
	    they are.

       --FF nnuummbbeerr,, ----ffuuzzzz==nnuummbbeerr
	    sets  the  maximum	fuzz  factor.	This  option only
	    applies to context diffs, and causes _p_a_t_c_h 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.

       --ll,, ----iiggnnoorree--wwhhiitteessppaaccee
	    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  pat-
	    tern  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.

       --nn,, ----nnoorrmmaall
	    forces _p_a_t_c_h to interpret the patch file as a  normal
	    diff.

       --NN,, ----ffoorrwwaarrdd
	    causes  _p_a_t_c_h  to  ignore  patches that it thinks are
	    reversed or already applied.  See also --RR ..

       --oo ffiillee,, ----oouuttppuutt==ffiillee
	    causes ffiillee to be  interpreted  as	the  output  file
	    name.



			      LOCAL				4





PATCH(1)						 PATCH(1)


       --pp[[nnuummbbeerr]],, ----ssttrriipp[[==nnuummbbeerr]]
	    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 slashes are to be stripped
	    from the front of  the  pathname.	(Any  intervening
	    directory  names also go away.)  For example, suppos-
	    ing the file name in the patch file was

		 /u/howard/src/blurfl/blurfl.c

	    setting --pp or --pp00 gives the entire	pathname  unmodi-
	    fied, --pp11 gives

		 u/howard/src/blurfl/blurfl.c

	    without the leading slash, --pp44 gives

		 blurfl/blurfl.c

	    and	not	specifying  --pp	at  all	just  gives  you
	    "blurfl.c", unless all  of	the  directories  in  the
	    leading  path  (u/howard/src/blurfl)  exist	and that
	    path is relative, in which case you	get  the  entire
	    pathname  unmodified.   Whatever  you  end up with is
	    looked for either in the current  directory,  or  the
	    directory specified by the --dd option.

       --rr ffiillee,, ----rreejjeecctt--ffiillee==ffiillee
	    causes  ffiillee  to  be  interpreted  as the reject file
	    name.

       --RR,, ----rreevveerrssee
	    tells _p_a_t_c_h 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.)
	    _P_a_t_c_h  will	attempt  to swap each hunk around before
	    applying it.  Rejects will come out	in  the  swapped
	    format.   The  --RR  option  will not work with _e_d diff
	    scripts because there is too  little  information  to
	    reconstruct the reverse operation.

	    If	the  first  hunk  of  a	patch	fails, _p_a_t_c_h 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 --RR option 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



			      LOCAL				5





PATCH(1)						 PATCH(1)


	    with  a  delete,  which  will  fail,  triggering  the
	    heuristic.)

       --ss,, ----ssiilleenntt,, ----qquuiieett
	    makes  _p_a_t_c_h  do  its  work silently, unless an error
	    occurs.

       --SS,, ----sskkiipp
	    causes _p_a_t_c_h to ignore  this  patch	from  the  patch
	    file,  but	continue on looking for the next patch in
	    the file.  Thus

		 patch -S + -S + <patchfile

	    will ignore the first and second of three patches.

       --uu,, ----uunniiffiieedd
	    forces _p_a_t_c_h to interpret the patch file as a unified
	    context diff (a unidiff).

       --vv,, ----vveerrssiioonn
	    causes  _p_a_t_c_h  to  print  out its revision header and
	    patch level.

       --VV mmeetthhoodd,, ----vveerrssiioonn----ccoonnttrrooll==mmeetthhoodd
	    causes mmeetthhoodd to be interpreted as a method for  cre-
	    ating  backup  file	names.	The type of backups made
	    can also be given in the VVEERRSSIIOONN__CCOONNTTRROOLL  environment
	    variable, which is overridden by this option.  The --BB
	    option overrides this option, causing the  prefix  to
	    always  be	used  for  making backup file names.  The
	    value of the VVEERRSSIIOONN__CCOONNTTRROOLL environment variable and
	    the	argument to the --VV option are like the GNU Emacs
	    `version-control' variable; they also recognize  syn-
	    onyms  that	are  more descriptive.	The valid values
	    are (unique abbreviations are accepted):

	    `t' or `numbered'
		   Always make numbered backups.

	    `nil' or `existing'
		   Make numbered backups of  files  that  already
		   have them, simple backups of the others.  This
		   is the default.

	    `never' or `simple'
		   Always make simple backups.

       --xx nnuummbbeerr,, ----ddeebbuugg==nnuummbbeerr
	    sets internal debugging flags,  and	is  of	interest
	    only to _p_a_t_c_h patchers.

AAUUTTHHOORR
       Larry Wall <lwall@netlabs.com>



			      LOCAL				6





PATCH(1)						 PATCH(1)


       with many other contributors.

EENNVVIIRROONNMMEENNTT
       TTMMPPDDIIRR Directory	to  put  temporary  files in; default is
	      /tmp.

       SSIIMMPPLLEE__BBAACCKKUUPP__SSUUFFFFIIXX
	      Extension to use for backup file names  instead  of
	      "~".

       VVEERRSSIIOONN__CCOONNTTRROOLL
	      Selects when numbered backup files are made.

FFIILLEESS
       $TMPDIR/patch*

SSEEEE AALLSSOO
       diff(1)

NNOOTTEESS FFOORR PPAATTCCHH SSEENNDDEERRSS
       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 file names right, either in a  context  diff
       header, or with an Index: line.	If you are patching some-
       thing in a subdirectory, be sure to tell the patch user to
       specify	a  --pp  option 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  tar-
       get 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 haywire.

DDIIAAGGNNOOSSTTIICCSS
       Too many to list here, but generally indicative that _p_a_t_c_h
       couldn't parse your patch file.

       The  message  "Hmm..." indicates that there is unprocessed
       text in the patch file and that	_p_a_t_c_h  is  attempting  to
       intuit  whether	there is a patch in that text and, if so,
       what kind of patch it is.

       _P_a_t_c_h will exit with a non-zero status if any reject files
       were created.  When applying a set of patches in a loop it
       behooves you to check this exit status so you don't  apply
       a later patch to a partially patched file.



			      LOCAL				7





PATCH(1)						 PATCH(1)


CCAAVVEEAATTSS
       _P_a_t_c_h  cannot  tell  if	the line numbers are off in an _e_d
       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  prob-
       lem.  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 indication that the patch  worked,
       but not always.

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

BBUUGGSS
       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 OLD-
       CODE ... #else ...  #endif), _p_a_t_c_h is incapable of  patch-
       ing  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, _p_a_t_c_h will
       think it is a reversed patch, and offer	to  un-apply  the
       patch.  This could be construed as a feature.


























			      LOCAL				8


