Annotation of src/usr.bin/patch/patch.1, Revision 1.4
1.4 ! aaron 1: .\" $OpenBSD: patch.1,v 1.3 1998/11/25 00:30:25 espie Exp $ -*- nroff -*-
1.1 deraadt 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
1.2 niklas 208: .B \-b or \-\-suffix
1.1 deraadt 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
1.2 niklas 212: .B \-B or \-\-prefix
1.1 deraadt 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
1.2 niklas 216: .B \-c or \-\-context
1.1 deraadt 217: forces
218: .I patch
219: to interpret the patch file as a context diff.
220: .TP 5
1.3 espie 221: .B \-C or \-\-check
222: checks that the patch would apply cleanly, but does not modify anything.
223: .TP 5
1.2 niklas 224: .B \-d or \-\-directory
1.1 deraadt 225: causes
226: .I patch
227: to interpret the next argument as a directory, and cd to it before doing
228: anything else.
229: .TP 5
1.2 niklas 230: .B \-D or \-\-ifdef
1.1 deraadt 231: causes
232: .I patch
233: to use the "#ifdef...#endif" construct to mark changes.
234: The argument following will be used as the differentiating symbol.
235: Note that, unlike the C compiler, there must be a space between the
236: .B \-D
237: and the argument.
238: .TP 5
1.2 niklas 239: .B \-e or \-\-ed
1.1 deraadt 240: forces
241: .I patch
242: to interpret the patch file as an ed script.
243: .TP 5
1.2 niklas 244: .B \-E or \-\-remove-empty-files
1.1 deraadt 245: causes
246: .I patch
247: to remove output files that are empty after the patches have been applied.
248: .TP 5
1.2 niklas 249: .B \-f or \-\-force
1.1 deraadt 250: forces
251: .I patch
252: to assume that the user knows exactly what he or she is doing, and to not
253: ask any questions. It assumes the following: skip patches for which a
254: file to patch can't be found; patch files even though they have the
255: wrong version for the ``Prereq:'' line in the patch; and assume that
256: patches are not reversed even if they look like they are.
257: This option does not suppress commentary; use
258: .B \-s
259: for that.
260: .TP 5
1.2 niklas 261: .B \-t or \-\-batch
1.1 deraadt 262: similar to
263: .BR \-f ,
264: in that it suppresses questions, but makes some different assumptions:
265: skip patches for which a file to patch can't be found (the same as \fB\-f\fP);
266: skip patches for which the file has the wrong version for the ``Prereq:'' line
267: in the patch; and assume that patches are reversed if they look like
268: they are.
269: .TP 5
1.2 niklas 270: .B \-F<number> or \-\-fuzz <number>
1.1 deraadt 271: sets the maximum fuzz factor.
272: This switch only applies to context diffs, and causes
273: .I patch
274: to ignore up to that many lines in looking for places to install a hunk.
275: Note that a larger fuzz factor increases the odds of a faulty patch.
276: The default fuzz factor is 2, and it may not be set to more than
277: the number of lines of context in the context diff, ordinarily 3.
278: .TP 5
1.2 niklas 279: .B \-l or \-\-ignore-whitespace
1.1 deraadt 280: causes the pattern matching to be done loosely, in case the tabs and
281: spaces have been munged in your input file.
282: Any sequence of whitespace in the pattern line will match any sequence
283: in the input file.
284: Normal characters must still match exactly.
285: Each line of the context must still match a line in the input file.
286: .TP 5
1.2 niklas 287: .B \-n or \-\-normal
1.1 deraadt 288: forces
289: .I patch
290: to interpret the patch file as a normal diff.
291: .TP 5
1.2 niklas 292: .B \-N or \-\-forward
1.1 deraadt 293: causes
294: .I patch
295: to ignore patches that it thinks are reversed or already applied.
296: See also
297: .B \-R .
298: .TP 5
1.2 niklas 299: .B \-o or \-\-output
1.1 deraadt 300: causes the next argument to be interpreted as the output file name.
301: .TP 5
1.2 niklas 302: .B \-p<number> or \-\-strip <number>
1.1 deraadt 303: sets the pathname strip count,
304: which controls how pathnames found in the patch file are treated, in case
305: the you keep your files in a different directory than the person who sent
306: out the patch.
307: The strip count specifies how many slashes are to be stripped from
308: the front of the pathname.
309: (Any intervening directory names also go away.)
310: For example, supposing the filename in the patch file was
311: .sp
312: /u/howard/src/blurfl/blurfl.c
313: .sp
314: setting
315: .B \-p
316: or
317: .B \-p0
318: gives the entire pathname unmodified,
319: .B \-p1
320: gives
321: .sp
322: u/howard/src/blurfl/blurfl.c
323: .sp
324: without the leading slash,
325: .B \-p4
326: gives
327: .sp
328: blurfl/blurfl.c
329: .sp
330: and not specifying
331: .B \-p
332: at all just gives you "blurfl.c", unless all of the directories in the
333: leading path (u/howard/src/blurfl) exist and that path is relative,
334: in which case you get the entire pathname unmodified.
335: Whatever you end up with is looked for either in the current directory,
336: or the directory specified by the
337: .B \-d
338: switch.
339: .TP 5
1.2 niklas 340: .B \-r or \-\-reject-file
1.1 deraadt 341: causes the next argument to be interpreted as the reject file name.
342: .TP 5
1.2 niklas 343: .B \-R or \-\-reverse
1.1 deraadt 344: tells
345: .I patch
346: that this patch was created with the old and new files swapped.
347: (Yes, I'm afraid that does happen occasionally, human nature being what it
348: is.)
349: .I Patch
350: will attempt to swap each hunk around before applying it.
351: Rejects will come out in the swapped format.
352: The
353: .B \-R
354: switch will not work with ed diff scripts because there is too little
355: information to reconstruct the reverse operation.
356: .Sp
357: If the first hunk of a patch fails,
358: .I patch
359: will reverse the hunk to see if it can be applied that way.
360: If it can, you will be asked if you want to have the
361: .B \-R
362: switch set.
363: If it can't, the patch will continue to be applied normally.
364: (Note: this method cannot detect a reversed patch if it is a normal diff
365: and if the first command is an append (i.e. it should have been a delete)
366: since appends always succeed, due to the fact that a null context will match
367: anywhere.
368: Luckily, most patches add or change lines rather than delete them, so most
369: reversed normal diffs will begin with a delete, which will fail, triggering
370: the heuristic.)
371: .TP 5
1.2 niklas 372: .B \-s or \-\-quiet or \-\-silent
1.1 deraadt 373: makes
374: .I patch
375: do its work silently, unless an error occurs.
376: .TP 5
1.2 niklas 377: .B \-S or \-\-skip
1.1 deraadt 378: causes
379: .I patch
380: to ignore this patch from the patch file, but continue on looking
381: for the next patch in the file.
382: Thus
383: .sp
384: patch -S + -S + <patchfile
385: .sp
386: will ignore the first and second of three patches.
387: .TP 5
1.2 niklas 388: .B \-u or \-\-unified
1.1 deraadt 389: forces
390: .I patch
391: to interpret the patch file as a unified context diff (a unidiff).
392: .TP 5
1.2 niklas 393: .B \-v or \-\-version
1.1 deraadt 394: causes
395: .I patch
396: to print out its revision header and patch level.
397: .TP 5
1.2 niklas 398: .B \-V or \-\-version-control
1.1 deraadt 399: causes the next argument to be interpreted as a method for creating
400: backup file names. The type of backups made can also be given in the
401: .B VERSION_CONTROL
402: environment variable, which is overridden by this option.
403: The
404: .B -B
405: option overrides this option, causing the prefix to always be used for
406: making backup file names.
407: The value of the
408: .B VERSION_CONTROL
409: environment variable and the argument to the
410: .B -V
411: option are like the GNU
412: Emacs `version-control' variable; they also recognize synonyms that
413: are more descriptive. The valid values are (unique abbreviations are
414: accepted):
415: .RS
416: .TP
417: `t' or `numbered'
418: Always make numbered backups.
419: .TP
420: `nil' or `existing'
421: Make numbered backups of files that already
422: have them, simple backups of the others.
423: This is the default.
424: .TP
425: `never' or `simple'
426: Always make simple backups.
427: .RE
428: .TP 5
1.2 niklas 429: .B \-x<number> or \-\-debug <number>
1.1 deraadt 430: sets internal debugging flags, and is of interest only to
431: .I patch
432: patchers.
433: .SH AUTHOR
434: Larry Wall <lwall@netlabs.com>
435: .br
436: with many other contributors.
437: .SH ENVIRONMENT
438: .TP
439: .B TMPDIR
440: Directory to put temporary files in; default is /tmp.
441: .TP
442: .B SIMPLE_BACKUP_SUFFIX
443: Extension to use for backup file names instead of \*(L".orig\*(R" or
444: \*(L"~\*(R".
445: .TP
446: .B VERSION_CONTROL
447: Selects when numbered backup files are made.
448: .SH FILES
449: $TMPDIR/patch*
450: .SH SEE ALSO
451: diff(1)
452: .SH NOTES FOR PATCH SENDERS
453: There are several things you should bear in mind if you are going to
454: be sending out patches.
455: First, you can save people a lot of grief by keeping a patchlevel.h file
456: which is patched to increment the patch level as the first diff in the
457: patch file you send out.
458: If you put a Prereq: line in with the patch, it won't let them apply
459: patches out of order without some warning.
460: Second, make sure you've specified the filenames right, either in a
461: context diff header, or with an Index: line.
462: If you are patching something in a subdirectory, be sure to tell the patch
1.4 ! aaron 463: user to specify a
1.1 deraadt 464: .B \-p
465: switch as needed.
466: Third, you can create a file by sending out a diff that compares a
467: null file to the file you want to create.
468: This will only work if the file you want to create doesn't exist already in
469: the target directory.
470: Fourth, take care not to send out reversed patches, since it makes people wonder
471: whether they already applied the patch.
472: Fifth, while you may be able to get away with putting 582 diff listings into
473: one file, it is probably wiser to group related patches into separate files in
474: case something goes haywire.
475: .SH DIAGNOSTICS
476: Too many to list here, but generally indicative that
477: .I patch
478: couldn't parse your patch file.
479: .PP
480: The message \*(L"Hmm...\*(R" indicates that there is unprocessed text in
481: the patch file and that
482: .I patch
483: is attempting to intuit whether there is a patch in that text and, if so,
484: what kind of patch it is.
485: .PP
486: .I Patch
487: will exit with a non-zero status if any reject files were created.
488: When applying a set of patches in a loop it behooves you to check this
489: exit status so you don't apply a later patch to a partially patched file.
490: .SH CAVEATS
491: .I Patch
492: cannot tell if the line numbers are off in an ed script, and can only detect
493: bad line numbers in a normal diff when it finds a \*(L"change\*(R" or
494: a \*(L"delete\*(R" command.
495: A context diff using fuzz factor 3 may have the same problem.
496: Until a suitable interactive interface is added, you should probably do
497: a context diff in these cases to see if the changes made sense.
498: Of course, compiling without errors is a pretty good indication that the patch
499: worked, but not always.
500: .PP
501: .I Patch
502: usually produces the correct results, even when it has to do a lot of
503: guessing.
504: However, the results are guaranteed to be correct only when the patch is
505: applied to exactly the same version of the file that the patch was
506: generated from.
507: .SH BUGS
508: Could be smarter about partial matches, excessively \&deviant offsets and
509: swapped code, but that would take an extra pass.
1.3 espie 510: .PP
511: Check patch mode (
512: .BR -C )
513: will fail if you try to check several patches in succession that build on
1.4 ! aaron 514: each other. The whole code of
1.3 espie 515: .I patch
516: would have to be restructured to keep temporary files around so that it can
517: handle this situation.
1.1 deraadt 518: .PP
519: If code has been duplicated (for instance with #ifdef OLDCODE ... #else ...
520: #endif),
521: .I patch
522: is incapable of patching both versions, and, if it works at all, will likely
523: patch the wrong one, and tell you that it succeeded to boot.
524: .PP
525: If you apply a patch you've already applied,
526: .I patch
527: will think it is a reversed patch, and offer to un-apply the patch.
528: This could be construed as a feature.
529: .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