Annotation of src/usr.bin/patch/patch.1, Revision 1.30
1.30 ! millert 1: .\" $OpenBSD: patch.1,v 1.29 2015/03/13 19:58:41 jmc 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.30 ! millert 22: .Dd $Mdocdate: March 13 2015 $
1.9 jmc 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
1.18 sobrado 30: .Bk -words
31: .Op Fl bCcEeflNnRstuv
32: .Op Fl B Ar backup-prefix
33: .Op Fl D Ar symbol
34: .Op Fl d Ar directory
35: .Op Fl F Ar max-fuzz
36: .Op Fl i Ar patchfile
37: .Op Fl o Ar out-file
38: .Op Fl p Ar strip-count
39: .Op Fl r Ar rej-name
40: .Op Fl V Cm t | nil | never
41: .Op Fl x Ar number
42: .Op Fl z Ar backup-ext
43: .Op Fl Fl posix
1.9 jmc 44: .Op Ar origfile Op Ar patchfile
1.18 sobrado 45: .Ek
1.9 jmc 46: .Nm patch
47: .Pf \*(Lt Ar patchfile
48: .Sh DESCRIPTION
49: .Nm
1.1 deraadt 50: will take a patch file containing any of the four forms of difference
51: listing produced by the
1.9 jmc 52: .Xr diff 1
53: program and apply those differences to an original file,
54: producing a patched version.
1.1 deraadt 55: If
1.9 jmc 56: .Ar patchfile
1.17 millert 57: is omitted, or is a hyphen, the patch will be read from the standard input.
1.9 jmc 58: .Pp
59: .Nm
1.23 jmc 60: will attempt to determine the type of the diff listing, unless overruled by a
1.9 jmc 61: .Fl c ,
62: .Fl e ,
63: .Fl n ,
1.1 deraadt 64: or
1.9 jmc 65: .Fl u
1.11 millert 66: option.
1.1 deraadt 67: Context diffs (old-style, new-style, and unified) and
1.17 millert 68: normal diffs are applied directly by the
1.9 jmc 69: .Nm
1.17 millert 70: program itself, whereas ed diffs are simply fed to the
1.9 jmc 71: .Xr ed 1
1.1 deraadt 72: editor via a pipe.
1.9 jmc 73: .Pp
1.17 millert 74: If the
75: .Ar patchfile
76: contains more than one patch,
1.9 jmc 77: .Nm
1.1 deraadt 78: will try to apply each of them as if they came from separate patch files.
79: This means, among other things, that it is assumed that the name of the file
1.17 millert 80: to patch must be determined for each diff listing, and that the garbage before
81: each diff listing will be examined for interesting things such as file names
82: and revision level (see the section on
83: .Sx Filename Determination
84: below).
1.9 jmc 85: .Pp
1.11 millert 86: The options are as follows:
1.9 jmc 87: .Bl -tag -width Ds
1.18 sobrado 88: .It Xo
89: .Fl B Ar backup-prefix ,
90: .Fl Fl prefix Ar backup-prefix
91: .Xc
92: Causes the next argument to be interpreted as a prefix to the backup file
93: name.
94: If this argument is specified, any argument to
95: .Fl z
96: will be ignored.
1.12 millert 97: .It Fl b , Fl Fl backup
98: Save a backup copy of the file before it is modified.
99: By default the original file is saved with a backup extension of
100: .Qq .orig
101: unless the file already has a numbered backup, in which case a numbered
102: backup is made.
103: This is equivalent to specifying
1.18 sobrado 104: .Qo Fl V Cm existing Qc .
1.22 jmc 105: This option is currently the default, unless
106: .Fl -posix
107: is specified.
1.18 sobrado 108: .It Fl C , Fl Fl check
109: Checks that the patch would apply cleanly, but does not modify anything.
1.9 jmc 110: .It Fl c , Fl Fl context
111: Forces
112: .Nm
1.1 deraadt 113: to interpret the patch file as a context diff.
1.18 sobrado 114: .It Xo
115: .Fl D Ar symbol ,
116: .Fl Fl ifdef Ar symbol
117: .Xc
1.9 jmc 118: Causes
119: .Nm
120: to use the
121: .Qq #ifdef...#endif
122: construct to mark changes.
1.1 deraadt 123: The argument following will be used as the differentiating symbol.
124: Note that, unlike the C compiler, there must be a space between the
1.9 jmc 125: .Fl D
1.1 deraadt 126: and the argument.
1.18 sobrado 127: .It Xo
128: .Fl d Ar directory ,
129: .Fl Fl directory Ar directory
130: .Xc
131: Causes
132: .Nm
1.21 jmc 133: to interpret the next argument as a directory,
134: and change working directory to it before doing anything else.
1.18 sobrado 135: .It Fl E , Fl Fl remove-empty-files
136: Causes
137: .Nm
138: to remove output files that are empty after the patches have been applied.
139: This option is useful when applying patches that create or remove files.
1.9 jmc 140: .It Fl e , Fl Fl ed
141: Forces
142: .Nm
143: to interpret the patch file as an
144: .Xr ed 1
145: script.
1.18 sobrado 146: .It Xo
147: .Fl F Ar max-fuzz ,
148: .Fl Fl fuzz Ar max-fuzz
149: .Xc
150: Sets the maximum fuzz factor.
151: This option only applies to context diffs, and causes
1.9 jmc 152: .Nm
1.18 sobrado 153: to ignore up to that many lines in looking for places to install a hunk.
154: Note that a larger fuzz factor increases the odds of a faulty patch.
155: The default fuzz factor is 2, and it may not be set to more than
156: the number of lines of context in the context diff, ordinarily 3.
1.9 jmc 157: .It Fl f , Fl Fl force
158: Forces
159: .Nm
1.1 deraadt 160: to assume that the user knows exactly what he or she is doing, and to not
1.9 jmc 161: ask any questions.
162: It assumes the following:
163: skip patches for which a file to patch can't be found;
164: patch files even though they have the wrong version for the
165: .Qq Prereq:
166: line in the patch;
167: and assume that patches are not reversed even if they look like they are.
1.1 deraadt 168: This option does not suppress commentary; use
1.9 jmc 169: .Fl s
1.1 deraadt 170: for that.
1.9 jmc 171: .It Xo
1.18 sobrado 172: .Fl i Ar patchfile ,
173: .Fl Fl input Ar patchfile
1.9 jmc 174: .Xc
1.15 millert 175: Causes the next argument to be interpreted as the input file name
176: (i.e. a patchfile).
177: This option may be specified multiple times.
1.9 jmc 178: .It Fl l , Fl Fl ignore-whitespace
179: Causes the pattern matching to be done loosely, in case the tabs and
1.1 deraadt 180: spaces have been munged in your input file.
181: Any sequence of whitespace in the pattern line will match any sequence
182: in the input file.
183: Normal characters must still match exactly.
184: Each line of the context must still match a line in the input file.
1.9 jmc 185: .It Fl N , Fl Fl forward
186: Causes
187: .Nm
1.1 deraadt 188: to ignore patches that it thinks are reversed or already applied.
189: See also
1.9 jmc 190: .Fl R .
1.18 sobrado 191: .It Fl n , Fl Fl normal
192: Forces
193: .Nm
194: to interpret the patch file as a normal diff.
195: .It Xo
196: .Fl o Ar out-file ,
197: .Fl Fl output Ar out-file
198: .Xc
1.9 jmc 199: Causes the next argument to be interpreted as the output file name.
200: .It Xo
1.18 sobrado 201: .Fl p Ar strip-count ,
202: .Fl Fl strip Ar strip-count
1.9 jmc 203: .Xc
204: Sets the pathname strip count,
205: which controls how pathnames found in the patch file are treated,
206: in case you keep your files in a different directory than the person who sent
1.1 deraadt 207: out the patch.
208: The strip count specifies how many slashes are to be stripped from
209: the front of the pathname.
210: (Any intervening directory names also go away.)
1.17 millert 211: For example, supposing the file name in the patch file was
1.9 jmc 212: .Pa /u/howard/src/blurfl/blurfl.c :
213: .Pp
214: Setting
215: .Fl p Ns Ar 0
216: gives the entire pathname unmodified.
217: .Pp
218: .Fl p Ns Ar 1
1.1 deraadt 219: gives
1.9 jmc 220: .Pp
221: .D1 Pa u/howard/src/blurfl/blurfl.c
222: .Pp
223: without the leading slash.
224: .Pp
225: .Fl p Ns Ar 4
1.1 deraadt 226: gives
1.9 jmc 227: .Pp
228: .D1 Pa blurfl/blurfl.c
229: .Pp
230: Not specifying
231: .Fl p
232: at all just gives you
233: .Pa blurfl.c ,
234: unless all of the directories in the leading path
235: .Pq Pa u/howard/src/blurfl
236: exist and that path is relative,
1.1 deraadt 237: in which case you get the entire pathname unmodified.
238: Whatever you end up with is looked for either in the current directory,
239: or the directory specified by the
1.9 jmc 240: .Fl d
1.11 millert 241: option.
1.9 jmc 242: .It Fl R , Fl Fl reverse
243: Tells
244: .Nm
1.1 deraadt 245: that this patch was created with the old and new files swapped.
246: (Yes, I'm afraid that does happen occasionally, human nature being what it
247: is.)
1.9 jmc 248: .Nm
1.1 deraadt 249: will attempt to swap each hunk around before applying it.
250: Rejects will come out in the swapped format.
251: The
1.9 jmc 252: .Fl R
1.11 millert 253: option will not work with ed diff scripts because there is too little
1.1 deraadt 254: information to reconstruct the reverse operation.
1.9 jmc 255: .Pp
1.1 deraadt 256: If the first hunk of a patch fails,
1.9 jmc 257: .Nm
1.1 deraadt 258: will reverse the hunk to see if it can be applied that way.
259: If it can, you will be asked if you want to have the
1.9 jmc 260: .Fl R
1.11 millert 261: option set.
1.1 deraadt 262: If it can't, the patch will continue to be applied normally.
263: (Note: this method cannot detect a reversed patch if it is a normal diff
264: and if the first command is an append (i.e. it should have been a delete)
265: since appends always succeed, due to the fact that a null context will match
266: anywhere.
267: Luckily, most patches add or change lines rather than delete them, so most
268: reversed normal diffs will begin with a delete, which will fail, triggering
269: the heuristic.)
1.9 jmc 270: .It Xo
1.18 sobrado 271: .Fl r Ar rej-name ,
272: .Fl Fl reject-file Ar rej-name
273: .Xc
274: Causes the next argument to be interpreted as the reject file name.
275: .It Xo
1.9 jmc 276: .Fl s , Fl Fl quiet ,
277: .Fl Fl silent
278: .Xc
279: Makes
280: .Nm
1.1 deraadt 281: do its work silently, unless an error occurs.
1.17 millert 282: .It Fl t , Fl Fl batch
283: Similar to
284: .Fl f ,
285: in that it suppresses questions, but makes some different assumptions:
286: skip patches for which a file to patch can't be found (the same as
287: .Fl f ) ;
288: skip patches for which the file has the wrong version for the
289: .Qq Prereq:
290: line in the patch;
291: and assume that patches are reversed if they look like they are.
1.9 jmc 292: .It Fl u , Fl Fl unified
293: Forces
294: .Nm
1.1 deraadt 295: to interpret the patch file as a unified context diff (a unidiff).
1.18 sobrado 296: .It Xo
297: .Fl V Cm t | nil | never ,
298: .Fl Fl version-control Cm t | nil | never
299: .Xc
1.9 jmc 300: Causes the next argument to be interpreted as a method for creating
301: backup file names.
302: The type of backups made can also be given in the
1.17 millert 303: .Ev PATCH_VERSION_CONTROL
304: or
1.9 jmc 305: .Ev VERSION_CONTROL
1.17 millert 306: environment variables, which are overridden by this option.
1.1 deraadt 307: The
1.9 jmc 308: .Fl B
1.1 deraadt 309: option overrides this option, causing the prefix to always be used for
310: making backup file names.
1.17 millert 311: The values of the
312: .Ev PATCH_VERSION_CONTROL
313: and
1.9 jmc 314: .Ev VERSION_CONTROL
1.17 millert 315: environment variables and the argument to the
1.9 jmc 316: .Fl V
317: option are like the GNU Emacs
318: .Dq version-control
319: variable; they also recognize synonyms that are more descriptive.
320: The valid values are (unique abbreviations are accepted):
321: .Bl -tag -width Ds -offset indent
1.18 sobrado 322: .It Cm t , numbered
1.1 deraadt 323: Always make numbered backups.
1.18 sobrado 324: .It Cm nil , existing
1.9 jmc 325: Make numbered backups of files that already have them,
326: simple backups of the others.
1.18 sobrado 327: .It Cm never , simple
1.1 deraadt 328: Always make simple backups.
1.9 jmc 329: .El
1.18 sobrado 330: .It Fl v , Fl Fl version
331: Causes
332: .Nm
333: to print out its revision header and patch level.
1.9 jmc 334: .It Xo
1.18 sobrado 335: .Fl x Ar number ,
336: .Fl Fl debug Ar number
1.9 jmc 337: .Xc
338: Sets internal debugging flags, and is of interest only to
339: .Nm
1.1 deraadt 340: patchers.
1.18 sobrado 341: .It Xo
342: .Fl z Ar backup-ext ,
343: .Fl Fl suffix Ar backup-ext
344: .Xc
1.12 millert 345: Causes the next argument to be interpreted as the backup extension, to be
346: used in place of
347: .Qq .orig .
1.17 millert 348: .It Fl Fl posix
349: Enables strict
1.24 jmc 350: .St -p1003.1-2008
1.17 millert 351: conformance, specifically:
352: .Bl -enum
353: .It
354: Backup files are not created unless the
355: .Fl b
356: option is specified.
357: .It
358: If unspecified, the file name used is the first of the old, new and
359: index files that exists.
360: .El
361: .El
362: .Ss Patch Application
363: .Nm
364: will try to skip any leading garbage, apply the diff,
365: and then skip any trailing garbage.
366: Thus you could feed an article or message containing a
367: diff listing to
368: .Nm patch ,
369: and it should work.
370: If the entire diff is indented by a consistent amount,
371: this will be taken into account.
372: .Pp
373: With context diffs, and to a lesser extent with normal diffs,
374: .Nm
375: can detect when the line numbers mentioned in the patch are incorrect,
376: and will attempt to find the correct place to apply each hunk of the patch.
377: As a first guess, it takes the line number mentioned for the hunk, plus or
378: minus any offset used in applying the previous hunk.
379: If that is not the correct place,
380: .Nm
381: will scan both forwards and backwards for a set of lines matching the context
382: given in the hunk.
383: First
384: .Nm
385: looks for a place where all lines of the context match.
386: If no such place is found, and it's a context diff, and the maximum fuzz factor
387: is set to 1 or more, then another scan takes place ignoring the first and last
388: line of context.
389: If that fails, and the maximum fuzz factor is set to 2 or more,
390: the first two and last two lines of context are ignored,
391: and another scan is made.
392: .Pq The default maximum fuzz factor is 2.
393: .Pp
394: If
395: .Nm
396: cannot find a place to install that hunk of the patch, it will put the hunk
397: out to a reject file, which normally is the name of the output file plus
398: .Qq .rej .
399: (Note that the rejected hunk will come out in context diff form whether the
400: input patch was a context diff or a normal diff.
401: If the input was a normal diff, many of the contexts will simply be null.)
402: The line numbers on the hunks in the reject file may be different than
403: in the patch file: they reflect the approximate location patch thinks the
404: failed hunks belong in the new file rather than the old one.
405: .Pp
406: As each hunk is completed, you will be told whether the hunk succeeded or
407: failed, and which line (in the new file)
408: .Nm
409: thought the hunk should go on.
410: If this is different from the line number specified in the diff,
411: you will be told the offset.
412: A single large offset MAY be an indication that a hunk was installed in the
413: wrong place.
414: You will also be told if a fuzz factor was used to make the match, in which
415: case you should also be slightly suspicious.
416: .Ss Filename Determination
417: If no original file is specified on the command line,
418: .Nm
419: will try to figure out from the leading garbage what the name of the file
420: to edit is.
421: When checking a prospective file name, pathname components are stripped
422: as specified by the
423: .Fl p
424: option and the file's existence and writability are checked relative
425: to the current working directory (or the directory specified by the
426: .Fl d
427: option).
428: .Pp
429: If the diff is a context or unified diff,
430: .Nm
431: is able to determine the old and new file names from the diff header.
432: For context diffs, the
433: .Dq old
434: file is specified in the line beginning with
435: .Qq ***
436: and the
437: .Dq new
438: file is specified in the line beginning with
439: .Qq --- .
440: For a unified diff, the
441: .Dq old
442: file is specified in the line beginning with
443: .Qq ---
444: and the
445: .Dq new
446: file is specified in the line beginning with
447: .Qq +++ .
448: If there is an
449: .Qq Index:
450: line in the leading garbage (regardless of the diff type),
451: .Nm
452: will use the file name from that line as the
453: .Dq index
454: file.
455: .Pp
456: .Nm
457: will choose the file name by performing the following steps, with the first
458: match used:
459: .Bl -enum
460: .It
461: If
462: .Nm
463: is operating in strict
1.24 jmc 464: .St -p1003.1-2008
1.17 millert 465: mode, the first of the
466: .Dq old ,
467: .Dq new
468: and
469: .Dq index
470: file names that exist is used.
471: Otherwise,
472: .Nm
473: will examine either the
474: .Dq old
475: and
476: .Dq new
477: file names or, for a non-context diff, the
478: .Dq index
479: file name, and choose the file name with the fewest path components,
480: the shortest basename, and the shortest total file name length (in that order).
481: .It
482: If no suitable file was found to patch, the patch file is a context or
483: unified diff, and the old file was zero length, the new file name is
484: created and used.
485: .It
486: If the file name still cannot be determined,
487: .Nm
488: will prompt the user for the file name to use.
1.9 jmc 489: .El
1.17 millert 490: .Pp
491: Additionally, if the leading garbage contains a
492: .Qq Prereq:\ \&
493: line,
494: .Nm
495: will take the first word from the prerequisites line (normally a version
496: number) and check the input file to see if that word can be found.
497: If not,
498: .Nm
499: will ask for confirmation before proceeding.
500: .Pp
501: The upshot of all this is that you should be able to say, while in a news
502: interface, the following:
503: .Pp
504: .Dl | patch -d /usr/src/local/blurfl
505: .Pp
506: and patch a file in the blurfl directory directly from the article containing
507: the patch.
508: .Ss Backup Files
509: By default, the patched version is put in place of the original, with
510: the original file backed up to the same name with the extension
511: .Qq .orig ,
512: or as specified by the
513: .Fl B ,
514: .Fl V ,
515: or
516: .Fl z
517: options.
518: The extension used for making backup files may also be specified in the
519: .Ev SIMPLE_BACKUP_SUFFIX
520: environment variable, which is overridden by the options above.
521: .Pp
522: If the backup file is a symbolic or hard link to the original file,
523: .Nm
524: creates a new backup file name by changing the first lowercase letter
525: in the last component of the file's name into uppercase.
526: If there are no more lowercase letters in the name,
527: it removes the first character from the name.
528: It repeats this process until it comes up with a
529: backup file that does not already exist or is not linked to the original file.
530: .Pp
531: You may also specify where you want the output to go with the
532: .Fl o
533: option; if that file already exists, it is backed up first.
534: .Ss Notes For Patch Senders
1.1 deraadt 535: There are several things you should bear in mind if you are going to
1.9 jmc 536: be sending out patches:
537: .Pp
538: First, you can save people a lot of grief by keeping a
539: .Pa patchlevel.h
540: file which is patched to increment the patch level as the first diff in the
1.1 deraadt 541: patch file you send out.
1.9 jmc 542: If you put a
543: .Qq Prereq:
544: line in with the patch, it won't let them apply
1.1 deraadt 545: patches out of order without some warning.
1.9 jmc 546: .Pp
1.17 millert 547: Second, make sure you've specified the file names right, either in a
1.9 jmc 548: context diff header, or with an
549: .Qq Index:
550: line.
1.1 deraadt 551: If you are patching something in a subdirectory, be sure to tell the patch
1.4 aaron 552: user to specify a
1.9 jmc 553: .Fl p
1.11 millert 554: option as needed.
1.9 jmc 555: .Pp
1.1 deraadt 556: Third, you can create a file by sending out a diff that compares a
557: null file to the file you want to create.
558: This will only work if the file you want to create doesn't exist already in
559: the target directory.
1.9 jmc 560: .Pp
1.1 deraadt 561: Fourth, take care not to send out reversed patches, since it makes people wonder
562: whether they already applied the patch.
1.9 jmc 563: .Pp
1.1 deraadt 564: Fifth, while you may be able to get away with putting 582 diff listings into
565: one file, it is probably wiser to group related patches into separate files in
566: case something goes haywire.
1.9 jmc 567: .Sh ENVIRONMENT
1.17 millert 568: .Bl -tag -width "PATCH_VERSION_CONTROL" -compact
569: .It Ev POSIXLY_CORRECT
570: When set,
571: .Nm
572: behaves as if the
573: .Fl Fl posix
574: option has been specified.
575: .It Ev SIMPLE_BACKUP_SUFFIX
576: Extension to use for backup file names instead of
577: .Qq .orig .
1.9 jmc 578: .It Ev TMPDIR
579: Directory to put temporary files in; default is
580: .Pa /tmp .
1.17 millert 581: .It Ev PATCH_VERSION_CONTROL
582: Selects when numbered backup files are made.
1.9 jmc 583: .It Ev VERSION_CONTROL
1.17 millert 584: Same as
585: .Ev PATCH_VERSION_CONTROL .
1.9 jmc 586: .El
587: .Sh FILES
1.17 millert 588: .Bl -tag -width "$TMPDIR/patch*" -compact
1.9 jmc 589: .It Pa $TMPDIR/patch*
1.17 millert 590: .Nm
591: temporary files
592: .It Pa /dev/tty
593: used to read input when
594: .Nm
595: prompts the user
1.9 jmc 596: .El
1.26 jmc 597: .Sh EXIT STATUS
598: The
599: .Nm
600: utility exits with one of the following values:
601: .Pp
602: .Bl -tag -width Ds -offset indent -compact
603: .It 0
604: Successful completion.
605: .It 1
606: One or more lines were written to a reject file.
607: .It \*(Gt1
608: An error occurred.
609: .El
610: .Pp
611: When applying a set of patches in a loop it behooves you to check this
612: exit status so you don't apply a later patch to a partially patched file.
1.9 jmc 613: .Sh DIAGNOSTICS
1.1 deraadt 614: Too many to list here, but generally indicative that
1.9 jmc 615: .Nm
1.1 deraadt 616: couldn't parse your patch file.
1.9 jmc 617: .Pp
618: The message
619: .Qq Hmm...
620: indicates that there is unprocessed text in the patch file and that
621: .Nm
1.1 deraadt 622: is attempting to intuit whether there is a patch in that text and, if so,
623: what kind of patch it is.
1.9 jmc 624: .Sh SEE ALSO
625: .Xr diff 1
1.19 jmc 626: .Sh STANDARDS
627: The
628: .Nm
629: utility is compliant with the
1.24 jmc 630: .St -p1003.1-2008
1.27 jmc 631: specification,
632: except as detailed above for the
1.22 jmc 633: .Fl -posix
1.27 jmc 634: option.
1.19 jmc 635: .Pp
636: The flags
1.25 jmc 637: .Op Fl BCEFfstVvxz
1.19 jmc 638: and
639: .Op Fl -posix
640: are extensions to that specification.
1.9 jmc 641: .Sh AUTHORS
1.13 millert 642: .An Larry Wall
1.9 jmc 643: with many other contributors.
644: .Sh CAVEATS
645: .Nm
1.1 deraadt 646: cannot tell if the line numbers are off in an ed script, and can only detect
1.9 jmc 647: bad line numbers in a normal diff when it finds a
648: .Qq change
649: or a
650: .Qq delete
651: command.
1.1 deraadt 652: A context diff using fuzz factor 3 may have the same problem.
653: Until a suitable interactive interface is added, you should probably do
654: a context diff in these cases to see if the changes made sense.
655: Of course, compiling without errors is a pretty good indication that the patch
656: worked, but not always.
1.9 jmc 657: .Pp
658: .Nm
1.1 deraadt 659: usually produces the correct results, even when it has to do a lot of
660: guessing.
661: However, the results are guaranteed to be correct only when the patch is
662: applied to exactly the same version of the file that the patch was
663: generated from.
1.9 jmc 664: .Sh BUGS
665: Could be smarter about partial matches, excessively deviant offsets and
1.1 deraadt 666: swapped code, but that would take an extra pass.
1.9 jmc 667: .Pp
668: Check patch mode
669: .Pq Fl C
1.3 espie 670: will fail if you try to check several patches in succession that build on
1.9 jmc 671: each other.
1.17 millert 672: The entire
1.9 jmc 673: .Nm
1.17 millert 674: code would have to be restructured to keep temporary files around so that it
675: can handle this situation.
1.9 jmc 676: .Pp
1.1 deraadt 677: If code has been duplicated (for instance with #ifdef OLDCODE ... #else ...
678: #endif),
1.9 jmc 679: .Nm
1.29 jmc 680: is incapable of patching both versions and, if it works at all, will likely
1.1 deraadt 681: patch the wrong one, and tell you that it succeeded to boot.
1.9 jmc 682: .Pp
1.1 deraadt 683: If you apply a patch you've already applied,
1.9 jmc 684: .Nm
1.1 deraadt 685: will think it is a reversed patch, and offer to un-apply the patch.
686: This could be construed as a feature.