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