![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to patch.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / patch|
Return to patch.1 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / patch |
1.1 root 1: ''' $Header: patch.man,v 2.0 86/09/17 15:39:09 lwall Exp $
2: '''
3: ''' $Log: patch.man,v $
4: ''' Revision 2.0 86/09/17 15:39:09 lwall
5: ''' Baseline for netwide release.
6: '''
7: ''' Revision 1.4 86/08/01 19:23:22 lwall
8: ''' Documented -v, -p, -F.
9: ''' Added notes to patch senders.
10: '''
11: ''' Revision 1.3 85/03/26 15:11:06 lwall
12: ''' Frozen.
13: '''
14: ''' Revision 1.2.1.4 85/03/12 16:14:27 lwall
15: ''' Documented -p.
16: '''
17: ''' Revision 1.2.1.3 85/03/12 16:09:41 lwall
18: ''' Documented -D.
19: '''
20: ''' Revision 1.2.1.2 84/12/05 11:06:55 lwall
21: ''' Added -l switch, and noted bistability bug.
22: '''
23: ''' Revision 1.2.1.1 84/12/04 17:23:39 lwall
24: ''' Branch for sdcrdcf changes.
25: '''
26: ''' Revision 1.2 84/12/04 17:22:02 lwall
27: ''' Baseline version.
28: '''
29: .de Sh
30: .br
31: .ne 5
32: .PP
33: \fB\\$1\fR
34: .PP
35: ..
36: .de Sp
37: .if t .sp .5v
38: .if n .sp
39: ..
40: '''
41: ''' Set up \*(-- to give an unbreakable dash;
42: ''' string Tr holds user defined translation string.
43: ''' Bell System Logo is used as a dummy character.
44: '''
45: .ie n \{\
46: .tr \(bs-\*(Tr
47: .ds -- \(bs-
48: .if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch
49: .if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch
50: .ds L" ""
51: .ds R" ""
52: .ds L' '
53: .ds R' '
54: 'br\}
55: .el\{\
56: .ds -- \(em\|
57: .tr \*(Tr
58: .ds L" ``
59: .ds R" ''
60: .ds L' `
61: .ds R' '
62: 'br\}
63: .TH PATCH 1 LOCAL
64: .SH NAME
65: patch - a program for applying a diff file to an original
66: .SH SYNOPSIS
67: .B patch
68: [options] orig patchfile [+ [options] orig]
69: .sp
70: but usually just
71: .sp
72: .B patch
73: <patchfile
74: .SH DESCRIPTION
75: .I Patch
76: will take a patch file containing any of the three forms of difference
77: listing produced by the
78: .I diff
79: program and apply those differences to an original file, producing a patched
80: version.
81: By default, the patched version is put in place of the original, with
82: the original file backed up to the same name with the
83: extension \*(L".orig\*(R", or as specified by the
84: .B -b
85: switch.
86: You may also specify where you want the output to go with a
87: .B -o
88: switch.
89: If
90: .I patchfile
91: is omitted, or is a hyphen, the patch will be read from standard input.
92: .PP
93: Upon startup, patch will attempt to determine the type of the diff listing,
94: unless over-ruled by a
95: .BR -c ,
96: .BR -e ,
97: or
98: .B -n
99: switch.
100: Context diffs and normal diffs are applied by the
101: .I patch
102: program itself, while ed diffs are simply fed to the
103: .I ed
104: editor via a pipe.
105: .PP
106: .I Patch
107: will try to skip any leading garbage, apply the diff,
108: and then skip any trailing garbage.
109: Thus you could feed an article or message containing a
110: diff listing to
111: .IR patch ,
112: and it should work.
113: If the entire diff is indented by a consistent amount,
114: this will be taken into account.
115: .PP
116: With context diffs, and to a lesser extent with normal diffs,
117: .I patch
118: can detect when the line numbers mentioned in the patch are incorrect,
119: and will attempt to find the correct place to apply each hunk of the patch.
120: As a first guess, it takes the line number mentioned for the hunk, plus or
121: minus any offset used in applying the previous hunk.
122: If that is not the correct place,
123: .I patch
124: will scan both forwards and backwards for a set of lines matching the context
125: given in the hunk.
126: First
127: .I patch
128: looks for a place where all lines of the context match.
129: If no such place is found, and it's a context diff, and the maximum fuzz factor
130: is set to 1 or more, then another scan takes place ignoring the first and last
131: line of context.
132: If that fails, and the maximum fuzz factor is set to 2 or more,
133: the first two and last two lines of context are ignored,
134: and another scan is made.
135: (The default maximum fuzz factor is 2.)
136: If
137: .I patch
138: cannot find a place to install that hunk of the patch, it will put the
139: hunk out to a reject file, which normally is the name of the output file
140: plus \*(L".rej\*(R".
141: (Note that the rejected hunk will come out in context diff form whether the
142: input patch was a context diff or a normal diff.
143: If the input was a normal diff, many of the contexts will simply be null.)
144: The line numbers on the hunks in the reject file may be different than
145: in the patch file: they reflect the approximate location patch thinks the
146: failed hunks belong in the new file rather than the old one.
147: .PP
148: As each hunk is completed, you will be told whether the hunk succeeded or
149: failed, and which line (in the new file)
150: .I patch
151: thought the hunk should go on.
152: If this is different from the line number specified in the diff you will
153: be told the offset.
154: A single large offset MAY be an indication that a hunk was installed in the
155: wrong place.
156: You will also be told if a fuzz factor was used to make the match, in which
157: case you should also be slightly suspicious.
158: .PP
159: If no original file is specified on the command line,
160: .I patch
161: will try to figure out from the leading garbage what the name of the file
162: to edit is.
163: In the header of a context diff, the filename is found from lines beginning
164: with \*(L"***\*(R" or \*(L"---\*(R", with the shortest name of an existing
165: file winning.
166: Only context diffs have lines like that, but if there is an \*(L"Index:\*(R"
167: line in the leading garbage,
168: .I patch
169: will try to use the filename from that line.
170: The context diff header takes precedence over an Index line.
171: If no filename can be intuited from the leading garbage, you will be asked
172: for the name of the file to patch.
173: .PP
174: (If the original file cannot be found, but a suitable SCCS or RCS file is
175: handy,
176: .I patch
177: will attempt to get or check out the file.)
178: .PP
179: Additionally, if the leading garbage contains a \*(L"Prereq: \*(R" line,
180: .I patch
181: will take the first word from the prerequisites line (normally a version
182: number) and check the input file to see if that word can be found.
183: If not,
184: .I patch
185: will ask for confirmation before proceeding.
186: .PP
187: The upshot of all this is that you should be able to say, while in a news
188: interface, the following:
189: .Sp
190: | patch -d /usr/src/local/blurfl
191: .Sp
192: and patch a file in the blurfl directory directly from the article containing
193: the patch.
194: .PP
195: If the patch file contains more than one patch,
196: .I patch
197: will try to apply each of them as if they came from separate patch files.
198: This means, among other things, that it is assumed that the name of the file
199: to patch must be determined for each diff listing,
200: and that the garbage before each diff listing will
201: be examined for interesting things such as filenames and revision level, as
202: mentioned previously.
203: You can give switches (and another original file name) for the second and
204: subsequent patches by separating the corresponding argument lists
205: by a \*(L'+\*(R'.
206: (The argument list for a second or subsequent patch may not specify a new
207: patch file, however.)
208: .PP
209: .I Patch
210: recognizes the following switches:
211: .TP 5
212: .B \-b
213: causes the next argument to be interpreted as the backup extension, to be
214: used in place of \*(L".orig\*(R".
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 \-f
242: forces
243: .I patch
244: to assume that the user knows exactly what he or she is doing, and to not
245: ask any questions.
246: It does not suppress commentary, however.
247: Use
248: .B \-s
249: for that.
250: .TP 5
251: .B \-F<number>
252: sets the maximum fuzz factor.
253: This switch only applied to context diffs, and causes
254: .I patch
255: to ignore up to that many lines in looking for places to install a hunk.
256: Note that a larger fuzz factor increases the odds of a faulty patch.
257: The default fuzz factor is 2, and it may not be set to more than
258: the number of lines of context in the context diff, ordinarily 3.
259: .TP 5
260: .B \-l
261: causes the pattern matching to be done loosely, in case the tabs and
262: spaces have been munged in your input file.
263: Any sequence of whitespace in the pattern line will match any sequence
264: in the input file.
265: Normal characters must still match exactly.
266: Each line of the context must still match a line in the input file.
267: .TP 5
268: .B \-n
269: forces
270: .I patch
271: to interpret the patch file as a normal diff.
272: .TP 5
273: .B \-N
274: causes
275: .I patch
276: to ignore patches that it thinks are reversed or already applied.
277: See also
278: .B \-R .
279: .TP 5
280: .B \-o
281: causes the next argument to be interpreted as the output file name.
282: .TP 5
283: .B \-p<number>
284: sets the pathname strip count,
285: which controls how pathnames found in the patch file are treated, in case
286: the you keep your files in a different directory than the person who sent
287: out the patch.
288: The strip count specifies how many backslashes are to be stripped from
289: the front of the pathname.
290: (Any intervening directory names also go away.)
291: For example, supposing the filename in the patch file was
292: .sp
293: /u/howard/src/blurfl/blurfl.c
294: .sp
295: setting
296: .B \-p
297: or
298: .B \-p0
299: gives the entire pathname unmodified,
300: .B \-p1
301: gives
302: .sp
303: u/howard/src/blurfl/blurfl.c
304: .sp
305: without the leading slash,
306: .B \-p4
307: gives
308: .sp
309: blurfl/blurfl.c
310: .sp
311: and not specifying
312: .B \-p
313: at all just gives you "blurfl.c".
314: Whatever you end up with is looked for either in the current directory,
315: or the directory specified by the
316: .B \-d
317: switch.
318: .TP 5
319: .B \-r
320: causes the next argument to be interpreted as the reject file name.
321: .TP 5
322: .B \-R
323: tells
324: .I patch
325: that this patch was created with the old and new files swapped.
326: (Yes, I'm afraid that does happen occasionally, human nature being what it
327: is.)
328: .I Patch
329: will attempt to swap each hunk around before applying it.
330: Rejects will come out in the swapped format.
331: The
332: .B \-R
333: switch will not work with ed diff scripts because there is too little
334: information to reconstruct the reverse operation.
335: .Sp
336: If the first hunk of a patch fails,
337: .I patch
338: will reverse the hunk to see if it can be applied that way.
339: If it can, you will be asked if you want to have the
340: .B \-R
341: switch set.
342: If it can't, the patch will continue to be applied normally.
343: (Note: this method cannot detect a reversed patch if it is a normal diff
344: and if the first command is an append (i.e. it should have been a delete)
345: since appends always succeed, due to the fact that a null context will match
346: anywhere.
347: Luckily, most patches add or change lines rather than delete them, so most
348: reversed normal diffs will begin with a delete, which will fail, triggering
349: the heuristic.)
350: .TP 5
351: .B \-s
352: makes
353: .I patch
354: do its work silently, unless an error occurs.
355: .TP 5
356: .B \-S
357: causes
358: .I patch
359: to ignore this patch from the patch file, but continue on looking
360: for the next patch in the file.
361: Thus
362: .sp
363: patch -S + -S + <patchfile
364: .sp
365: will ignore the first and second of three patches.
366: .TP 5
367: .B \-v
368: causes
369: .I patch
370: to print out it's revision header and patch level.
371: .TP 5
372: .B \-x<number>
373: sets internal debugging flags, and is of interest only to
374: .I patch
375: patchers.
376: .SH ENVIRONMENT
377: No environment variables are used by
378: .IR patch .
379: .SH FILES
380: /tmp/patch*
381: .SH SEE ALSO
382: diff(1)
383: .SH NOTES FOR PATCH SENDERS
384: There are several things you should bear in mind if you are going to
385: be sending out patches.
386: First, you can save people a lot of grief by keeping a patchlevel.h file
387: which is patched to increment the patch level as the first diff in the
388: patch file you send out.
389: If you put a Prereq: line in with the patch, it won't let them apply
390: patches out of order without some warning.
391: Second, make sure you've specified the filenames right, either in a
392: context diff header, or with an Index: line.
393: If you are patching something in a subdirectory, be sure to tell the patch
394: user to specify a
395: .B \-p
396: switch as needed.
397: Third, you can create a file by sending out a diff that compares a
398: null file to the file you want to create.
399: This will only work if the file you want to create doesn't exist already in
400: the target directory.
401: Fourth, take care not to send out reversed patches, since it makes people wonder
402: whether they already applied the patch.
403: Fifth, while you may be able to get away with putting 582 diff listings into
404: one file, it is probably wiser to group related patches into separate files in
405: case something goes haywire.
406: .SH DIAGNOSTICS
407: Too many to list here, but generally indicative that
408: .I patch
409: couldn't parse your patch file.
410: .PP
411: The message \*(L"Hmm...\*(R" indicates that there is unprocessed text in
412: the patch file and that
413: .I patch
414: is attempting to intuit whether there is a patch in that text and, if so,
415: what kind of patch it is.
416: .SH CAVEATS
417: .I Patch
418: cannot tell if the line numbers are off in an ed script, and can only detect
419: bad line numbers in a normal diff when it finds a \*(L"change\*(R" or
420: a \*(L"delete\*(R" command.
421: A context diff using fuzz factor 3 may have the same problem.
422: Until a suitable interactive interface is added, you should probably do
423: a context diff in these cases to see if the changes made sense.
424: Of course, compiling without errors is a pretty good indication that the patch
425: worked, but not always.
426: .PP
427: .I Patch
428: usually produces the correct results, even when it has to do a lot of
429: guessing.
430: However, the results are guaranteed to be correct only when the patch is
431: applied to exactly the same version of the file that the patch was
432: generated from.
433: .SH BUGS
434: Could be smarter about partial matches, excessively \&deviant offsets and
435: swapped code, but that would take an extra pass.
436: .PP
437: If code has been duplicated (for instance with #ifdef OLDCODE ... #else ...
438: #endif),
439: .I patch
440: is incapable of patching both versions, and, if it works at all, will likely
441: patch the wrong one, and tell you that it succeeded to boot.
442: .PP
443: If you apply a patch you've already applied,
444: .I patch
445: will think it is a reversed patch, and offer to un-apply the patch.
446: This could be construed as a feature.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.