


PATCH(1)                                                 PATCH(1)


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

SSYYNNOOPPSSIISS
       ppaattcchh [options] orig patchfile [+ [options] orig]

       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 ".orig" ("~"  on  sys-
       tems  that do not support long filenames), or as specified
       by the --bb, --BB, or --VV switches.   The  extension  used  for
       making  backup  files  may  also  be specified in the SSIIMM--
       PPLLEE__BBAACCKKUUPP__SSUUFFFFIIXX environment variable, which is  overrid-
       den by above switches.

       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 switch; 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, --ee, --nn, or --uu
       switch.  Context diffs (old-style, new-style, and unified)
       and  normal diffs are applied by the _p_a_t_c_h program itself,
       while ed 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
       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



                              LOCAL                             1





PATCH(1)                                                 PATCH(1)


       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
       filenames).  (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 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,  _p_a_t_c_h
       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, _p_a_t_c_h will attempt to get or check
       out the file.)

       Additionally, if the leading garbage contains a "Prereq: "
       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.



                              LOCAL                             2





PATCH(1)                                                 PATCH(1)


       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 filenames and revision level, as mentioned  previ-
       ously.   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.)

       _P_a_t_c_h recognizes the following switches:

       --bb   causes  the  next  argument  to be interpreted as the
            backup extension, to be used in place of  ".orig"  or
            "~".

       --BB   causes  the next argument to be interpreted as a pre-
            fix to the backup file  name.  If  this  argument  is
            specified any argument from -b will be ignored.

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

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

       --DD   causes  _p_a_t_c_h  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 --DD  and
            the argument.

       --ee   forces  _p_a_t_c_h  to  interpret  the patch file as an ed
            script.

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

       --ff   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  does  not  suppress commentary, however.
            Use --ss for that.




                              LOCAL                             3





PATCH(1)                                                 PATCH(1)


       --FF<<nnuummbbeerr>>
            sets the  maximum  fuzz  factor.   This  switch  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   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   forces  _p_a_t_c_h to interpret the patch file as a normal
            diff.

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

       --oo   causes  the  next  argument  to be interpreted as the
            output file name.

       --pp<<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 filename 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".   Whatever  you end up with is looked for
            either in the current  directory,  or  the  directory
            specified by the --dd switch.

       --rr   causes  the  next  argument  to be interpreted as the



                              LOCAL                             4





PATCH(1)                                                 PATCH(1)


            reject file name.

       --RR   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  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, _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 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.)

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

       --SS   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   forces _p_a_t_c_h to interpret the patch file as a unified
            context diff (a unidiff).

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

       --VV   causes the next  argument  to  be  interpreted  as  a
            method  for  creating 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  synonyms  that  are more descriptive.  The
            valid values are (unique abbreviations are accepted):




                              LOCAL                             5





PATCH(1)                                                 PATCH(1)


            `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>>
            sets  internal  debugging  flags,  and is of interest
            only to _p_a_t_c_h patchers.

AAUUTTHHOORR
       Larry Wall <lwall@netlabs.com>
       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
              ".orig" or "~".

       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  filenames  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 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 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



                              LOCAL                             6





PATCH(1)                                                 PATCH(1)


       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.

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


