Commit | Line | Data |
---|---|---|
055d27ab WJ |
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. |