home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / gnu / patch-2.1-bin.lha / man / cat1 / patch.0
Text File  |  1993-12-07  |  22KB  |  529 lines
  1.  
  2.  
  3.  
  4. PATCH(1)                                                 PATCH(1)
  5.  
  6.  
  7. NNAAMMEE
  8.        patch - apply a diff file to an original
  9.  
  10. SSYYNNOOPPSSIISS
  11.        ppaattcchh [options] [origfile [patchfile]] [+ [options] [orig-
  12.        file]]...
  13.  
  14.        but usually just
  15.  
  16.        ppaattcchh <patchfile
  17.  
  18. DDEESSCCRRIIPPTTIIOONN
  19.        _P_a_t_c_h will take a patch file containing any  of  the  four
  20.        forms  of  difference listing produced by the _d_i_f_f 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  --bb  (----ssuuffffiixx),  --BB  (----pprreeffiixx),  or  --VV  (----vveerr--
  27.        ssiioonn--ccoonnttrrooll) options.   The  extension  used  for  making
  28.        backup   files   may   also   be  specified  in  the  SSIIMM--
  29.        PPLLEE__BBAACCKKUUPP__SSUUFFFFIIXX environment variable, which is  overrid-
  30.        den by the above options.
  31.  
  32.        If  the  backup  file  already exists, ppaattcchh 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 --oo (----oouuttppuutt) option; if that file already exists, it is
  42.        backed up first.
  43.  
  44.        If _p_a_t_c_h_f_i_l_e 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 --cc (----ccoonntteexxtt),
  49.        --ee (----eedd), --nn (----nnoorrmmaall), or --uu (----uunniiffiieedd) option.   Con-
  50.        text  diffs (old-style, new-style, and unified) and normal
  51.        diffs are applied by the _p_a_t_c_h program  itself,  while  _e_d
  52.        diffs are simply fed to the _e_d editor via a pipe.
  53.  
  54.        _P_a_t_c_h  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.        _p_a_t_c_h, 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, _p_a_t_c_h 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, _p_a_t_c_h will scan
  79.        both forwards and backwards for a set  of  lines  matching
  80.        the  context  given  in the hunk.  First _p_a_t_c_h 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  _p_a_t_c_h  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.        _p_a_t_c_h 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.        _p_a_t_c_h 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.        _p_a_t_c_h  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, _p_a_t_c_h 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,  _p_a_t_c_h  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, _p_a_t_c_h 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, _p_a_t_c_h 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.        _P_a_t_c_h recognizes the following options:
  167.  
  168.        --bb ssuuffff,, ----ssuuffffiixx==ssuuffff
  169.             causes  ssuuffff  to  be interpreted as the backup exten-
  170.             sion, to be used in place of ".orig" or "~".
  171.  
  172.        --BB pprreeff,, ----pprreeffiixx==pprreeff
  173.             causes pprreeff to be interpreted  as  a  prefix  to  the
  174.             backup  file name. If this argument is specified, any
  175.             argument from --bb will be ignored.
  176.  
  177.        --cc,, ----ccoonntteexxtt
  178.             forces _p_a_t_c_h to interpret the patch file as a context
  179.             diff.
  180.  
  181.        --dd ddiirr,, ----ddiirreeccttoorryy==ddiirr
  182.             causes  _p_a_t_c_h to interpret ddiirr as a directory, and cd
  183.             to it before doing anything else.
  184.  
  185.        --DD ssyymm,, ----iiffddeeff==ssyymm
  186.             causes _p_a_t_c_h to use the  "#ifdef...#endif"  construct
  187.             to mark changes.  ssyymm will be used as the differenti-
  188.             ating symbol.
  189.  
  190.        --ee,, ----eedd
  191.             forces _p_a_t_c_h to interpret the patch  file  as  an  _e_d
  192.             script.
  193.  
  194.  
  195.  
  196.                               LOCAL                             3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PATCH(1)                                                 PATCH(1)
  203.  
  204.  
  205.        --EE,, ----rreemmoovvee--eemmppttyy--ffiilleess
  206.             causes  _p_a_t_c_h  to  remove output files that are empty
  207.             after the patches have been applied.
  208.  
  209.        --ff,, ----ffoorrccee
  210.             forces _p_a_t_c_h 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.             --ss for that.
  219.  
  220.        --tt,, ----bbaattcchh
  221.             similar to --ff, 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.             --ff);  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.        --FF nnuummbbeerr,, ----ffuuzzzz==nnuummbbeerr
  230.             sets the  maximum  fuzz  factor.   This  option  only
  231.             applies  to context diffs, and causes _p_a_t_c_h 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.        --ll,, ----iiggnnoorree--wwhhiitteessppaaccee
  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.        --nn,, ----nnoorrmmaall
  249.             forces  _p_a_t_c_h to interpret the patch file as a normal
  250.             diff.
  251.  
  252.        --NN,, ----ffoorrwwaarrdd
  253.             causes _p_a_t_c_h to ignore patches  that  it  thinks  are
  254.             reversed or already applied.  See also --RR ..
  255.  
  256.        --oo ffiillee,, ----oouuttppuutt==ffiillee
  257.             causes  ffiillee  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.        --pp[[nnuummbbeerr]],, ----ssttrriipp[[==nnuummbbeerr]]
  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  --pp  or --pp00 gives the entire pathname unmodi-
  284.             fied, --pp11 gives
  285.  
  286.                  u/howard/src/blurfl/blurfl.c
  287.  
  288.             without the leading slash, --pp44 gives
  289.  
  290.                  blurfl/blurfl.c
  291.  
  292.             and  not  specifying  --pp  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 --dd option.
  299.  
  300.        --rr ffiillee,, ----rreejjeecctt--ffiillee==ffiillee
  301.             causes ffiillee to be  interpreted  as  the  reject  file
  302.             name.
  303.  
  304.        --RR,, ----rreevveerrssee
  305.             tells  _p_a_t_c_h 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.             _P_a_t_c_h will attempt to swap each  hunk  around  before
  309.             applying  it.   Rejects  will come out in the swapped
  310.             format.  The --RR option will not  work  with  _e_d  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,  _p_a_t_c_h  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 --RR 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.        --ss,, ----ssiilleenntt,, ----qquuiieett
  341.             makes _p_a_t_c_h do its work  silently,  unless  an  error
  342.             occurs.
  343.  
  344.        --SS,, ----sskkiipp
  345.             causes  _p_a_t_c_h  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.        --uu,, ----uunniiffiieedd
  354.             forces _p_a_t_c_h to interpret the patch file as a unified
  355.             context diff (a unidiff).
  356.  
  357.        --vv,, ----vveerrssiioonn
  358.             causes _p_a_t_c_h to print out  its  revision  header  and
  359.             patch level.
  360.  
  361.        --VV mmeetthhoodd,, ----vveerrssiioonn----ccoonnttrrooll==mmeetthhoodd
  362.             causes  mmeetthhoodd 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 VVEERRSSIIOONN__CCOONNTTRROOLL environment
  365.             variable, which is overridden by this option.  The --BB
  366.             option  overrides  this option, causing the prefix to
  367.             always be used for making  backup  file  names.   The
  368.             value of the VVEERRSSIIOONN__CCOONNTTRROOLL environment variable and
  369.             the argument to the --VV 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.        --xx nnuummbbeerr,, ----ddeebbuugg==nnuummbbeerr
  386.             sets  internal  debugging  flags,  and is of interest
  387.             only to _p_a_t_c_h patchers.
  388.  
  389. AAUUTTHHOORR
  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. EENNVVIIRROONNMMEENNTT
  406.        TTMMPPDDIIRR Directory to put temporary  files  in;  default  is
  407.               /tmp.
  408.  
  409.        SSIIMMPPLLEE__BBAACCKKUUPP__SSUUFFFFIIXX
  410.               Extension  to  use for backup file names instead of
  411.               ".orig" or "~".
  412.  
  413.        VVEERRSSIIOONN__CCOONNTTRROOLL
  414.               Selects when numbered backup files are made.
  415.  
  416. FFIILLEESS
  417.        $TMPDIR/patch*
  418.  
  419. SSEEEE AALLSSOO
  420.        diff(1)
  421.  
  422. NNOOTTEESS FFOORR PPAATTCCHH SSEENNDDEERRSS
  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 --pp 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. DDIIAAGGNNOOSSTTIICCSS
  445.        Too many to list here, but generally indicative that _p_a_t_c_h
  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 _p_a_t_c_h 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.        _P_a_t_c_h 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. CCAAVVEEAATTSS
  470.        _P_a_t_c_h cannot tell if the line numbers are  off  in  an  _e_d
  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.        _P_a_t_c_h 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. BBUUGGSS
  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), _p_a_t_c_h 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,  _p_a_t_c_h  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.