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