0
|
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 }` ''
|