Return to patch.1 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / patch

Annotation of 43BSDReno/contrib/patch/patch.1, revision 1.1

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

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