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