home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / rcs / patch.man < prev    next >
Text File  |  1991-12-24  |  15KB  |  275 lines
  1. NAME
  2.      patch - a program for applying a diff file to an original
  3.  
  4. SYNOPSIS
  5.      patch [options] orig patchfile [+ [options] orig]
  6.  
  7.      but usually just
  8.  
  9.      patch <patchfile
  10.  
  11. DESCRIPTION
  12.      Patch will take a  patch  file  containing  any  of  the  four  forms  of
  13.      difference   listing  produced  by  the  diff  program  and  apply  those
  14.      differences to  an  original  file,  producing  a  patched  version.   By
  15.      default,  the  patched  version is put in place of the original, with the
  16.      original file backed up to the same name with the extension ``.orig''  or
  17.      ``~'' , or as specified by the -b switch.  You may also specify where you
  18.      want the output to go with a -o switch.  If patchfile is omitted, or is a
  19.      hyphen, the patch will be read from standard input.
  20.  
  21.      Upon startup, patch will attempt  to  determine  the  type  of  the  diff
  22.      listing,  unless over-ruled by a -c, -e, -n, or -u switch.  Context diffs
  23.      (old-style, new-style, and unified) and normal diffs are applied  by  the
  24.      patch  program itself, while ed diffs are simply fed to the ed editor via
  25.      a pipe.
  26.  
  27.      Patch will try to skip any leading garbage, apply the diff, and then skip
  28.      any  trailing  garbage.   Thus  you  could  feed  an  article  or message
  29.      containing a diff listing to patch, and it should work.   If  the  entire
  30.      diff is indented by a consistent amount, this will be taken into account.
  31.  
  32.      With context diffs, and to a lesser extent with normal diffs,  patch  can
  33.      detect  when  the  line numbers mentioned in the patch are incorrect, and
  34.      will attempt to find the correct place to apply each hunk of  the  patch.
  35.      As  a  first guess, it takes the line number mentioned for the hunk, plus
  36.      or minus any offset used in applying the previous hunk.  If that  is  not
  37.      the  correct place, patch will scan both forwards and backwards for a set
  38.      of lines matching the context given in the hunk.  First patch looks for a
  39.      place  where  all lines of the context match.  If no such place is found,
  40.      and it's a context diff, and the maximum fuzz factor is set to 1 or more,
  41.      then  another  scan  takes  place  ignoring  the  first  and last line of
  42.      context.  If that fails, and the maximum fuzz factor is set to 2 or more,
  43.      the first two and last two lines of context are ignored, and another scan
  44.      is made.  (The default maximum fuzz factor is 2.)  If patch cannot find a
  45.      place  to  install  that hunk of the patch, it will put the hunk out to a
  46.      reject file, which normally is the name of the output file plus  ``.rej''
  47.      or  ``#''  .   (Note that the rejected hunk will come out in context diff
  48.      form whether the input patch was a context diff or a normal diff.  If the
  49.      input  was a normal diff, many of the contexts will simply be null.)  The
  50.      line numbers on the hunks in the reject file may be different than in the
  51.      patch file: they reflect the approximate location patch thinks the failed
  52.      hunks belong in the new file rather than the old one.
  53.  
  54.      As each hunk is completed, you will be told whether the hunk succeeded or
  55.      failed, and which line (in the new file) patch thought the hunk should go
  56.      on.  If this is different from the line number specified in the diff  you
  57.      will be told the offset.  A single large offset MAY be an indication that
  58.      a hunk was installed in the wrong place.  You will also be told if a fuzz
  59.      factor  was  used  to  make  the  match, in which case you should also be
  60.      slightly suspicious.
  61.  
  62.      If no original file is specified on the command line, patch will  try  to
  63.      figure out from the leading garbage what the name of the file to edit is.
  64.      In the header of a  context  diff,  the  filename  is  found  from  lines
  65.      beginning  with ``***'' or ``---'', with the shortest name of an existing
  66.      file winning.  Only context diffs have lines like that, but if  there  is
  67.      an  ``Index:''   line  in  the leading garbage, patch will try to use the
  68.      filename from that line.  The context diff header takes  precedence  over
  69.      an  Index line.  If no filename can be intuited from the leading garbage,
  70.      you will be asked for the name of the file to patch.
  71.  
  72.      (If the original file cannot be found, but a suitable SCCS or RCS file is
  73.      handy, patch will attempt to get or check out the file.)
  74.  
  75.      Additionally, if the leading garbage contains a ``Prereq: '' line,  patch
  76.      will  take the first word from the prerequisites line (normally a version
  77.      number) and check the input file to see if that word can  be  found.   If
  78.      not, patch will ask for confirmation before proceeding.
  79.  
  80.      The upshot of all this is that you should be able to say, while in a news
  81.      interface, the following:
  82.  
  83.           | patch -d /usr/src/local/blurfl
  84.  
  85.      and patch a file in  the  blurfl  directory  directly  from  the  article
  86.      containing the patch.
  87.  
  88.      If the patch file contains more than one patch, patch will try  to  apply
  89.      each  of  them  as  if  they came from separate patch files.  This means,
  90.      among other things, that it is assumed that the name of the file to patch
  91.      must  be  determined  for  each diff listing, and that the garbage before
  92.      each diff listing  will  be  examined  for  interesting  things  such  as
  93.      filenames  and  revision  level,  as  mentioned previously.  You can give
  94.      switches (and another original file name) for the second  and  subsequent
  95.      patches  by  separating  the corresponding argument lists by a `+'.  (The
  96.      argument list for a second or subsequent patch  may  not  specify  a  new
  97.      patch file, however.)
  98.  
  99.      Patch recognizes the following switches:
  100.  
  101.      -b   causes the next argument to be interpreted as the backup  extension,
  102.           to be used in place of ``.orig'' or ``~''.
  103.  
  104.      -B   causes the next argument to be interpreted as a prefix to the backup
  105.           file  name.  If this argument is specified any argument from -b will
  106.           be ignored.  This argument is an extension  to  Larry  Wall's  patch
  107.           v2.0.1.4, patchlevel 8, made by M. Greim (greim@sbsvax.uucp).
  108.  
  109.      -c   forces patch to interpret the patch file as a context diff.
  110.  
  111.      -d   causes patch to interpret the next argument as a directory,  and  cd
  112.           to it before doing anything else.
  113.  
  114.      -D   causes patch to use the "#ifdef...#endif" construct to mark changes.
  115.           The  argument  following will be used as the differentiating symbol.
  116.           Note that, unlike the C compiler, there must be a space between  the
  117.           -D and the argument.
  118.  
  119.      -e   forces patch to interpret the patch file as an ed script.
  120.  
  121.      -f   forces patch to assume that the user knows exactly what he or she is
  122.           doing,  and  to  not  ask  any  questions.   It  does  not  suppress
  123.           commentary, however.  Use -s for that.
  124.  
  125.      -F<number>
  126.           sets the maximum fuzz factor.  This switch only applies  to  context
  127.           diffs,  and  causes patch to ignore up to that many lines in looking
  128.           for places to install a  hunk.   Note  that  a  larger  fuzz  factor
  129.           increases the odds of a faulty patch.  The default fuzz factor is 2,
  130.           and it may not be set to more than the number of lines of context in
  131.           the context diff, ordinarily 3.
  132.  
  133.      -l   causes the pattern matching to be done loosely, in case the tabs and
  134.           spaces  have  been  munged  in  your  input  file.   Any sequence of
  135.           whitespace in the pattern line will match any sequence in the  input
  136.           file.  Normal characters must still match exactly.  Each line of the
  137.           context must still match a line in the input file.
  138.  
  139.      -n   forces patch to interpret the patch file as a normal diff.
  140.  
  141.      -N   causes patch to ignore  patches  that  it  thinks  are  reversed  or
  142.           already applied.  See also -R .
  143.  
  144.      -o   causes the next argument to be interpreted as the output file name.
  145.  
  146.      -p<number>
  147.           sets the pathname strip count, which controls how pathnames found in
  148.           the  patch  file  are  treated, in case the you keep your files in a
  149.           different directory than the person who sent  out  the  patch.   The
  150.           strip  count  specifies how many slashes are to be stripped from the
  151.           front of the pathname.  (Any intervening  directory  names  also  go
  152.           away.)  For example, supposing the filename in the patch file was
  153.  
  154.                /u/howard/src/blurfl/blurfl.c
  155.  
  156.           setting -p or -p0 gives the entire pathname unmodified, -p1 gives
  157.  
  158.                u/howard/src/blurfl/blurfl.c
  159.  
  160.           without the leading slash, -p4 gives
  161.  
  162.                blurfl/blurfl.c
  163.  
  164.           and not specifying -p at all just gives  you  "blurfl.c".   Whatever
  165.           you  end  up  with is looked for either in the current directory, or
  166.           the directory specified by the -d switch.
  167.  
  168.      -r   causes the next argument to be interpreted as the reject file name.
  169.  
  170.      -R   tells patch that this patch was created with the old and  new  files
  171.           swapped.   (Yes,  I'm  afraid  that  does happen occasionally, human
  172.           nature being what it is.)  Patch will  attempt  to  swap  each  hunk
  173.           around  before  applying  it.   Rejects will come out in the swapped
  174.           format.  The -R switch will not work with ed  diff  scripts  because
  175.           there   is   too  little  information  to  reconstruct  the  reverse
  176.           operation.
  177.  
  178.           If the first hunk of a patch fails, patch will reverse the  hunk  to
  179.           see  if it can be applied that way.  If it can, you will be asked if
  180.           you want to have the -R switch set.  If it  can't,  the  patch  will
  181.           continue to be applied normally.  (Note: this method cannot detect a
  182.           reversed patch if it is a normal diff and if the first command is an
  183.           append  (i.e.  it  should  have  been a delete) since appends always
  184.           succeed, due to the fact that a null context  will  match  anywhere.
  185.           Luckily,  most  patches add or change lines rather than delete them,
  186.           so most reversed normal diffs will begin with a delete,  which  will
  187.           fail, triggering the heuristic.)
  188.  
  189.      -s   makes patch do its work silently, unless an error occurs.
  190.  
  191.      -S   causes patch to ignore this patch from the patch file, but  continue
  192.           on looking for the next patch in the file.  Thus
  193.  
  194.                patch -S + -S + <patchfile
  195.  
  196.           will ignore the first and second of three patches.
  197.  
  198.      -u   forces patch to interpret the patch file as a unified  context  diff
  199.           (a unidiff).
  200.  
  201.      -v   causes patch to print out it's revision header and patch level.
  202.  
  203.      -x<number>
  204.           sets internal debugging flags, and is  of  interest  only  to  patch
  205.           patchers.
  206.  
  207. AUTHOR
  208.      Larry Wall <lwall@netlabs.com>
  209.  
  210. ENVIRONMENT
  211.      No environment variables are used by patch.
  212.  
  213. FILES
  214.      /tmp/patch*
  215.  
  216. SEE ALSO
  217.      diff(1)
  218.  
  219. NOTES FOR PATCH SENDERS
  220.      There are several things you should bear in mind if you are going  to  be
  221.      sending  out  patches.   First,  you  can  save  people a lot of grief by
  222.      keeping a patchlevel.h file which is patched to increment the patch level
  223.      as  the  first diff in the patch file you send out.  If you put a Prereq:
  224.      line in with the patch, it won't let them  apply  patches  out  of  order
  225.      without  some  warning.  Second, make sure you've specified the filenames
  226.      right, either in a context diff header, or with an Index: line.   If  you
  227.      are  patching something in a subdirectory, be sure to tell the patch user
  228.      to specify a -p switch as needed.   Third,  you  can  create  a  file  by
  229.      sending  out  a  diff  that  compares a null file to the file you want to
  230.      create.  This will only work if the file you want to create doesn't exist
  231.      already  in  the  target  directory.   Fourth,  take care not to send out
  232.      reversed patches, since it  makes  people  wonder  whether  they  already
  233.      applied the patch.  Fifth, while you may be able to get away with putting
  234.      582 diff listings into one file, it is probably wiser  to  group  related
  235.      patches into separate files in case something goes haywire.
  236.  
  237. DIAGNOSTICS
  238.      Too many to list here, but generally indicative that patch couldn't parse
  239.      your patch file.
  240.  
  241.      The message ``Hmm...'' indicates that there is unprocessed  text  in  the
  242.      patch  file  and  that  patch  is attempting to intuit whether there is a
  243.      patch in that text and, if so, what kind of patch it is.
  244.  
  245.      Patch will exit with a non-zero status if any reject files were  created.
  246.      When  applying  a  set of patches in a loop it behooves you to check this
  247.      exit status so you don't apply a later patch to a partially patched file.
  248.  
  249. CAVEATS
  250.      Patch cannot tell if the line numbers are off in an ed  script,  and  can
  251.      only  detect bad line numbers in a normal diff when it finds a ``change''
  252.      or a ``delete'' command.  A context diff using fuzz factor 3 may have the
  253.      same  problem.   Until  a  suitable  interactive  interface is added, you
  254.      should probably do a context diff in these cases to see  if  the  changes
  255.      made  sense.   Of  course,  compiling  without  errors  is  a pretty good
  256.      indication that the patch worked, but not always.
  257.  
  258.      Patch usually produces the correct results, even when it has to do a  lot
  259.      of guessing.  However, the results are guaranteed to be correct only when
  260.      the patch is applied to exactly the same version of  the  file  that  the
  261.      patch was generated from.
  262.  
  263. BUGS
  264.      Could be smarter about partial matches, excessively deviant  offsets  and
  265.      swapped code, but that would take an extra pass.
  266.  
  267.      If code has been duplicated (for instance with #ifdef OLDCODE  ...  #else
  268.      ...   #endif),  patch  is incapable of patching both versions, and, if it
  269.      works at all, will likely patch the wrong  one,  and  tell  you  that  it
  270.      succeeded to boot.
  271.  
  272.      If you apply a patch you've already applied, patch will  think  it  is  a
  273.      reversed patch, and offer to un-apply the patch.  This could be construed
  274.      as a feature.
  275.