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