home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / unix / doc / patch.man < prev    next >
Text File  |  1993-06-13  |  21KB  |  529 lines
  1.  
  2.  
  3.  
  4. PATCH(1)                                                 PATCH(1)
  5.  
  6.  
  7. NAME
  8.        patch - apply a diff file to an original
  9.  
  10. SYNOPSIS
  11.        patch [options] [origfile [patchfile]] [+ [options] [orig-
  12.        file]]...
  13.  
  14.        but usually just
  15.  
  16.        patch <patchfile
  17.  
  18. DESCRIPTION
  19.        Patch will take a patch file containing any  of  the  four
  20.        forms  of  difference listing produced by the diff program
  21.        and apply those differences to an original file, producing
  22.        a patched version.  By default, the patched version is put
  23.        in place of the original, with the original file backed up
  24.        to  the  same name with the extension ".orig" ("~" on sys-
  25.        tems that do not support long file names), or as specified
  26.        by  the  -b  (--suffix),  -B  (--prefix),  or  -V  (--ver-
  27.        sion-control) options.   The  extension  used  for  making
  28.        backup   files   may   also   be  specified  in  the  SIM-
  29.        PLE_BACKUP_SUFFIX environment variable, which is  overrid-
  30.        den by the above options.
  31.  
  32.        If  the  backup  file  already exists, patch creates a new
  33.        backup file name by changing the first lowercase letter in
  34.        the  last component of the file's name into uppercase.  If
  35.        there are no  more  lowercase  letters  in  the  name,  it
  36.        removes  the  first  character  from the name.  It repeats
  37.        this process until it comes up with  a  backup  file  that
  38.        does not already exist.
  39.  
  40.        You  may also specify where you want the output to go with
  41.        a -o (--output) option; if that file already exists, it is
  42.        backed up first.
  43.  
  44.        If patchfile is omitted, or is a hyphen, the patch will be
  45.        read from standard input.
  46.  
  47.        Upon startup, patch will attempt to determine the type  of
  48.        the  diff  listing, unless over-ruled by a -c (--context),
  49.        -e (--ed), -n (--normal), or -u (--unified) option.   Con-
  50.        text  diffs (old-style, new-style, and unified) and normal
  51.        diffs are applied by the patch program  itself,  while  ed
  52.        diffs are simply fed to the ed editor via a pipe.
  53.  
  54.        Patch  will  try  to  skip  any leading garbage, apply the
  55.        diff, and then skip any trailing garbage.  Thus you  could
  56.        feed  an  article  or message containing a diff listing to
  57.        patch, and it should work.  If the entire diff is indented
  58.        by a consistent amount, this will be taken into account.
  59.  
  60.        With  context  diffs,  and  to a lesser extent with normal
  61.  
  62.  
  63.  
  64.                               LOCAL                             1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PATCH(1)                                                 PATCH(1)
  71.  
  72.  
  73.        diffs, patch can detect when the line numbers mentioned in
  74.        the patch are incorrect, and will attempt to find the cor-
  75.        rect place to apply each hunk of the patch.   As  a  first
  76.        guess,  it  takes  the line number mentioned for the hunk,
  77.        plus or minus any offset used  in  applying  the  previous
  78.        hunk.   If  that is not the correct place, patch will scan
  79.        both forwards and backwards for a set  of  lines  matching
  80.        the  context  given  in the hunk.  First patch looks for a
  81.        place where all lines of the context match.   If  no  such
  82.        place  is  found, and it's a context diff, and the maximum
  83.        fuzz factor is set to 1 or more, then another  scan  takes
  84.        place  ignoring  the  first  and last line of context.  If
  85.        that fails, and the maximum fuzz factor is  set  to  2  or
  86.        more,  the  first  two  and  last two lines of context are
  87.        ignored, and another scan is made.  (The  default  maximum
  88.        fuzz  factor  is  2.)   If  patch  cannot  find a place to
  89.        install that hunk of the patch, it will put the  hunk  out
  90.        to a reject file, which normally is the name of the output
  91.        file plus ".rej" ("#" on systems that do not support  long
  92.        file  names).   (Note that the rejected hunk will come out
  93.        in context diff form whether the input patch was a context
  94.        diff  or  a  normal diff.  If the input was a normal diff,
  95.        many of the contexts will simply be null.)  The line  num-
  96.        bers on the hunks in the reject file may be different than
  97.        in the patch file: they reflect the  approximate  location
  98.        patch  thinks  the  failed  hunks  belong  in the new file
  99.        rather than the old one.
  100.  
  101.        As each hunk is completed, you will be  told  whether  the
  102.        hunk succeeded or failed, and which line (in the new file)
  103.        patch thought the hunk should go on.  If this is different
  104.        from  the  line  number  specified in the diff you will be
  105.        told the offset.  A single large offset MAY be an  indica-
  106.        tion  that  a  hunk was installed in the wrong place.  You
  107.        will also be told if a fuzz factor was used  to  make  the
  108.        match,  in  which  case you should also be slightly suspi-
  109.        cious.
  110.  
  111.        If no original file is  specified  on  the  command  line,
  112.        patch will try to figure out from the leading garbage what
  113.        the name of the file to edit is.  In the header of a  con-
  114.        text  diff,  the  file  name is found from lines beginning
  115.        with "***" or "---", with the shortest name of an existing
  116.        file  winning.   Only  context diffs have lines like that,
  117.        but if there is an "Index:" line in the  leading  garbage,
  118.        patch  will  try to use the file name from that line.  The
  119.        context diff header takes precedence over an  Index  line.
  120.        If  no file name can be intuited from the leading garbage,
  121.        you will be asked for the name of the file to patch.
  122.  
  123.        If the original file cannot be found or is read-only,  but
  124.        a  suitable  SCCS or RCS file is handy, patch will attempt
  125.        to get or check out the file.
  126.  
  127.  
  128.  
  129.  
  130.                               LOCAL                             2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PATCH(1)                                                 PATCH(1)
  137.  
  138.  
  139.        Additionally, if the leading garbage contains a "Prereq: "
  140.        line,  patch  will  take the first word from the prerequi-
  141.        sites line (normally a version number) and check the input
  142.        file to see if that word can be found.  If not, patch will
  143.        ask for confirmation before proceeding.
  144.  
  145.        The upshot of all this is that you should be able to  say,
  146.        while in a news interface, the following:
  147.  
  148.             | patch -d /usr/src/local/blurfl
  149.  
  150.        and patch a file in the blurfl directory directly from the
  151.        article containing the patch.
  152.  
  153.        If the patch file contains more than one patch, patch will
  154.        try  to  apply  each of them as if they came from separate
  155.        patch files.  This means, among other things, that  it  is
  156.        assumed  that the name of the file to patch must be deter-
  157.        mined for each diff listing, and that the  garbage  before
  158.        each  diff listing will be examined for interesting things
  159.        such as file names and revision level, as mentioned previ-
  160.        ously.   You  can  give options (and another original file
  161.        name) for the second and subsequent patches by  separating
  162.        the  corresponding argument lists by a '+'.  (The argument
  163.        list for a second or subsequent patch may  not  specify  a
  164.        new patch file, however.)
  165.  
  166.        Patch recognizes the following options:
  167.  
  168.        -b suff, --suffix=suff
  169.             causes  suff  to  be interpreted as the backup exten-
  170.             sion, to be used in place of ".orig" or "~".
  171.  
  172.        -B pref, --prefix=pref
  173.             causes pref to be interpreted  as  a  prefix  to  the
  174.             backup  file name. If this argument is specified, any
  175.             argument from -b will be ignored.
  176.  
  177.        -c, --context
  178.             forces patch to interpret the patch file as a context
  179.             diff.
  180.  
  181.        -d dir, --directory=dir
  182.             causes  patch to interpret dir as a directory, and cd
  183.             to it before doing anything else.
  184.  
  185.        -D sym, --ifdef=sym
  186.             causes patch to use the  "#ifdef...#endif"  construct
  187.             to mark changes.  sym will be used as the differenti-
  188.             ating symbol.
  189.  
  190.        -e, --ed
  191.             forces patch to interpret the patch  file  as  an  ed
  192.             script.
  193.  
  194.  
  195.  
  196.                               LOCAL                             3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PATCH(1)                                                 PATCH(1)
  203.  
  204.  
  205.        -E, --remove-empty-files
  206.             causes  patch  to  remove output files that are empty
  207.             after the patches have been applied.
  208.  
  209.        -f, --force
  210.             forces patch to assume that the  user  knows  exactly
  211.             what  he  or  she  is doing, and to not ask any ques-
  212.             tions.  It assumes the following:  skip  patches  for
  213.             which  a  file  to  patch can't be found; patch files
  214.             even though they  have  the  wrong  version  for  the
  215.             ``Prereq:''  line  in  the  patch;  and  assume  that
  216.             patches are not reversed even if they look like  they
  217.             are.   This  option does not suppress commentary; use
  218.             -s for that.
  219.  
  220.        -t, --batch
  221.             similar to -f, in that it suppresses  questions,  but
  222.             makes  some  different  assumptions: skip patches for
  223.             which a file to patch can't be  found  (the  same  as
  224.             -f);  skip  patches  for which the file has the wrong
  225.             version for the ``Prereq:'' line in  the  patch;  and
  226.             assume  that  patches  are reversed if they look like
  227.             they are.
  228.  
  229.        -F number, --fuzz=number
  230.             sets the  maximum  fuzz  factor.   This  option  only
  231.             applies  to context diffs, and causes patch to ignore
  232.             up to that  many  lines  in  looking  for  places  to
  233.             install  a  hunk.   Note  that  a  larger fuzz factor
  234.             increases the odds of a faulty  patch.   The  default
  235.             fuzz  factor is 2, and it may not be set to more than
  236.             the number of lines of context in the  context  diff,
  237.             ordinarily 3.
  238.  
  239.        -l, --ignore-whitespace
  240.             causes  the  pattern  matching to be done loosely, in
  241.             case the tabs and spaces have  been  munged  in  your
  242.             input  file.   Any sequence of whitespace in the pat-
  243.             tern line will match any sequence in the input  file.
  244.             Normal  characters  must  still  match exactly.  Each
  245.             line of the context must still match a  line  in  the
  246.             input file.
  247.  
  248.        -n, --normal
  249.             forces  patch to interpret the patch file as a normal
  250.             diff.
  251.  
  252.        -N, --forward
  253.             causes patch to ignore patches  that  it  thinks  are
  254.             reversed or already applied.  See also -R .
  255.  
  256.        -o file, --output=file
  257.             causes  file  to  be  interpreted  as the output file
  258.             name.
  259.  
  260.  
  261.  
  262.                               LOCAL                             4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. PATCH(1)                                                 PATCH(1)
  269.  
  270.  
  271.        -p[number], --strip[=number]
  272.             sets the pathname strip  count,  which  controls  how
  273.             pathnames  found  in  the  patch file are treated, in
  274.             case the you keep your files in a different directory
  275.             than  the  person  who sent out the patch.  The strip
  276.             count specifies how many slashes are to  be  stripped
  277.             from  the  front  of  the pathname.  (Any intervening
  278.             directory names also go away.)  For example,  suppos-
  279.             ing the file name in the patch file was
  280.  
  281.                  /u/howard/src/blurfl/blurfl.c
  282.  
  283.             setting  -p  or -p0 gives the entire pathname unmodi-
  284.             fied, -p1 gives
  285.  
  286.                  u/howard/src/blurfl/blurfl.c
  287.  
  288.             without the leading slash, -p4 gives
  289.  
  290.                  blurfl/blurfl.c
  291.  
  292.             and  not  specifying  -p  at  all  just   gives   you
  293.             "blurfl.c",  unless  all  of  the  directories in the
  294.             leading path  (u/howard/src/blurfl)  exist  and  that
  295.             path  is  relative,  in which case you get the entire
  296.             pathname unmodified.  Whatever you  end  up  with  is
  297.             looked  for  either  in the current directory, or the
  298.             directory specified by the -d option.
  299.  
  300.        -r file, --reject-file=file
  301.             causes file to be  interpreted  as  the  reject  file
  302.             name.
  303.  
  304.        -R, --reverse
  305.             tells  patch that this patch was created with the old
  306.             and new files swapped.  (Yes, I'm  afraid  that  does
  307.             happen  occasionally, human nature being what it is.)
  308.             Patch will attempt to swap each  hunk  around  before
  309.             applying  it.   Rejects  will come out in the swapped
  310.             format.  The -R option will not  work  with  ed  diff
  311.             scripts  because  there  is too little information to
  312.             reconstruct the reverse operation.
  313.  
  314.             If the first  hunk  of  a  patch  fails,  patch  will
  315.             reverse  the  hunk  to  see if it can be applied that
  316.             way.  If it can, you will be asked  if  you  want  to
  317.             have  the -R option set.  If it can't, the patch will
  318.             continue to be applied normally.  (Note: this  method
  319.             cannot detect a reversed patch if it is a normal diff
  320.             and if the first command is an append (i.e. it should
  321.             have been a delete) since appends always succeed, due
  322.             to the fact that a null context will match  anywhere.
  323.             Luckily, most patches add or change lines rather than
  324.             delete them, so most reversed normal diffs will begin
  325.  
  326.  
  327.  
  328.                               LOCAL                             5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. PATCH(1)                                                 PATCH(1)
  335.  
  336.  
  337.             with  a  delete,  which  will  fail,  triggering  the
  338.             heuristic.)
  339.  
  340.        -s, --silent, --quiet
  341.             makes patch do its work  silently,  unless  an  error
  342.             occurs.
  343.  
  344.        -S, --skip
  345.             causes  patch  to  ignore  this  patch from the patch
  346.             file, but continue on looking for the next  patch  in
  347.             the file.  Thus
  348.  
  349.                  patch -S + -S + <patchfile
  350.  
  351.             will ignore the first and second of three patches.
  352.  
  353.        -u, --unified
  354.             forces patch to interpret the patch file as a unified
  355.             context diff (a unidiff).
  356.  
  357.        -v, --version
  358.             causes patch to print out  its  revision  header  and
  359.             patch level.
  360.  
  361.        -V method, --version--control=method
  362.             causes  method to be interpreted as a method for cre-
  363.             ating backup file names.  The type  of  backups  made
  364.             can  also be given in the VERSION_CONTROL environment
  365.             variable, which is overridden by this option.  The -B
  366.             option  overrides  this option, causing the prefix to
  367.             always be used for making  backup  file  names.   The
  368.             value of the VERSION_CONTROL environment variable and
  369.             the argument to the -V option are like the GNU  Emacs
  370.             `version-control'  variable; they also recognize syn-
  371.             onyms that are more descriptive.   The  valid  values
  372.             are (unique abbreviations are accepted):
  373.  
  374.             `t' or `numbered'
  375.                    Always make numbered backups.
  376.  
  377.             `nil' or `existing'
  378.                    Make  numbered  backups  of files that already
  379.                    have them, simple backups of the others.  This
  380.                    is the default.
  381.  
  382.             `never' or `simple'
  383.                    Always make simple backups.
  384.  
  385.        -x number, --debug=number
  386.             sets  internal  debugging  flags,  and is of interest
  387.             only to patch patchers.
  388.  
  389. AUTHOR
  390.        Larry Wall <lwall@netlabs.com>
  391.  
  392.  
  393.  
  394.                               LOCAL                             6
  395.  
  396.  
  397.  
  398.  
  399.  
  400. PATCH(1)                                                 PATCH(1)
  401.  
  402.  
  403.        with many other contributors.
  404.  
  405. ENVIRONMENT
  406.        TMPDIR Directory to put temporary  files  in;  default  is
  407.               /tmp.
  408.  
  409.        SIMPLE_BACKUP_SUFFIX
  410.               Extension  to  use for backup file names instead of
  411.               ".orig" or "~".
  412.  
  413.        VERSION_CONTROL
  414.               Selects when numbered backup files are made.
  415.  
  416. FILES
  417.        $TMPDIR/patch*
  418.  
  419. SEE ALSO
  420.        diff(1)
  421.  
  422. NOTES FOR PATCH SENDERS
  423.        There are several things you should bear in  mind  if  you
  424.        are  going to be sending out patches.  First, you can save
  425.        people a lot of grief by keeping a patchlevel.h file which
  426.        is  patched to increment the patch level as the first diff
  427.        in the patch file you send out.  If you put a Prereq: line
  428.        in  with the patch, it won't let them apply patches out of
  429.        order without some  warning.   Second,  make  sure  you've
  430.        specified  the  file names right, either in a context diff
  431.        header, or with an Index: line.  If you are patching some-
  432.        thing in a subdirectory, be sure to tell the patch user to
  433.        specify a -p option as needed.  Third, you  can  create  a
  434.        file  by  sending  out a diff that compares a null file to
  435.        the file you want to create.  This will only work  if  the
  436.        file  you want to create doesn't exist already in the tar-
  437.        get directory.  Fourth, take care not to send out reversed
  438.        patches, since it makes people wonder whether they already
  439.        applied the patch.  Fifth, while you may be  able  to  get
  440.        away  with  putting 582 diff listings into one file, it is
  441.        probably wiser to  group  related  patches  into  separate
  442.        files in case something goes haywire.
  443.  
  444. DIAGNOSTICS
  445.        Too many to list here, but generally indicative that patch
  446.        couldn't parse your patch file.
  447.  
  448.        The message "Hmm..." indicates that there  is  unprocessed
  449.        text  in  the  patch  file and that patch is attempting to
  450.        intuit whether there is a patch in that text and,  if  so,
  451.        what kind of patch it is.
  452.  
  453.        Patch will exit with a non-zero status if any reject files
  454.        were created.  When applying a set of patches in a loop it
  455.        behooves  you to check this exit status so you don't apply
  456.        a later patch to a partially patched file.
  457.  
  458.  
  459.  
  460.                               LOCAL                             7
  461.  
  462.  
  463.  
  464.  
  465.  
  466. PATCH(1)                                                 PATCH(1)
  467.  
  468.  
  469. CAVEATS
  470.        Patch cannot tell if the line numbers are  off  in  an  ed
  471.        script,  and  can only detect bad line numbers in a normal
  472.        diff when it finds a "change" or a  "delete"  command.   A
  473.        context  diff  using fuzz factor 3 may have the same prob-
  474.        lem.  Until a suitable interactive interface is added, you
  475.        should probably do a context diff in these cases to see if
  476.        the changes made  sense.   Of  course,  compiling  without
  477.        errors  is a pretty good indication that the patch worked,
  478.        but not always.
  479.  
  480.        Patch usually produces the correct results, even  when  it
  481.        has  to  do  a  lot of guessing.  However, the results are
  482.        guaranteed to be correct only when the patch is applied to
  483.        exactly  the  same  version of the file that the patch was
  484.        generated from.
  485.  
  486. BUGS
  487.        Could  be  smarter  about  partial  matches,   excessively
  488.        deviant  offsets  and swapped code, but that would take an
  489.        extra pass.
  490.  
  491.        If code has been duplicated (for instance with #ifdef OLD-
  492.        CODE  ... #else ...  #endif), patch is incapable of patch-
  493.        ing both versions, and, if it works at  all,  will  likely
  494.        patch  the  wrong  one,  and tell you that it succeeded to
  495.        boot.
  496.  
  497.        If you apply a patch you've already  applied,  patch  will
  498.        think  it  is  a reversed patch, and offer to un-apply the
  499.        patch.  This could be construed as a feature.
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.                               LOCAL                             8
  527.  
  528.  
  529.