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