Annotation of src/usr.bin/patch/patch.1, Revision 1.16
1.16 ! millert 1: .\" $OpenBSD: patch.1,v 1.15 2003/07/30 16:45:44 millert Exp $
1.6 jmc 2: .\" Copyright 1986, Larry Wall
3: .\"
4: .\" Redistribution and use in source and binary forms, with or without
5: .\" modification, are permitted provided that the following condition
6: .\" is met:
7: .\" 1. Redistributions of source code must retain the above copyright
8: .\" notice, this condition and the following disclaimer.
1.7 deraadt 9: .\"
1.6 jmc 10: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
11: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
12: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
13: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
14: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
15: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
16: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
17: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
18: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
19: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
20: .\" SUCH DAMAGE.
21: .\"
1.9 jmc 22: .Dd July 23, 2003
23: .Dt PATCH 1
24: .Os
25: .Sh NAME
26: .Nm patch
27: .Nd apply a diff file to an original
28: .Sh SYNOPSIS
29: .Nm patch
30: .Op Cm options
31: .Op Ar origfile Op Ar patchfile
32: .Nm patch
33: .Pf \*(Lt Ar patchfile
34: .Sh DESCRIPTION
35: .Nm
1.1 deraadt 36: will take a patch file containing any of the four forms of difference
37: listing produced by the
1.9 jmc 38: .Xr diff 1
39: program and apply those differences to an original file,
40: producing a patched version.
1.1 deraadt 41: By default, the patched version is put in place of the original, with
1.9 jmc 42: the original file backed up to the same name with the extension
1.10 millert 43: .Qq .orig ,
1.9 jmc 44: or as specified by the
45: .Fl B ,
1.12 millert 46: .Fl V ,
1.9 jmc 47: or
1.12 millert 48: .Fl z
1.11 millert 49: options.
1.1 deraadt 50: The extension used for making backup files may also be specified in the
1.9 jmc 51: .Ev SIMPLE_BACKUP_SUFFIX
1.11 millert 52: environment variable, which is overridden by the options above.
1.9 jmc 53: .Pp
1.14 otto 54: If the backup file is linked to the original file,
1.9 jmc 55: .Nm
1.1 deraadt 56: creates a new backup file name by changing the first lowercase letter
1.9 jmc 57: in the last component of the file's name into uppercase.
58: If there are no more lowercase letters in the name,
59: it removes the first character from the name.
60: It repeats this process until it comes up with a
1.14 otto 61: backup file that does not already exist or is not linked to the original file.
1.9 jmc 62: .Pp
63: You may also specify where you want the output to go with the
64: .Fl o
1.11 millert 65: option; if that file already exists, it is backed up first.
1.9 jmc 66: .Pp
1.1 deraadt 67: If
1.9 jmc 68: .Ar patchfile
1.1 deraadt 69: is omitted, or is a hyphen, the patch will be read from standard input.
1.9 jmc 70: .Pp
71: Upon startup,
72: .Nm
73: will attempt to determine the type of the diff listing,
1.1 deraadt 74: unless over-ruled by a
1.9 jmc 75: .Fl c ,
76: .Fl e ,
77: .Fl n ,
1.1 deraadt 78: or
1.9 jmc 79: .Fl u
1.11 millert 80: option.
1.1 deraadt 81: Context diffs (old-style, new-style, and unified) and
82: normal diffs are applied by the
1.9 jmc 83: .Nm
1.1 deraadt 84: program itself, while ed diffs are simply fed to the
1.9 jmc 85: .Xr ed 1
1.1 deraadt 86: editor via a pipe.
1.9 jmc 87: .Pp
88: .Nm
1.1 deraadt 89: will try to skip any leading garbage, apply the diff,
90: and then skip any trailing garbage.
91: Thus you could feed an article or message containing a
92: diff listing to
1.9 jmc 93: .Nm patch ,
1.1 deraadt 94: and it should work.
95: If the entire diff is indented by a consistent amount,
96: this will be taken into account.
1.9 jmc 97: .Pp
1.1 deraadt 98: With context diffs, and to a lesser extent with normal diffs,
1.9 jmc 99: .Nm
1.1 deraadt 100: can detect when the line numbers mentioned in the patch are incorrect,
101: and will attempt to find the correct place to apply each hunk of the patch.
102: As a first guess, it takes the line number mentioned for the hunk, plus or
103: minus any offset used in applying the previous hunk.
104: If that is not the correct place,
1.9 jmc 105: .Nm
1.1 deraadt 106: will scan both forwards and backwards for a set of lines matching the context
107: given in the hunk.
108: First
1.9 jmc 109: .Nm
1.1 deraadt 110: looks for a place where all lines of the context match.
111: If no such place is found, and it's a context diff, and the maximum fuzz factor
112: is set to 1 or more, then another scan takes place ignoring the first and last
113: line of context.
114: If that fails, and the maximum fuzz factor is set to 2 or more,
115: the first two and last two lines of context are ignored,
116: and another scan is made.
1.9 jmc 117: .Pq The default maximum fuzz factor is 2.
118: .Pp
1.1 deraadt 119: If
1.9 jmc 120: .Nm
121: cannot find a place to install that hunk of the patch, it will put the hunk
122: out to a reject file, which normally is the name of the output file plus
1.10 millert 123: .Qq .rej .
1.1 deraadt 124: (Note that the rejected hunk will come out in context diff form whether the
125: input patch was a context diff or a normal diff.
126: If the input was a normal diff, many of the contexts will simply be null.)
127: The line numbers on the hunks in the reject file may be different than
128: in the patch file: they reflect the approximate location patch thinks the
129: failed hunks belong in the new file rather than the old one.
1.9 jmc 130: .Pp
1.1 deraadt 131: As each hunk is completed, you will be told whether the hunk succeeded or
132: failed, and which line (in the new file)
1.9 jmc 133: .Nm
1.1 deraadt 134: thought the hunk should go on.
1.9 jmc 135: If this is different from the line number specified in the diff,
136: you will be told the offset.
1.1 deraadt 137: A single large offset MAY be an indication that a hunk was installed in the
138: wrong place.
139: You will also be told if a fuzz factor was used to make the match, in which
140: case you should also be slightly suspicious.
1.9 jmc 141: .Pp
1.1 deraadt 142: If no original file is specified on the command line,
1.9 jmc 143: .Nm
1.1 deraadt 144: will try to figure out from the leading garbage what the name of the file
145: to edit is.
146: In the header of a context diff, the filename is found from lines beginning
1.9 jmc 147: with
148: .Qq ***
149: or
150: .Qq --- ,
151: with the shortest name of an existing file winning.
152: Only context diffs have lines like that, but if there is an
153: .Qq Index:
1.1 deraadt 154: line in the leading garbage,
1.9 jmc 155: .Nm
1.1 deraadt 156: will try to use the filename from that line.
157: The context diff header takes precedence over an Index line.
158: If no filename can be intuited from the leading garbage, you will be asked
159: for the name of the file to patch.
1.9 jmc 160: .Pp
1.1 deraadt 161: If the original file cannot be found or is read-only, but a suitable
162: SCCS or RCS file is handy,
1.9 jmc 163: .Nm
1.1 deraadt 164: will attempt to get or check out the file.
1.9 jmc 165: .Pp
166: Additionally, if the leading garbage contains a
167: .Qq Prereq:\ \&
168: line,
169: .Nm
1.1 deraadt 170: will take the first word from the prerequisites line (normally a version
171: number) and check the input file to see if that word can be found.
172: If not,
1.9 jmc 173: .Nm
1.1 deraadt 174: will ask for confirmation before proceeding.
1.9 jmc 175: .Pp
1.1 deraadt 176: The upshot of all this is that you should be able to say, while in a news
177: interface, the following:
1.9 jmc 178: .Pp
179: .Dl | patch -d /usr/src/local/blurfl
180: .Pp
1.1 deraadt 181: and patch a file in the blurfl directory directly from the article containing
182: the patch.
1.9 jmc 183: .Pp
1.1 deraadt 184: If the patch file contains more than one patch,
1.9 jmc 185: .Nm
1.1 deraadt 186: will try to apply each of them as if they came from separate patch files.
187: This means, among other things, that it is assumed that the name of the file
188: to patch must be determined for each diff listing,
189: and that the garbage before each diff listing will
190: be examined for interesting things such as filenames and revision level, as
191: mentioned previously.
1.9 jmc 192: .Pp
1.11 millert 193: The options are as follows:
1.9 jmc 194: .Bl -tag -width Ds
1.12 millert 195: .It Fl b , Fl Fl backup
196: Save a backup copy of the file before it is modified.
197: By default the original file is saved with a backup extension of
198: .Qq .orig
199: unless the file already has a numbered backup, in which case a numbered
200: backup is made.
201: This is equivalent to specifying
202: .Qo Fl V Ar existing Qc .
203: This option is currently the default but that will change in a future release.
1.9 jmc 204: .It Fl B , Fl Fl prefix
205: Causes the next argument to be interpreted as a prefix to the backup file
206: name.
207: If this argument is specified, any argument from
1.12 millert 208: .Fl z
1.9 jmc 209: will be ignored.
210: .It Fl c , Fl Fl context
211: Forces
212: .Nm
1.1 deraadt 213: to interpret the patch file as a context diff.
1.9 jmc 214: .It Fl C , Fl Fl check
215: Checks that the patch would apply cleanly, but does not modify anything.
216: .It Fl d , Fl Fl directory
217: Causes
218: .Nm
219: to interpret the next argument as a directory, and
220: .Xr cd 1
221: to it before doing anything else.
222: .It Fl D , Fl Fl ifdef
223: Causes
224: .Nm
225: to use the
226: .Qq #ifdef...#endif
227: construct to mark changes.
1.1 deraadt 228: The argument following will be used as the differentiating symbol.
229: Note that, unlike the C compiler, there must be a space between the
1.9 jmc 230: .Fl D
1.1 deraadt 231: and the argument.
1.9 jmc 232: .It Fl e , Fl Fl ed
233: Forces
234: .Nm
235: to interpret the patch file as an
236: .Xr ed 1
237: script.
238: .It Fl E , Fl Fl remove-empty-files
239: Causes
240: .Nm
1.1 deraadt 241: to remove output files that are empty after the patches have been applied.
1.9 jmc 242: .It Fl f , Fl Fl force
243: Forces
244: .Nm
1.1 deraadt 245: to assume that the user knows exactly what he or she is doing, and to not
1.9 jmc 246: ask any questions.
247: It assumes the following:
248: skip patches for which a file to patch can't be found;
249: patch files even though they have the wrong version for the
250: .Qq Prereq:
251: line in the patch;
252: and assume that patches are not reversed even if they look like they are.
1.1 deraadt 253: This option does not suppress commentary; use
1.9 jmc 254: .Fl s
1.1 deraadt 255: for that.
1.9 jmc 256: .It Fl t , Fl Fl batch
257: Similar to
258: .Fl f ,
1.1 deraadt 259: in that it suppresses questions, but makes some different assumptions:
1.9 jmc 260: skip patches for which a file to patch can't be found (the same as
261: .Fl f ) ;
262: skip patches for which the file has the wrong version for the
263: .Qq Prereq:
264: line in the patch;
265: and assume that patches are reversed if they look like they are.
266: .It Xo
267: .Fl F Ns Aq Ar number ,
268: .Fl Fl fuzz Aq Ar number
269: .Xc
270: Sets the maximum fuzz factor.
1.11 millert 271: This option only applies to context diffs, and causes
1.9 jmc 272: .Nm
1.1 deraadt 273: to ignore up to that many lines in looking for places to install a hunk.
274: Note that a larger fuzz factor increases the odds of a faulty patch.
275: The default fuzz factor is 2, and it may not be set to more than
276: the number of lines of context in the context diff, ordinarily 3.
1.15 millert 277: .It Fl i , Fl Fl input
278: Causes the next argument to be interpreted as the input file name
279: (i.e. a patchfile).
280: This option may be specified multiple times.
1.9 jmc 281: .It Fl l , Fl Fl ignore-whitespace
282: Causes the pattern matching to be done loosely, in case the tabs and
1.1 deraadt 283: spaces have been munged in your input file.
284: Any sequence of whitespace in the pattern line will match any sequence
285: in the input file.
286: Normal characters must still match exactly.
287: Each line of the context must still match a line in the input file.
1.9 jmc 288: .It Fl n , Fl Fl normal
289: Forces
290: .Nm
1.1 deraadt 291: to interpret the patch file as a normal diff.
1.9 jmc 292: .It Fl N , Fl Fl forward
293: Causes
294: .Nm
1.1 deraadt 295: to ignore patches that it thinks are reversed or already applied.
296: See also
1.9 jmc 297: .Fl R .
298: .It Fl o , Fl Fl output
299: Causes the next argument to be interpreted as the output file name.
300: .It Xo
301: .Fl p Ns Aq Ar number ,
302: .Fl Fl strip Aq Ar number
303: .Xc
304: Sets the pathname strip count,
305: which controls how pathnames found in the patch file are treated,
306: in case you keep your files in a different directory than the person who sent
1.1 deraadt 307: out the patch.
308: The strip count specifies how many slashes are to be stripped from
309: the front of the pathname.
310: (Any intervening directory names also go away.)
311: For example, supposing the filename in the patch file was
1.9 jmc 312: .Pa /u/howard/src/blurfl/blurfl.c :
313: .Pp
314: Setting
315: .Fl p Ns Ar 0
316: gives the entire pathname unmodified.
317: .Pp
318: .Fl p Ns Ar 1
1.1 deraadt 319: gives
1.9 jmc 320: .Pp
321: .D1 Pa u/howard/src/blurfl/blurfl.c
322: .Pp
323: without the leading slash.
324: .Pp
325: .Fl p Ns Ar 4
1.1 deraadt 326: gives
1.9 jmc 327: .Pp
328: .D1 Pa blurfl/blurfl.c
329: .Pp
330: Not specifying
331: .Fl p
332: at all just gives you
333: .Pa blurfl.c ,
334: unless all of the directories in the leading path
335: .Pq Pa u/howard/src/blurfl
336: exist and that path is relative,
1.1 deraadt 337: in which case you get the entire pathname unmodified.
338: Whatever you end up with is looked for either in the current directory,
339: or the directory specified by the
1.9 jmc 340: .Fl d
1.11 millert 341: option.
1.9 jmc 342: .It Fl r , Fl Fl reject-file
343: Causes the next argument to be interpreted as the reject file name.
344: .It Fl R , Fl Fl reverse
345: Tells
346: .Nm
1.1 deraadt 347: that this patch was created with the old and new files swapped.
348: (Yes, I'm afraid that does happen occasionally, human nature being what it
349: is.)
1.9 jmc 350: .Nm
1.1 deraadt 351: will attempt to swap each hunk around before applying it.
352: Rejects will come out in the swapped format.
353: The
1.9 jmc 354: .Fl R
1.11 millert 355: option will not work with ed diff scripts because there is too little
1.1 deraadt 356: information to reconstruct the reverse operation.
1.9 jmc 357: .Pp
1.1 deraadt 358: If the first hunk of a patch fails,
1.9 jmc 359: .Nm
1.1 deraadt 360: will reverse the hunk to see if it can be applied that way.
361: If it can, you will be asked if you want to have the
1.9 jmc 362: .Fl R
1.11 millert 363: option set.
1.1 deraadt 364: If it can't, the patch will continue to be applied normally.
365: (Note: this method cannot detect a reversed patch if it is a normal diff
366: and if the first command is an append (i.e. it should have been a delete)
367: since appends always succeed, due to the fact that a null context will match
368: anywhere.
369: Luckily, most patches add or change lines rather than delete them, so most
370: reversed normal diffs will begin with a delete, which will fail, triggering
371: the heuristic.)
1.9 jmc 372: .It Xo
373: .Fl s , Fl Fl quiet ,
374: .Fl Fl silent
375: .Xc
376: Makes
377: .Nm
1.1 deraadt 378: do its work silently, unless an error occurs.
1.9 jmc 379: .It Fl u , Fl Fl unified
380: Forces
381: .Nm
1.1 deraadt 382: to interpret the patch file as a unified context diff (a unidiff).
1.9 jmc 383: .It Fl v , Fl Fl version
384: Causes
385: .Nm
1.1 deraadt 386: to print out its revision header and patch level.
1.9 jmc 387: .It Fl V , Fl Fl version-control
388: Causes the next argument to be interpreted as a method for creating
389: backup file names.
390: The type of backups made can also be given in the
391: .Ev VERSION_CONTROL
1.1 deraadt 392: environment variable, which is overridden by this option.
393: The
1.9 jmc 394: .Fl B
1.1 deraadt 395: option overrides this option, causing the prefix to always be used for
396: making backup file names.
397: The value of the
1.9 jmc 398: .Ev VERSION_CONTROL
1.1 deraadt 399: environment variable and the argument to the
1.9 jmc 400: .Fl V
401: option are like the GNU Emacs
402: .Dq version-control
403: variable; they also recognize synonyms that are more descriptive.
404: The valid values are (unique abbreviations are accepted):
405: .Bl -tag -width Ds -offset indent
406: .It t , numbered
1.1 deraadt 407: Always make numbered backups.
1.9 jmc 408: .It nil , existing
409: Make numbered backups of files that already have them,
410: simple backups of the others.
411: .It never , simple
1.1 deraadt 412: Always make simple backups.
1.9 jmc 413: .El
414: .It Xo
415: .Fl x Ns Aq Ar number ,
416: .Fl Fl debug Aq Ar number
417: .Xc
418: Sets internal debugging flags, and is of interest only to
419: .Nm
1.1 deraadt 420: patchers.
1.12 millert 421: .It Fl z , Fl Fl suffix
422: Causes the next argument to be interpreted as the backup extension, to be
423: used in place of
424: .Qq .orig .
1.9 jmc 425: .El
426: .Sh NOTES FOR PATCH SENDERS
1.1 deraadt 427: There are several things you should bear in mind if you are going to
1.9 jmc 428: be sending out patches:
429: .Pp
430: First, you can save people a lot of grief by keeping a
431: .Pa patchlevel.h
432: file which is patched to increment the patch level as the first diff in the
1.1 deraadt 433: patch file you send out.
1.9 jmc 434: If you put a
435: .Qq Prereq:
436: line in with the patch, it won't let them apply
1.1 deraadt 437: patches out of order without some warning.
1.9 jmc 438: .Pp
1.1 deraadt 439: Second, make sure you've specified the filenames right, either in a
1.9 jmc 440: context diff header, or with an
441: .Qq Index:
442: line.
1.1 deraadt 443: If you are patching something in a subdirectory, be sure to tell the patch
1.4 aaron 444: user to specify a
1.9 jmc 445: .Fl p
1.11 millert 446: option as needed.
1.9 jmc 447: .Pp
1.1 deraadt 448: Third, you can create a file by sending out a diff that compares a
449: null file to the file you want to create.
450: This will only work if the file you want to create doesn't exist already in
451: the target directory.
1.9 jmc 452: .Pp
1.1 deraadt 453: Fourth, take care not to send out reversed patches, since it makes people wonder
454: whether they already applied the patch.
1.9 jmc 455: .Pp
1.1 deraadt 456: Fifth, while you may be able to get away with putting 582 diff listings into
457: one file, it is probably wiser to group related patches into separate files in
458: case something goes haywire.
1.9 jmc 459: .Sh ENVIRONMENT
460: .Bl -tag -width "SIMPLE_BACKUP_SUFFIX" -compact
461: .It Ev TMPDIR
462: Directory to put temporary files in; default is
463: .Pa /tmp .
464: .It Ev SIMPLE_BACKUP_SUFFIX
465: Extension to use for backup file names instead of
1.10 millert 466: .Qq .orig .
1.9 jmc 467: .It Ev VERSION_CONTROL
468: Selects when numbered backup files are made.
469: .El
470: .Sh FILES
471: .Bl -tag -width Ds
472: .It Pa $TMPDIR/patch*
473: .El
474: .Sh DIAGNOSTICS
1.1 deraadt 475: Too many to list here, but generally indicative that
1.9 jmc 476: .Nm
1.1 deraadt 477: couldn't parse your patch file.
1.9 jmc 478: .Pp
479: The message
480: .Qq Hmm...
481: indicates that there is unprocessed text in the patch file and that
482: .Nm
1.1 deraadt 483: is attempting to intuit whether there is a patch in that text and, if so,
484: what kind of patch it is.
1.9 jmc 485: .Pp
1.13 millert 486: The
1.9 jmc 487: .Nm
1.13 millert 488: utility exits with one of the following values:
489: .Pp
490: .Bl -tag -width Ds -compact -offset indent
491: .It \&0
492: Successful completion.
493: .It \&1
494: One or more lines were written to a reject file.
495: .It \*[Gt]\&1
496: An error occurred.
497: .El
498: .Pp
1.1 deraadt 499: When applying a set of patches in a loop it behooves you to check this
500: exit status so you don't apply a later patch to a partially patched file.
1.9 jmc 501: .Sh SEE ALSO
502: .Xr diff 1
503: .Sh AUTHORS
1.13 millert 504: .An Larry Wall
1.9 jmc 505: with many other contributors.
506: .Sh CAVEATS
507: .Nm
1.1 deraadt 508: cannot tell if the line numbers are off in an ed script, and can only detect
1.9 jmc 509: bad line numbers in a normal diff when it finds a
510: .Qq change
511: or a
512: .Qq delete
513: command.
1.1 deraadt 514: A context diff using fuzz factor 3 may have the same problem.
515: Until a suitable interactive interface is added, you should probably do
516: a context diff in these cases to see if the changes made sense.
517: Of course, compiling without errors is a pretty good indication that the patch
518: worked, but not always.
1.9 jmc 519: .Pp
520: .Nm
1.1 deraadt 521: usually produces the correct results, even when it has to do a lot of
522: guessing.
523: However, the results are guaranteed to be correct only when the patch is
524: applied to exactly the same version of the file that the patch was
525: generated from.
1.9 jmc 526: .Sh BUGS
527: Could be smarter about partial matches, excessively deviant offsets and
1.1 deraadt 528: swapped code, but that would take an extra pass.
1.9 jmc 529: .Pp
530: Check patch mode
531: .Pq Fl C
1.3 espie 532: will fail if you try to check several patches in succession that build on
1.9 jmc 533: each other.
534: The whole code of
535: .Nm
1.3 espie 536: would have to be restructured to keep temporary files around so that it can
537: handle this situation.
1.9 jmc 538: .Pp
1.1 deraadt 539: If code has been duplicated (for instance with #ifdef OLDCODE ... #else ...
540: #endif),
1.9 jmc 541: .Nm
1.1 deraadt 542: is incapable of patching both versions, and, if it works at all, will likely
543: patch the wrong one, and tell you that it succeeded to boot.
1.9 jmc 544: .Pp
1.1 deraadt 545: If you apply a patch you've already applied,
1.9 jmc 546: .Nm
1.1 deraadt 547: will think it is a reversed patch, and offer to un-apply the patch.
548: This could be construed as a feature.