Return to patch.0 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / new / patch

Annotation of 43BSDTahoe/new/patch/patch.0, revision 1.1

1.1     ! root        1: 
        !             2: 
        !             3: 
        !             4: PATCH(1)           UNIX Programmer's Manual             PATCH(1)
        !             5: 
        !             6: 
        !             7: 
        !             8: NAME
        !             9:      patch - a program for applying a diff file to an original
        !            10: 
        !            11: SYNOPSIS
        !            12:      patch [options] orig patchfile [+ [options] orig]
        !            13: 
        !            14:      but usually just
        !            15: 
        !            16:      patch <patchfile
        !            17: 
        !            18: DESCRIPTION
        !            19:      _P_a_t_c_h will take a patch file containing any of the three
        !            20:      forms of difference listing produced by the _d_i_f_f program and
        !            21:      apply those differences to an original file, producing a
        !            22:      patched version.  By default, the patched version is put in
        !            23:      place of the original, with the original file backed up to
        !            24:      the same name with the extension ".orig", or as specified by
        !            25:      the -b switch.  You may also specify where you want the out-
        !            26:      put to go with a -o switch.  If _p_a_t_c_h_f_i_l_e is omitted, or is
        !            27:      a hyphen, the patch will be read from standard input.
        !            28: 
        !            29:      Upon startup, patch will attempt to determine the type of
        !            30:      the diff listing, unless over-ruled by a -c, -e, or -n
        !            31:      switch.  Context diffs and normal diffs are applied by the
        !            32:      _p_a_t_c_h program itself, while ed diffs are simply fed to the
        !            33:      _e_d editor via a pipe.
        !            34: 
        !            35:      _P_a_t_c_h will try to skip any leading garbage, apply the diff,
        !            36:      and then skip any trailing garbage.  Thus you could feed an
        !            37:      article or message containing a diff listing to _p_a_t_c_h, and
        !            38:      it should work.  If the entire diff is indented by a con-
        !            39:      sistent amount, this will be taken into account.
        !            40: 
        !            41:      With context diffs, and to a lesser extent with normal
        !            42:      diffs, _p_a_t_c_h can detect when the line numbers mentioned in
        !            43:      the patch are incorrect, and will attempt to find the
        !            44:      correct place to apply each hunk of the patch.  As a first
        !            45:      guess, it takes the line number mentioned for the hunk, plus
        !            46:      or minus any offset used in applying the previous hunk.  If
        !            47:      that is not the correct place, _p_a_t_c_h will scan both forwards
        !            48:      and backwards for a set of lines matching the context given
        !            49:      in the hunk.  First _p_a_t_c_h looks for a place where all lines
        !            50:      of the context match.  If no such place is found, and it's a
        !            51:      context diff, and the maximum fuzz factor is set to 1 or
        !            52:      more, then another scan takes place ignoring the first and
        !            53:      last line of context.  If that fails, and the maximum fuzz
        !            54:      factor is set to 2 or more, the first two and last two lines
        !            55:      of context are ignored, and another scan is made. (The
        !            56:      default maximum fuzz factor is 2.) If _p_a_t_c_h cannot find a
        !            57:      place to install that hunk of the patch, it will put the
        !            58:      hunk out to a reject file, which normally is the name of the
        !            59:      output file plus ".rej".  (Note that the rejected hunk will
        !            60: 
        !            61: 
        !            62: 
        !            63: Printed 2/18/88               LOCAL                            1
        !            64: 
        !            65: 
        !            66: 
        !            67: 
        !            68: 
        !            69: 
        !            70: PATCH(1)           UNIX Programmer's Manual             PATCH(1)
        !            71: 
        !            72: 
        !            73: 
        !            74:      come out in context diff form whether the input patch was a
        !            75:      context diff or a normal diff.  If the input was a normal
        !            76:      diff, many of the contexts will simply be null.) The line
        !            77:      numbers on the hunks in the reject file may be different
        !            78:      than in the patch file: they reflect the approximate loca-
        !            79:      tion patch thinks the failed hunks belong in the new file
        !            80:      rather than the old one.
        !            81: 
        !            82:      As each hunk is completed, you will be told whether the hunk
        !            83:      succeeded or failed, and which line (in the new file) _p_a_t_c_h
        !            84:      thought the hunk should go on.  If this is different from
        !            85:      the line number specified in the diff you will be told the
        !            86:      offset.  A single large offset MAY be an indication that a
        !            87:      hunk was installed in the wrong place.  You will also be
        !            88:      told if a fuzz factor was used to make the match, in which
        !            89:      case you should also be slightly suspicious.
        !            90: 
        !            91:      If no original file is specified on the command line, _p_a_t_c_h
        !            92:      will try to figure out from the leading garbage what the
        !            93:      name of the file to edit is.  In the header of a context
        !            94:      diff, the filename is found from lines beginning with "***"
        !            95:      or "---", with the shortest name of an existing file win-
        !            96:      ning.  Only context diffs have lines like that, but if there
        !            97:      is an "Index:" line in the leading garbage, _p_a_t_c_h will try
        !            98:      to use the filename from that line.  The context diff header
        !            99:      takes precedence over an Index line.  If no filename can be
        !           100:      intuited from the leading garbage, you will be asked for the
        !           101:      name of the file to patch.
        !           102: 
        !           103:      (If the original file cannot be found, but a suitable SCCS
        !           104:      or RCS file is handy, _p_a_t_c_h will attempt to get or check out
        !           105:      the file.)
        !           106: 
        !           107:      Additionally, if the leading garbage contains a "Prereq: "
        !           108:      line, _p_a_t_c_h will take the first word from the prerequisites
        !           109:      line (normally a version number) and check the input file to
        !           110:      see if that word can be found.  If not, _p_a_t_c_h will ask for
        !           111:      confirmation before proceeding.
        !           112: 
        !           113:      The upshot of all this is that you should be able to say,
        !           114:      while in a news interface, the following:
        !           115: 
        !           116:          | patch -d /usr/src/local/blurfl
        !           117: 
        !           118:      and patch a file in the blurfl directory directly from the
        !           119:      article containing the patch.
        !           120: 
        !           121:      If the patch file contains more than one patch, _p_a_t_c_h will
        !           122:      try to apply each of them as if they came from separate
        !           123:      patch files.  This means, among other things, that it is
        !           124:      assumed that the name of the file to patch must be deter-
        !           125:      mined for each diff listing, and that the garbage before
        !           126: 
        !           127: 
        !           128: 
        !           129: Printed 2/18/88               LOCAL                            2
        !           130: 
        !           131: 
        !           132: 
        !           133: 
        !           134: 
        !           135: 
        !           136: PATCH(1)           UNIX Programmer's Manual             PATCH(1)
        !           137: 
        !           138: 
        !           139: 
        !           140:      each diff listing will be examined for interesting things
        !           141:      such as filenames and revision level, as mentioned previ-
        !           142:      ously.  You can give switches (and another original file
        !           143:      name) for the second and subsequent patches by separating
        !           144:      the corresponding argument lists by a '+'.  (The argument
        !           145:      list for a second or subsequent patch may not specify a new
        !           146:      patch file, however.)
        !           147: 
        !           148:      _P_a_t_c_h recognizes the following switches:
        !           149: 
        !           150:      -b   causes the next argument to be interpreted as the
        !           151:          backup extension, to be used in place of ".orig".
        !           152: 
        !           153:      -c   forces _p_a_t_c_h to interpret the patch file as a context
        !           154:          diff.
        !           155: 
        !           156:      -d   causes _p_a_t_c_h to interpret the next argument as a direc-
        !           157:          tory, and cd to it before doing anything else.
        !           158: 
        !           159:      -D   causes _p_a_t_c_h to use the "#ifdef...#endif" construct to
        !           160:          mark changes.  The argument following will be used as
        !           161:          the differentiating symbol.  Note that, unlike the C
        !           162:          compiler, there must be a space between the -D and the
        !           163:          argument.
        !           164: 
        !           165:      -e   forces _p_a_t_c_h to interpret the patch file as an ed
        !           166:          script.
        !           167: 
        !           168:      -f   forces _p_a_t_c_h to assume that the user knows exactly what
        !           169:          he or she is doing, and to not ask any questions.  It
        !           170:          does not suppress commentary, however.  Use -s for
        !           171:          that.
        !           172: 
        !           173:      -F<number>
        !           174:          sets the maximum fuzz factor.  This switch only applied
        !           175:          to context diffs, and causes _p_a_t_c_h to ignore up to that
        !           176:          many lines in looking for places to install a hunk.
        !           177:          Note that a larger fuzz factor increases the odds of a
        !           178:          faulty patch.  The default fuzz factor is 2, and it may
        !           179:          not be set to more than the number of lines of context
        !           180:          in the context diff, ordinarily 3.
        !           181: 
        !           182:      -l   causes the pattern matching to be done loosely, in case
        !           183:          the tabs and spaces have been munged in your input
        !           184:          file.  Any sequence of whitespace in the pattern line
        !           185:          will match any sequence in the input file.  Normal
        !           186:          characters must still match exactly.  Each line of the
        !           187:          context must still match a line in the input file.
        !           188: 
        !           189:      -n   forces _p_a_t_c_h to interpret the patch file as a normal
        !           190:          diff.
        !           191: 
        !           192: 
        !           193: 
        !           194: 
        !           195: Printed 2/18/88               LOCAL                            3
        !           196: 
        !           197: 
        !           198: 
        !           199: 
        !           200: 
        !           201: 
        !           202: PATCH(1)           UNIX Programmer's Manual             PATCH(1)
        !           203: 
        !           204: 
        !           205: 
        !           206:      -N   causes _p_a_t_c_h to ignore patches that it thinks are
        !           207:          reversed or already applied.  See also -R .
        !           208: 
        !           209:      -o   causes the next argument to be interpreted as the out-
        !           210:          put file name.
        !           211: 
        !           212:      -p<number>
        !           213:          sets the pathname strip count, which controls how path-
        !           214:          names found in the patch file are treated, in case the
        !           215:          you keep your files in a different directory than the
        !           216:          person who sent out the patch.  The strip count speci-
        !           217:          fies how many backslashes are to be stripped from the
        !           218:          front of the pathname.  (Any intervening directory
        !           219:          names also go away.) For example, supposing the
        !           220:          filename in the patch file was
        !           221: 
        !           222:               /u/howard/src/blurfl/blurfl.c
        !           223: 
        !           224:          setting -p or -p0 gives the entire pathname unmodified,
        !           225:          -p1 gives
        !           226: 
        !           227:               u/howard/src/blurfl/blurfl.c
        !           228: 
        !           229:          without the leading slash, -p4 gives
        !           230: 
        !           231:               blurfl/blurfl.c
        !           232: 
        !           233:          and not specifying -p at all just gives you "blurfl.c".
        !           234:          Whatever you end up with is looked for either in the
        !           235:          current directory, or the directory specified by the -d
        !           236:          switch.
        !           237: 
        !           238:      -r   causes the next argument to be interpreted as the
        !           239:          reject file name.
        !           240: 
        !           241:      -R   tells _p_a_t_c_h that this patch was created with the old
        !           242:          and new files swapped.  (Yes, I'm afraid that does hap-
        !           243:          pen occasionally, human nature being what it is.) _P_a_t_c_h
        !           244:          will attempt to swap each hunk around before applying
        !           245:          it.  Rejects will come out in the swapped format.  The
        !           246:          -R switch will not work with ed diff scripts because
        !           247:          there is too little information to reconstruct the
        !           248:          reverse operation.
        !           249: 
        !           250:          If the first hunk of a patch fails, _p_a_t_c_h will reverse
        !           251:          the hunk to see if it can be applied that way.  If it
        !           252:          can, you will be asked if you want to have the -R
        !           253:          switch set.  If it can't, the patch will continue to be
        !           254:          applied normally.  (Note: this method cannot detect a
        !           255:          reversed patch if it is a normal diff and if the first
        !           256:          command is an append (i.e. it should have been a
        !           257:          delete) since appends always succeed, due to the fact
        !           258: 
        !           259: 
        !           260: 
        !           261: Printed 2/18/88               LOCAL                            4
        !           262: 
        !           263: 
        !           264: 
        !           265: 
        !           266: 
        !           267: 
        !           268: PATCH(1)           UNIX Programmer's Manual             PATCH(1)
        !           269: 
        !           270: 
        !           271: 
        !           272:          that a null context will match anywhere.  Luckily, most
        !           273:          patches add or change lines rather than delete them, so
        !           274:          most reversed normal diffs will begin with a delete,
        !           275:          which will fail, triggering the heuristic.)
        !           276: 
        !           277:      -s   makes _p_a_t_c_h do its work silently, unless an error
        !           278:          occurs.
        !           279: 
        !           280:      -S   causes _p_a_t_c_h to ignore this patch from the patch file,
        !           281:          but continue on looking for the next patch in the file.
        !           282:          Thus
        !           283: 
        !           284:               patch -S + -S + <patchfile
        !           285: 
        !           286:          will ignore the first and second of three patches.
        !           287: 
        !           288:      -v   causes _p_a_t_c_h to print out it's revision header and
        !           289:          patch level.
        !           290: 
        !           291:      -x<number>
        !           292:          sets internal debugging flags, and is of interest only
        !           293:          to _p_a_t_c_h patchers.
        !           294: 
        !           295: ENVIRONMENT
        !           296:      No environment variables are used by _p_a_t_c_h.
        !           297: 
        !           298: FILES
        !           299:      /tmp/patch*
        !           300: 
        !           301: SEE ALSO
        !           302:      diff(1)
        !           303: 
        !           304: NOTES FOR PATCH SENDERS
        !           305:      There are several things you should bear in mind if you are
        !           306:      going to be sending out patches.  First, you can save people
        !           307:      a lot of grief by keeping a patchlevel.h file which is
        !           308:      patched to increment the patch level as the first diff in
        !           309:      the patch file you send out.  If you put a Prereq: line in
        !           310:      with the patch, it won't let them apply patches out of order
        !           311:      without some warning.  Second, make sure you've specified
        !           312:      the filenames right, either in a context diff header, or
        !           313:      with an Index: line.  If you are patching something in a
        !           314:      subdirectory, be sure to tell the patch user to specify a -p
        !           315:      switch as needed. Third, you can create a file by sending
        !           316:      out a diff that compares a null file to the file you want to
        !           317:      create.  This will only work if the file you want to create
        !           318:      doesn't exist already in the target directory.  Fourth, take
        !           319:      care not to send out reversed patches, since it makes people
        !           320:      wonder whether they already applied the patch.  Fifth, while
        !           321:      you may be able to get away with putting 582 diff listings
        !           322:      into one file, it is probably wiser to group related patches
        !           323:      into separate files in case something goes haywire.
        !           324: 
        !           325: 
        !           326: 
        !           327: Printed 2/18/88               LOCAL                            5
        !           328: 
        !           329: 
        !           330: 
        !           331: 
        !           332: 
        !           333: 
        !           334: PATCH(1)           UNIX Programmer's Manual             PATCH(1)
        !           335: 
        !           336: 
        !           337: 
        !           338: DIAGNOSTICS
        !           339:      Too many to list here, but generally indicative that _p_a_t_c_h
        !           340:      couldn't parse your patch file.
        !           341: 
        !           342:      The message "Hmm..." indicates that there is unprocessed
        !           343:      text in the patch file and that _p_a_t_c_h is attempting to
        !           344:      intuit whether there is a patch in that text and, if so,
        !           345:      what kind of patch it is.
        !           346: 
        !           347: CAVEATS
        !           348:      _P_a_t_c_h cannot tell if the line numbers are off in an ed
        !           349:      script, and can only detect bad line numbers in a normal
        !           350:      diff when it finds a "change" or a "delete" command.  A con-
        !           351:      text diff using fuzz factor 3 may have the same problem.
        !           352:      Until a suitable interactive interface is added, you should
        !           353:      probably do a context diff in these cases to see if the
        !           354:      changes made sense.  Of course, compiling without errors is
        !           355:      a pretty good indication that the patch worked, but not
        !           356:      always.
        !           357: 
        !           358:      _P_a_t_c_h usually produces the correct results, even when it has
        !           359:      to do a lot of guessing.  However, the results are
        !           360:      guaranteed to be correct only when the patch is applied to
        !           361:      exactly the same version of the file that the patch was gen-
        !           362:      erated from.
        !           363: 
        !           364: BUGS
        !           365:      Could be smarter about partial matches, excessively deviant
        !           366:      offsets and swapped code, but that would take an extra pass.
        !           367: 
        !           368:      If code has been duplicated (for instance with #ifdef OLD-
        !           369:      CODE ... #else ...  #endif), _p_a_t_c_h is incapable of patching
        !           370:      both versions, and, if it works at all, will likely patch
        !           371:      the wrong one, and tell you that it succeeded to boot.
        !           372: 
        !           373:      If you apply a patch you've already applied, _p_a_t_c_h will
        !           374:      think it is a reversed patch, and offer to un-apply the
        !           375:      patch.  This could be construed as a feature.
        !           376: 
        !           377: 
        !           378: 
        !           379: 
        !           380: 
        !           381: 
        !           382: 
        !           383: 
        !           384: 
        !           385: 
        !           386: 
        !           387: 
        !           388: 
        !           389: 
        !           390: 
        !           391: 
        !           392: 
        !           393: Printed 2/18/88               LOCAL                            6
        !           394: 
        !           395: 
        !           396: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.