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