User Commands                                            PATCH(1)


NAME

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


SYNOPSIS

     patch [options] orig patchfile [+ [options] orig]

     spatch [options] orig patchfile [+ [options] orig]

     opatch [options] orig patchfile [+ [options] orig]

     sccspatch [options] orig patchfile [+ [options] orig]

     but usually just

     patch <patchfile


DESCRIPTION

     Patch will take a patch file  containing  any  of  the  four
     forms of difference listing produced by the diff 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 and no backup is made.  The -b  switch
     tells  patch  to create a backup file.  You may also specify
     where you want the output to go with a -o switch.  If patch-
     file is omitted, or is a hyphen, the patch will be read from
     standard input.

     By default, this version of patch is in  strict  POSIX  mode
     and  does  not  permit  extensions.   If  patch is called as
     opatch, it behaves like  the  original  patch  utility  from
     Larry  Wall (except for filename determination) but with new
     additional features enabled.  The name spatch may be used as
     an  alternate  name  for  the  strict POSIX patch.  The name
     sccspatch may be used to select POSIX  patch  behavior  with
     extensions  from  Larry  Wall  and  extensions  from  recent
     development.


OPTIONS

     Patch recognizes the following switches:

     -b       Save a copy of the original contents of each  modi-
              fied file, before the differences are applied, in a
              file  of  the  same  name  with  the  suffix  .orig
              appended  to  it. If the file already exists, it is
              overwritten.  If multiple patches  are  applied  to
              the  same  file, the .orig file is written only for
              the first patch. When the -o outfile option is also
              specified,  file  .orig is not created but, if out-
              file already exists, outfile .orig is created.

              The original behavior of the -b option as found  in

SunOS 5.10           Last change: 2015/05/30                    1


User Commands                                            PATCH(1)

              the  original  patch  from  Larry Wall is available
              with the -z option.

     -B       causes the next argument to  be  interpreted  as  a
              prefix to the backup file name. If this argument is
              specified any argument from  -z  will  be  ignored.
              For example, with -B /old/ the backup file name for
              src/patch/util.c is /old/src/patch/util.c.

              This argument is an extension to Larry Wall's patch
              v2.0.1.4,   patchlevel   8,   made   by   M.  Greim
              (greim@sbsvax.uucp).

              This option is not available in strict POSIX mode.

     -c       forces patch to interpret the patch file as a  con-
              text diff.

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

     -D define
              causes patch to use the #ifdef define...#endif con-
              struct  to mark changes.  The argument following -D
              will be used as the differentiating symbol.

     -E       Remove output files that are empty after  patching.
              If  the patch is in the unified context diff format
              and the diff header contains a  correct  zero  time
              stamp  for  the  removed  file,  this option is not
              needed.  A unified context  diff  created  by  diff
              -Nur  marks  removed files by including a time that
              refers to the beginning of the year 1970  UTC  like
              in the following example diff output header:

              --- old/Makefile          2011-01-25 12:08:18 +0100
              +++ new/Makefile          1970-01-01 01:00:00 +0100
              @@ -1,18 +0,0 @@

              The zero time stamp is only recognized in case  the
              time  stamp  is  printed  in the format required by
              POSIX for unified diffs as in the example above  or
              with added sub second time information.

              This option is not available in strict POSIX mode.

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

     -f       forces patch to assume that the user knows  exactly
              what  he  or she is doing, and to not ask any ques-
              tions.   It   does   not   suppress   informational

SunOS 5.10           Last change: 2015/05/30                    2


User Commands                                            PATCH(1)

              messages, however.  Use -s for that.

              This option is not available in strict POSIX mode.

     -Fnumber sets the maximum fuzz  factor.   This  switch  only
              applies  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 available in strict POSIX mode.

     -i patchfile
              Reads the patch information from the file named  by
              the  path  name patchfile, rather than the standard
              input.

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

     -n       forces patch to interpret the patch file as a  nor-
              mal diff.

     -N       causes patch to ignore patches that it  thinks  are
              reversed or already applied.  See also -R .

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

     -pnumber 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  direc-
              tory  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,  supposing  the filename in the patch file
              was

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

              setting -p0 gives the entire  pathname  unmodified,
              -p1 gives

SunOS 5.10           Last change: 2015/05/30                    3


User Commands                                            PATCH(1)

                   u/howard/src/blurfl/blurfl.c

              without the leading slash, -p4 gives

                   blurfl/blurfl.c

              and  not  specifying  -p  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 -d switch.

              When in POSIX mode, -p always must  have  an  argu-
              ment,  in non-POSIX mode -p may be used as an alias
              for -p0.

     -r rejectfile
              causes the next argument to be interpreted  as  the
              reject  file name.  In the default case, the reject
              file has the same name as the output file, with the
              suffix .rej appended to it.

     -R       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.)   Patch  will  attempt  to  swap each hunk
              around before applying it.  Rejects will  come  out
              in the swapped format.  The -R 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  -R  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.)

     -s       makes patch do its work silently, unless  an  error
              occurs.

              This option is not available in strict POSIX mode.

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

SunOS 5.10           Last change: 2015/05/30                    4


User Commands                                            PATCH(1)

                   patch -S + -S + <patchfile

              will ignore the first and second of three patches.

              This option is not available in strict POSIX mode.

     -u       forces patch to interpret the patch file as a  uni-
              fied context diff (a unidiff).

     -v       causes patch to print out it's revision header  and
              patch level.

              This option is not available in strict POSIX mode.

     -vv      causes patch to be more verbose.

     -W+      Causes patch to permit enhancements  from  historic
              and recent versions in POSIX mode.

     -Wall    Causes patch to implement compatibility  for  Larry
              Wall's patch-2.0.

              This  currently  only  applies  to  the  way  patch
              selects   the  filename  from  the  patchfile.   By
              default,  patch  uses  the  filename  determination
              algorithm  from POSIX that defaults to the original
              filename from the diff header.  The algorithm  from
              patch-2.0  defaults  to  the shorter name, assuming
              that filename.orig is used as original filename and
              filename is used as new filename.

     -Wposix  Causes patch to go into strict  POSIX  mode.   This
              disables  the  effect  of  a previous -W+ and -Wall
              option.

     -W-posix Causes patch to revert the effect of a previous -W+
              and -Wposix option.

     -xnumber sets internal debugging flags, and is  of  interest
              only to patch patchers.

              This option is not available in strict POSIX mode.

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

              This option is not available in strict POSIX mode.


EXTENDED DESCRIPTION


SunOS 5.10           Last change: 2015/05/30                    5


User Commands                                            PATCH(1)

     Upon startup, patch will attempt to determine  the  type  of
     the  diff  listing, unless over-ruled by a -c, -e, -n, or -u
     switch.  Context diffs (old-style, new-style,  and  unified)
     and  normal  diffs  are applied by the patch program itself,
     while ed diffs are simply 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 con-
     sistent 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.)  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" or "#" .  (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 dif-
     ferent  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.

  Patch File Format
     If no original file is specified on the command line,  patch
     will  try  to  figure  out from the leading garbage what the

SunOS 5.10           Last change: 2015/05/30                    6


User Commands                                            PATCH(1)

     name of the file to edit  is.   The  following  formats  are
     recognized.

     A context diff includes the following headers:

         "*** filename timestamp"
         "--- filename timestamp"

     The first line refers to the filename and timestamp  of  the
     original  file  and  the  second  line refers to the changed
     file.

     A unified context diff includes the following headers:

         "--- filename timestamp"
         "+++ filename timestamp"

     The first line refers to the filename and timestamp  of  the
     original  file  and  the  second  line refers to the changed
     file.

         "Index:filename"

     May be added in order to give the filename in case if a nor-
     mal diff or an ed script.

     If not in strict POSIX mode,

         "Prereq: version-id"

     is recognized and used to match against a  version  specific
     string in the file to patch.

  Filename Determination
     If no original file is specified on the command line,  patch
     will use the following search preference:

     1.   In the header of a context diff, the filename is  found
          from  lines beginning with "***" or "---" (if the patch
          is a unified context diff).

     2.   In the header of a context diff, the filename is  found
          from  lines beginning with "---" or "+++" (if the patch
          is a unified context diff).

          If the option -Wall was specified, the shortest name of
          an existing file from the two above wins.

     3.   If the diff  type  is  not  context  and  there  is  an

SunOS 5.10           Last change: 2015/05/30                    7


User Commands                                            PATCH(1)

          "Index:"   line  in the leading garbage, patch will try
          to use the filename from that line.  The  context  diff
          header takes precedence over an Index line.

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

     5.   If no filename can be intuited from  the  leading  gar-
          bage,  you  will  be  asked for the name of the file to
          patch via the controlling terminal (e.g. via stderr  or
          /dev/tty).

     Additionally, if not in strict POSIX mode and 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:

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

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

  Patch Application
     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 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.  If patch is not in POSIX mode, you can give switches
     (and another original file name) for the second  and  subse-
     quent 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.)


ENVIRONMENT

     POSIXLY_CORRECT
          If present, patch  operates  in  POSIX  mode  but  also
          recognizes the additional non-POSIX options and permits
          non-POSIX behavior like removing files that  have  been
          marked  removed  in the diff -Nur output. See -E option
          for more information.  This behavior is implemented  to
          make patch more compatible to the gpatch program.

SunOS 5.10           Last change: 2015/05/30                    8


User Commands                                            PATCH(1)


FILES

     /tmp/patch*


EXIT STATUS

     The following exit values are returned:

     0     Successful completion.

     1     One or more lines were written to a reject file.

     >1    An error occurred.


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 -p
     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 haywire.


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.

SunOS 5.10           Last change: 2015/05/30                    9


User Commands                                            PATCH(1)

     When applying a set of patches in a loop it behooves you  to
     check  the exit status so you don't apply a later patch to a
     partially patched file.


CAVEATS

     Patch 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 con-
     text  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  indication  that  the patch worked, but not
     always.

     Patch 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 gen-
     erated from.


COMPATIBILITY ISSUES

     The POSIX standard introduced some small differences to  the
     traditional  behavior of patch.  The behavior of gpatch (GNU
     patch) differs from both, the traditional  patch  and  POSIX
     patch.

     If you like to write portable patch scripts, you  should  be
     aware of the differences:

     +    Traditional patch by default created backups  with  the
          .orig suffix and the -b option allowed to define a dif-
          ferent suffix.  Modern patch implementations by default
          do  not create backup files and allow to enable backups
          with the -b option that does  not  permit  a  parameter
          with POSIX.

          The -b suffix behavior  of  the  traditional  patch  is
          equivalent  to -b -z suffix with modern patch implemen-
          tations in case that enhancements over POSIX  are  per-
          mitted.

     +    Patch writes informational messages to stderr and  does
          not  use  stdout, while gpatch uses stdout for informa-
          tional messages.

     +    Gpatch changed some of the informational messages;  you
          cannot expect to get the same messages as with patch.

          For portable scripts, do not rely on informational mes-
          sages.

SunOS 5.10           Last change: 2015/05/30                   10


User Commands                                            PATCH(1)

     +    In traditional patch, the -p option  did  not  need  to
          have  an operand. With POSIX patch, -p always must have
          an operand. The option -p without  argument  in  tradi-
          tional patch is equivalent to -p 0 in POSIX patch.

          For portability, use the -p option with no space to the
          following argument, e.g.  -p1.

     +    The option -i patchfile  is  only  supported  by  POSIX
          patch, but not by traditional patch or gpatch.

     +    Traditional patch used  several  different  and  partly
          undocumented  methods to determine the name of the file
          to be  patched  from  the  patchfile  that  could  e.g.
          result  to  create  an  incorrect  new  file  with  new
          filename if a line was inserted at the beginning of  an
          existing  file.   This  patch  and  POSIX patch use the
          POSIX method for Filename Determination and only permit
          to use the the special Index: line.

     +    Gpatch uses a different method to read replies to ques-
          tions  to  the  user  than  patch does.  Do not rely on
          patch to read from stderr.

     +    Traditional  patch  used  an  exit  code   value   that
          reflected the number of failed hunks and an exit code 1
          if there was one failed  hunk  or  any  other  problem.
          POSIX  patch  uses  exit code 1 if there was any failed
          hunk and an exit code > 1 if other problems occurred.

     +    Patch does not  implement  support  for  long  options,
          while  gpatch  documents  and  implements  various long
          options.

     For maximum portability, limit  yourself  to  the  following
     options:
         -c
         -d dir
         -D define
         -e
         -l
         -n
         -N
         -o outfile
         -pnum
         -R
         -r rejectfile
         -u

     Never use long options.  Use a shorter name for the original
     filename in the diff header of the patchfile.

SunOS 5.10           Last change: 2015/05/30                   11


User Commands                                            PATCH(1)


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  OLD-
     CODE  ...  #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 construed as a feature.


AUTHORS

     Larry Wall <larry@wall.org> wrote the  original  version  of
     patch.

     Wayne Davison added unidiff support.

     Joerg Schilling added modern portability code, code to  sup-
     port  arbitrarily long lines, large file support and code to
     support POSIX compliance.

SunOS 5.10           Last change: 2015/05/30                   12


Man(1) output converted with man2html


FhG Schily's Home VED powered