Annotation of src/usr.bin/patch/patch.1, Revision 1.1
1.1 ! deraadt 1: .\" $Id: patch.1,v 1.2 1993/08/02 17:55:18 mycroft Exp $ -*- nroff -*-
! 2: .rn '' }`
! 3: .de Sh
! 4: .br
! 5: .ne 5
! 6: .PP
! 7: \fB\\$1\fR
! 8: .PP
! 9: ..
! 10: .de Sp
! 11: .if t .sp .5v
! 12: .if n .sp
! 13: ..
! 14: '\"
! 15: '\" Set up \*(-- to give an unbreakable dash;
! 16: '\" string Tr holds user defined translation string.
! 17: '\" Bell System Logo is used as a dummy character.
! 18: '\"
! 19: '\" Shut up a groff -ww warning.
! 20: .if \n(.g .if !dTr .ds Tr
! 21: .ie n \{\
! 22: .tr \(*W-\*(Tr
! 23: .ds -- \(*W-
! 24: .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
! 25: .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
! 26: .ds L" ""
! 27: .ds R" ""
! 28: .ds L' '
! 29: .ds R' '
! 30: 'br \}
! 31: .el \{\
! 32: .ds -- \(em\|
! 33: .tr \*(Tr
! 34: .ds L" ``
! 35: .ds R" ''
! 36: .ds L' `
! 37: .ds R' '
! 38: 'br\}
! 39: .TH PATCH 1
! 40: .SH NAME
! 41: patch - apply a diff file to an original
! 42: .SH SYNOPSIS
! 43: .B patch
! 44: [options] [origfile [patchfile]] [+ [options] [origfile]]...
! 45: .sp
! 46: but usually just
! 47: .sp
! 48: .B patch
! 49: <patchfile
! 50: .SH DESCRIPTION
! 51: .I Patch
! 52: will take a patch file containing any of the four forms of difference
! 53: listing produced by the
! 54: .I diff
! 55: program and apply those differences to an original file, producing a patched
! 56: version.
! 57: By default, the patched version is put in place of the original, with
! 58: the original file backed up to the same name with the
! 59: extension \*(L".orig\*(R" (\*(L"~\*(R" on systems that do not
! 60: support long filenames), or as specified by the
! 61: .BR -b ,
! 62: .BR -B ,
! 63: or
! 64: .B -V
! 65: switches.
! 66: The extension used for making backup files may also be specified in the
! 67: .B SIMPLE_BACKUP_SUFFIX
! 68: environment variable, which is overridden by above switches.
! 69: .PP
! 70: If the backup file already exists,
! 71: .B patch
! 72: creates a new backup file name by changing the first lowercase letter
! 73: in the last component of the file's name into uppercase. If there are
! 74: no more lowercase letters in the name, it removes the first character
! 75: from the name. It repeats this process until it comes up with a
! 76: backup file that does not already exist.
! 77: .PP
! 78: You may also specify where you want the output to go with a
! 79: .B -o
! 80: switch; if that file already exists, it is backed up first.
! 81: .PP
! 82: If
! 83: .I patchfile
! 84: is omitted, or is a hyphen, the patch will be read from standard input.
! 85: .PP
! 86: Upon startup, patch will attempt to determine the type of the diff listing,
! 87: unless over-ruled by a
! 88: .BR -c ,
! 89: .BR -e ,
! 90: .BR -n ,
! 91: or
! 92: .B -u
! 93: switch.
! 94: Context diffs (old-style, new-style, and unified) and
! 95: normal diffs are applied by the
! 96: .I patch
! 97: program itself, while ed diffs are simply fed to the
! 98: .I ed
! 99: editor via a pipe.
! 100: .PP
! 101: .I Patch
! 102: will try to skip any leading garbage, apply the diff,
! 103: and then skip any trailing garbage.
! 104: Thus you could feed an article or message containing a
! 105: diff listing to
! 106: .IR patch ,
! 107: and it should work.
! 108: If the entire diff is indented by a consistent amount,
! 109: this will be taken into account.
! 110: .PP
! 111: With context diffs, and to a lesser extent with normal diffs,
! 112: .I patch
! 113: can detect when the line numbers mentioned in the patch are incorrect,
! 114: and will attempt to find the correct place to apply each hunk of the patch.
! 115: As a first guess, it takes the line number mentioned for the hunk, plus or
! 116: minus any offset used in applying the previous hunk.
! 117: If that is not the correct place,
! 118: .I patch
! 119: will scan both forwards and backwards for a set of lines matching the context
! 120: given in the hunk.
! 121: First
! 122: .I patch
! 123: looks for a place where all lines of the context match.
! 124: If no such place is found, and it's a context diff, and the maximum fuzz factor
! 125: is set to 1 or more, then another scan takes place ignoring the first and last
! 126: line of context.
! 127: If that fails, and the maximum fuzz factor is set to 2 or more,
! 128: the first two and last two lines of context are ignored,
! 129: and another scan is made.
! 130: (The default maximum fuzz factor is 2.)
! 131: If
! 132: .I patch
! 133: cannot find a place to install that hunk of the patch, it will put the
! 134: hunk out to a reject file, which normally is the name of the output file
! 135: plus \*(L".rej\*(R" (\*(L"#\*(R" on systems that do not support
! 136: long filenames).
! 137: (Note that the rejected hunk will come out in context diff form whether the
! 138: input patch was a context diff or a normal diff.
! 139: If the input was a normal diff, many of the contexts will simply be null.)
! 140: The line numbers on the hunks in the reject file may be different than
! 141: in the patch file: they reflect the approximate location patch thinks the
! 142: failed hunks belong in the new file rather than the old one.
! 143: .PP
! 144: As each hunk is completed, you will be told whether the hunk succeeded or
! 145: failed, and which line (in the new file)
! 146: .I patch
! 147: thought the hunk should go on.
! 148: If this is different from the line number specified in the diff you will
! 149: be told the offset.
! 150: A single large offset MAY be an indication that a hunk was installed in the
! 151: wrong place.
! 152: You will also be told if a fuzz factor was used to make the match, in which
! 153: case you should also be slightly suspicious.
! 154: .PP
! 155: If no original file is specified on the command line,
! 156: .I patch
! 157: will try to figure out from the leading garbage what the name of the file
! 158: to edit is.
! 159: In the header of a context diff, the filename is found from lines beginning
! 160: with \*(L"***\*(R" or \*(L"---\*(R", with the shortest name of an existing
! 161: file winning.
! 162: Only context diffs have lines like that, but if there is an \*(L"Index:\*(R"
! 163: line in the leading garbage,
! 164: .I patch
! 165: will try to use the filename from that line.
! 166: The context diff header takes precedence over an Index line.
! 167: If no filename can be intuited from the leading garbage, you will be asked
! 168: for the name of the file to patch.
! 169: .PP
! 170: If the original file cannot be found or is read-only, but a suitable
! 171: SCCS or RCS file is handy,
! 172: .I patch
! 173: will attempt to get or check out the file.
! 174: .PP
! 175: Additionally, if the leading garbage contains a \*(L"Prereq: \*(R" line,
! 176: .I patch
! 177: will take the first word from the prerequisites line (normally a version
! 178: number) and check the input file to see if that word can be found.
! 179: If not,
! 180: .I patch
! 181: will ask for confirmation before proceeding.
! 182: .PP
! 183: The upshot of all this is that you should be able to say, while in a news
! 184: interface, the following:
! 185: .Sp
! 186: | patch -d /usr/src/local/blurfl
! 187: .Sp
! 188: and patch a file in the blurfl directory directly from the article containing
! 189: the patch.
! 190: .PP
! 191: If the patch file contains more than one patch,
! 192: .I patch
! 193: will try to apply each of them as if they came from separate patch files.
! 194: This means, among other things, that it is assumed that the name of the file
! 195: to patch must be determined for each diff listing,
! 196: and that the garbage before each diff listing will
! 197: be examined for interesting things such as filenames and revision level, as
! 198: mentioned previously.
! 199: You can give switches (and another original file name) for the second and
! 200: subsequent patches by separating the corresponding argument lists
! 201: by a \*(L'+\*(R'.
! 202: (The argument list for a second or subsequent patch may not specify a new
! 203: patch file, however.)
! 204: .PP
! 205: .I Patch
! 206: recognizes the following switches:
! 207: .TP 5
! 208: .B \-b
! 209: causes the next argument to be interpreted as the backup extension, to be
! 210: used in place of \*(L".orig\*(R" or \*(L"~\*(R".
! 211: .TP 5
! 212: .B \-B
! 213: causes the next argument to be interpreted as a prefix to the backup file
! 214: name. If this argument is specified any argument from -b will be ignored.
! 215: .TP 5
! 216: .B \-c
! 217: forces
! 218: .I patch
! 219: to interpret the patch file as a context diff.
! 220: .TP 5
! 221: .B \-d
! 222: causes
! 223: .I patch
! 224: to interpret the next argument as a directory, and cd to it before doing
! 225: anything else.
! 226: .TP 5
! 227: .B \-D
! 228: causes
! 229: .I patch
! 230: to use the "#ifdef...#endif" construct to mark changes.
! 231: The argument following will be used as the differentiating symbol.
! 232: Note that, unlike the C compiler, there must be a space between the
! 233: .B \-D
! 234: and the argument.
! 235: .TP 5
! 236: .B \-e
! 237: forces
! 238: .I patch
! 239: to interpret the patch file as an ed script.
! 240: .TP 5
! 241: .B \-E
! 242: causes
! 243: .I patch
! 244: to remove output files that are empty after the patches have been applied.
! 245: .TP 5
! 246: .B \-f
! 247: forces
! 248: .I patch
! 249: to assume that the user knows exactly what he or she is doing, and to not
! 250: ask any questions. It assumes the following: skip patches for which a
! 251: file to patch can't be found; patch files even though they have the
! 252: wrong version for the ``Prereq:'' line in the patch; and assume that
! 253: patches are not reversed even if they look like they are.
! 254: This option does not suppress commentary; use
! 255: .B \-s
! 256: for that.
! 257: .TP 5
! 258: .B \-t
! 259: similar to
! 260: .BR \-f ,
! 261: in that it suppresses questions, but makes some different assumptions:
! 262: skip patches for which a file to patch can't be found (the same as \fB\-f\fP);
! 263: skip patches for which the file has the wrong version for the ``Prereq:'' line
! 264: in the patch; and assume that patches are reversed if they look like
! 265: they are.
! 266: .TP 5
! 267: .B \-F<number>
! 268: sets the maximum fuzz factor.
! 269: This switch only applies to context diffs, and causes
! 270: .I patch
! 271: to ignore up to that many lines in looking for places to install a hunk.
! 272: Note that a larger fuzz factor increases the odds of a faulty patch.
! 273: The default fuzz factor is 2, and it may not be set to more than
! 274: the number of lines of context in the context diff, ordinarily 3.
! 275: .TP 5
! 276: .B \-l
! 277: causes the pattern matching to be done loosely, in case the tabs and
! 278: spaces have been munged in your input file.
! 279: Any sequence of whitespace in the pattern line will match any sequence
! 280: in the input file.
! 281: Normal characters must still match exactly.
! 282: Each line of the context must still match a line in the input file.
! 283: .TP 5
! 284: .B \-n
! 285: forces
! 286: .I patch
! 287: to interpret the patch file as a normal diff.
! 288: .TP 5
! 289: .B \-N
! 290: causes
! 291: .I patch
! 292: to ignore patches that it thinks are reversed or already applied.
! 293: See also
! 294: .B \-R .
! 295: .TP 5
! 296: .B \-o
! 297: causes the next argument to be interpreted as the output file name.
! 298: .TP 5
! 299: .B \-p<number>
! 300: sets the pathname strip count,
! 301: which controls how pathnames found in the patch file are treated, in case
! 302: the you keep your files in a different directory than the person who sent
! 303: out the patch.
! 304: The strip count specifies how many slashes are to be stripped from
! 305: the front of the pathname.
! 306: (Any intervening directory names also go away.)
! 307: For example, supposing the filename in the patch file was
! 308: .sp
! 309: /u/howard/src/blurfl/blurfl.c
! 310: .sp
! 311: setting
! 312: .B \-p
! 313: or
! 314: .B \-p0
! 315: gives the entire pathname unmodified,
! 316: .B \-p1
! 317: gives
! 318: .sp
! 319: u/howard/src/blurfl/blurfl.c
! 320: .sp
! 321: without the leading slash,
! 322: .B \-p4
! 323: gives
! 324: .sp
! 325: blurfl/blurfl.c
! 326: .sp
! 327: and not specifying
! 328: .B \-p
! 329: at all just gives you "blurfl.c", unless all of the directories in the
! 330: leading path (u/howard/src/blurfl) exist and that path is relative,
! 331: in which case you get the entire pathname unmodified.
! 332: Whatever you end up with is looked for either in the current directory,
! 333: or the directory specified by the
! 334: .B \-d
! 335: switch.
! 336: .TP 5
! 337: .B \-r
! 338: causes the next argument to be interpreted as the reject file name.
! 339: .TP 5
! 340: .B \-R
! 341: tells
! 342: .I patch
! 343: that this patch was created with the old and new files swapped.
! 344: (Yes, I'm afraid that does happen occasionally, human nature being what it
! 345: is.)
! 346: .I Patch
! 347: will attempt to swap each hunk around before applying it.
! 348: Rejects will come out in the swapped format.
! 349: The
! 350: .B \-R
! 351: switch will not work with ed diff scripts because there is too little
! 352: information to reconstruct the reverse operation.
! 353: .Sp
! 354: If the first hunk of a patch fails,
! 355: .I patch
! 356: will reverse the hunk to see if it can be applied that way.
! 357: If it can, you will be asked if you want to have the
! 358: .B \-R
! 359: switch set.
! 360: If it can't, the patch will continue to be applied normally.
! 361: (Note: this method cannot detect a reversed patch if it is a normal diff
! 362: and if the first command is an append (i.e. it should have been a delete)
! 363: since appends always succeed, due to the fact that a null context will match
! 364: anywhere.
! 365: Luckily, most patches add or change lines rather than delete them, so most
! 366: reversed normal diffs will begin with a delete, which will fail, triggering
! 367: the heuristic.)
! 368: .TP 5
! 369: .B \-s
! 370: makes
! 371: .I patch
! 372: do its work silently, unless an error occurs.
! 373: .TP 5
! 374: .B \-S
! 375: causes
! 376: .I patch
! 377: to ignore this patch from the patch file, but continue on looking
! 378: for the next patch in the file.
! 379: Thus
! 380: .sp
! 381: patch -S + -S + <patchfile
! 382: .sp
! 383: will ignore the first and second of three patches.
! 384: .TP 5
! 385: .B \-u
! 386: forces
! 387: .I patch
! 388: to interpret the patch file as a unified context diff (a unidiff).
! 389: .TP 5
! 390: .B \-v
! 391: causes
! 392: .I patch
! 393: to print out its revision header and patch level.
! 394: .TP 5
! 395: .B \-V
! 396: causes the next argument to be interpreted as a method for creating
! 397: backup file names. The type of backups made can also be given in the
! 398: .B VERSION_CONTROL
! 399: environment variable, which is overridden by this option.
! 400: The
! 401: .B -B
! 402: option overrides this option, causing the prefix to always be used for
! 403: making backup file names.
! 404: The value of the
! 405: .B VERSION_CONTROL
! 406: environment variable and the argument to the
! 407: .B -V
! 408: option are like the GNU
! 409: Emacs `version-control' variable; they also recognize synonyms that
! 410: are more descriptive. The valid values are (unique abbreviations are
! 411: accepted):
! 412: .RS
! 413: .TP
! 414: `t' or `numbered'
! 415: Always make numbered backups.
! 416: .TP
! 417: `nil' or `existing'
! 418: Make numbered backups of files that already
! 419: have them, simple backups of the others.
! 420: This is the default.
! 421: .TP
! 422: `never' or `simple'
! 423: Always make simple backups.
! 424: .RE
! 425: .TP 5
! 426: .B \-x<number>
! 427: sets internal debugging flags, and is of interest only to
! 428: .I patch
! 429: patchers.
! 430: .SH AUTHOR
! 431: Larry Wall <lwall@netlabs.com>
! 432: .br
! 433: with many other contributors.
! 434: .SH ENVIRONMENT
! 435: .TP
! 436: .B TMPDIR
! 437: Directory to put temporary files in; default is /tmp.
! 438: .TP
! 439: .B SIMPLE_BACKUP_SUFFIX
! 440: Extension to use for backup file names instead of \*(L".orig\*(R" or
! 441: \*(L"~\*(R".
! 442: .TP
! 443: .B VERSION_CONTROL
! 444: Selects when numbered backup files are made.
! 445: .SH FILES
! 446: $TMPDIR/patch*
! 447: .SH SEE ALSO
! 448: diff(1)
! 449: .SH NOTES FOR PATCH SENDERS
! 450: There are several things you should bear in mind if you are going to
! 451: be sending out patches.
! 452: First, you can save people a lot of grief by keeping a patchlevel.h file
! 453: which is patched to increment the patch level as the first diff in the
! 454: patch file you send out.
! 455: If you put a Prereq: line in with the patch, it won't let them apply
! 456: patches out of order without some warning.
! 457: Second, make sure you've specified the filenames right, either in a
! 458: context diff header, or with an Index: line.
! 459: If you are patching something in a subdirectory, be sure to tell the patch
! 460: user to specify a
! 461: .B \-p
! 462: switch as needed.
! 463: Third, you can create a file by sending out a diff that compares a
! 464: null file to the file you want to create.
! 465: This will only work if the file you want to create doesn't exist already in
! 466: the target directory.
! 467: Fourth, take care not to send out reversed patches, since it makes people wonder
! 468: whether they already applied the patch.
! 469: Fifth, while you may be able to get away with putting 582 diff listings into
! 470: one file, it is probably wiser to group related patches into separate files in
! 471: case something goes haywire.
! 472: .SH DIAGNOSTICS
! 473: Too many to list here, but generally indicative that
! 474: .I patch
! 475: couldn't parse your patch file.
! 476: .PP
! 477: The message \*(L"Hmm...\*(R" indicates that there is unprocessed text in
! 478: the patch file and that
! 479: .I patch
! 480: is attempting to intuit whether there is a patch in that text and, if so,
! 481: what kind of patch it is.
! 482: .PP
! 483: .I Patch
! 484: will exit with a non-zero status if any reject files were created.
! 485: When applying a set of patches in a loop it behooves you to check this
! 486: exit status so you don't apply a later patch to a partially patched file.
! 487: .SH CAVEATS
! 488: .I Patch
! 489: cannot tell if the line numbers are off in an ed script, and can only detect
! 490: bad line numbers in a normal diff when it finds a \*(L"change\*(R" or
! 491: a \*(L"delete\*(R" command.
! 492: A context diff using fuzz factor 3 may have the same problem.
! 493: Until a suitable interactive interface is added, you should probably do
! 494: a context diff in these cases to see if the changes made sense.
! 495: Of course, compiling without errors is a pretty good indication that the patch
! 496: worked, but not always.
! 497: .PP
! 498: .I Patch
! 499: usually produces the correct results, even when it has to do a lot of
! 500: guessing.
! 501: However, the results are guaranteed to be correct only when the patch is
! 502: applied to exactly the same version of the file that the patch was
! 503: generated from.
! 504: .SH BUGS
! 505: Could be smarter about partial matches, excessively \&deviant offsets and
! 506: swapped code, but that would take an extra pass.
! 507: .PP
! 508: If code has been duplicated (for instance with #ifdef OLDCODE ... #else ...
! 509: #endif),
! 510: .I patch
! 511: is incapable of patching both versions, and, if it works at all, will likely
! 512: patch the wrong one, and tell you that it succeeded to boot.
! 513: .PP
! 514: If you apply a patch you've already applied,
! 515: .I patch
! 516: will think it is a reversed patch, and offer to un-apply the patch.
! 517: This could be construed as a feature.
! 518: .rn }` ''
![[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 [local] / src / usr.bin / patch