xref: /minix3/usr.bin/patch/patch.1 (revision 0a6a1f1d05b60e214de2f05a7310ddd1f0e590e7)
1757e8328SLionel Sambuc.\"	$OpenBSD: patch.1,v 1.22 2008/06/06 20:44:00 jmc Exp $
2757e8328SLionel Sambuc.\"	$DragonFly: src/usr.bin/patch/patch.1,v 1.10 2008/08/18 19:15:55 joerg Exp $
3*0a6a1f1dSLionel Sambuc.\"	$NetBSD: patch.1,v 1.19 2015/08/02 12:19:12 wiz Exp $
4757e8328SLionel Sambuc.\" Copyright 1986, Larry Wall
5757e8328SLionel Sambuc.\"
6757e8328SLionel Sambuc.\" Redistribution and use in source and binary forms, with or without
7757e8328SLionel Sambuc.\" modification, are permitted provided that the following condition
8757e8328SLionel Sambuc.\" is met:
9757e8328SLionel Sambuc.\"  1. Redistributions of source code must retain the above copyright
10757e8328SLionel Sambuc.\"     notice, this condition and the following disclaimer.
11757e8328SLionel Sambuc.\"
12757e8328SLionel Sambuc.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
13757e8328SLionel Sambuc.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14757e8328SLionel Sambuc.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15757e8328SLionel Sambuc.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
16757e8328SLionel Sambuc.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
17757e8328SLionel Sambuc.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
18757e8328SLionel Sambuc.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19757e8328SLionel Sambuc.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
20757e8328SLionel Sambuc.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
21757e8328SLionel Sambuc.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
22757e8328SLionel Sambuc.\" SUCH DAMAGE.
23757e8328SLionel Sambuc.\"
24*0a6a1f1dSLionel Sambuc.Dd August 2, 2015
25757e8328SLionel Sambuc.Dt PATCH 1
26757e8328SLionel Sambuc.Os
27757e8328SLionel Sambuc.Sh NAME
28757e8328SLionel Sambuc.Nm patch
29757e8328SLionel Sambuc.Nd apply a diff file to an original
30757e8328SLionel Sambuc.Sh SYNOPSIS
31757e8328SLionel Sambuc.Nm
32757e8328SLionel Sambuc.Op Fl bCcEeflNnRstuv
33757e8328SLionel Sambuc.Op Fl B Ar backup-prefix
34757e8328SLionel Sambuc.Op Fl D Ar symbol
35757e8328SLionel Sambuc.Op Fl d Ar directory
36757e8328SLionel Sambuc.Op Fl F Ar max-fuzz
37757e8328SLionel Sambuc.Op Fl i Ar patchfile
38757e8328SLionel Sambuc.Op Fl o Ar out-file
39757e8328SLionel Sambuc.Op Fl p Ar strip-count
40757e8328SLionel Sambuc.Op Fl r Ar rej-name
41*0a6a1f1dSLionel Sambuc.Op Fl V Cm t | nil | never | none
42757e8328SLionel Sambuc.Op Fl x Ar number
43757e8328SLionel Sambuc.Op Fl z Ar backup-ext
44757e8328SLionel Sambuc.Op Fl Fl posix
45757e8328SLionel Sambuc.Op Ar origfile Op Ar patchfile
46757e8328SLionel Sambuc.Nm
47757e8328SLionel Sambuc.Pf \*(Lt Ar patchfile
48757e8328SLionel Sambuc.Sh DESCRIPTION
49757e8328SLionel Sambuc.Nm
50757e8328SLionel Sambucwill take a patch file containing any of the four forms of difference
51757e8328SLionel Sambuclisting produced by the
52757e8328SLionel Sambuc.Xr diff 1
53757e8328SLionel Sambucprogram and apply those differences to an original file,
54757e8328SLionel Sambucproducing a patched version.
55757e8328SLionel SambucIf
56757e8328SLionel Sambuc.Ar patchfile
57757e8328SLionel Sambucis omitted, or is a hyphen, the patch will be read from the standard input.
58757e8328SLionel Sambuc.Pp
59757e8328SLionel Sambuc.Nm
60757e8328SLionel Sambucwill attempt to determine the type of the diff listing, unless over-ruled by a
61757e8328SLionel Sambuc.Fl c ,
62757e8328SLionel Sambuc.Fl e ,
63757e8328SLionel Sambuc.Fl n ,
64757e8328SLionel Sambucor
65757e8328SLionel Sambuc.Fl u
66757e8328SLionel Sambucoption.
67757e8328SLionel SambucContext diffs (old-style, new-style, and unified) and
68757e8328SLionel Sambucnormal diffs are applied directly by the
69757e8328SLionel Sambuc.Nm
70757e8328SLionel Sambucprogram itself, whereas ed diffs are simply fed to the
71757e8328SLionel Sambuc.Xr ed 1
72757e8328SLionel Sambuceditor via a pipe.
73757e8328SLionel Sambuc.Pp
74757e8328SLionel SambucIf the
75757e8328SLionel Sambuc.Ar patchfile
76757e8328SLionel Sambuccontains more than one patch,
77757e8328SLionel Sambuc.Nm
78757e8328SLionel Sambucwill try to apply each of them as if they came from separate patch files.
79757e8328SLionel SambucThis means, among other things, that it is assumed that the name of the file
80757e8328SLionel Sambucto patch must be determined for each diff listing, and that the garbage before
81757e8328SLionel Sambuceach diff listing will be examined for interesting things such as file names
82757e8328SLionel Sambucand revision level (see the section on
83757e8328SLionel Sambuc.Sx Filename Determination
84757e8328SLionel Sambucbelow).
85757e8328SLionel Sambuc.Pp
86757e8328SLionel SambucThe options are as follows:
87757e8328SLionel Sambuc.Bl -tag -width Ds
88757e8328SLionel Sambuc.It Fl B Ar backup-prefix , Fl Fl prefix Ar backup-prefix
89757e8328SLionel SambucCauses the next argument to be interpreted as a prefix to the backup file
90757e8328SLionel Sambucname.
91757e8328SLionel SambucIf this argument is specified, any argument to
92757e8328SLionel Sambuc.Fl z
93757e8328SLionel Sambucwill be ignored.
94757e8328SLionel Sambuc.It Fl b , Fl Fl backup
95757e8328SLionel SambucSave a backup copy of the file before it is modified.
96757e8328SLionel SambucBy default the original file is saved with a backup extension of
97757e8328SLionel Sambuc.Qq .orig
98757e8328SLionel Sambucunless the file already has a numbered backup, in which case a numbered
99757e8328SLionel Sambucbackup is made.
100757e8328SLionel SambucThis is equivalent to specifying
101757e8328SLionel Sambuc.Qo Fl V Cm existing Qc .
102757e8328SLionel SambucThis option is currently the default, unless
103757e8328SLionel Sambuc.Fl -posix
104757e8328SLionel Sambucis specified.
105757e8328SLionel Sambuc.It Fl C , Fl Fl check
106757e8328SLionel SambucChecks that the patch would apply cleanly, but does not modify anything.
107757e8328SLionel Sambuc.It Fl c , Fl Fl context
108757e8328SLionel SambucForces
109757e8328SLionel Sambuc.Nm
110757e8328SLionel Sambucto interpret the patch file as a context diff.
111757e8328SLionel Sambuc.It Fl D Ar symbol , Fl Fl ifdef Ar symbol
112757e8328SLionel SambucCauses
113757e8328SLionel Sambuc.Nm
114757e8328SLionel Sambucto use the
115757e8328SLionel Sambuc.Qq #ifdef...#endif
116757e8328SLionel Sambucconstruct to mark changes.
117757e8328SLionel SambucThe argument following will be used as the differentiating symbol.
118757e8328SLionel SambucNote that, unlike the C compiler, there must be a space between the
119757e8328SLionel Sambuc.Fl D
120757e8328SLionel Sambucand the argument.
121757e8328SLionel Sambuc.It Fl d Ar directory , Fl Fl directory Ar directory
122757e8328SLionel SambucCauses
123757e8328SLionel Sambuc.Nm
124757e8328SLionel Sambucto interpret the next argument as a directory,
125757e8328SLionel Sambucand change the working directory to it before doing anything else.
126757e8328SLionel Sambuc.It Fl E , Fl Fl remove-empty-files
127757e8328SLionel SambucCauses
128757e8328SLionel Sambuc.Nm
129757e8328SLionel Sambucto remove output files that are empty after the patches have been applied.
130757e8328SLionel SambucThis option is useful when applying patches that create or remove files.
131757e8328SLionel Sambuc.It Fl e , Fl Fl ed
132757e8328SLionel SambucForces
133757e8328SLionel Sambuc.Nm
134757e8328SLionel Sambucto interpret the patch file as an
135757e8328SLionel Sambuc.Xr ed 1
136757e8328SLionel Sambucscript.
137757e8328SLionel Sambuc.It Fl F Ar max-fuzz , Fl Fl fuzz Ar max-fuzz
138757e8328SLionel SambucSets the maximum fuzz factor.
139757e8328SLionel SambucThis option only applies to context diffs, and causes
140757e8328SLionel Sambuc.Nm
141757e8328SLionel Sambucto ignore up to that many lines in looking for places to install a hunk.
142757e8328SLionel SambucNote that a larger fuzz factor increases the odds of a faulty patch.
143757e8328SLionel SambucThe default fuzz factor is 2, and it may not be set to more than
144757e8328SLionel Sambucthe number of lines of context in the context diff, ordinarily 3.
145757e8328SLionel Sambuc.It Fl f , Fl Fl force
146757e8328SLionel SambucForces
147757e8328SLionel Sambuc.Nm
148757e8328SLionel Sambucto assume that the user knows exactly what he or she is doing, and to not
149757e8328SLionel Sambucask any questions.
150757e8328SLionel SambucIt assumes the following:
151757e8328SLionel Sambucskip patches for which a file to patch can't be found;
152757e8328SLionel Sambucpatch files even though they have the wrong version for the
153757e8328SLionel Sambuc.Qq Prereq:
154757e8328SLionel Sambucline in the patch;
155757e8328SLionel Sambucand assume that patches are not reversed even if they look like they are.
156757e8328SLionel SambucThis option does not suppress commentary; use
157757e8328SLionel Sambuc.Fl s
158757e8328SLionel Sambucfor that.
159757e8328SLionel Sambuc.It Fl i Ar patchfile , Fl Fl input Ar patchfile
160757e8328SLionel SambucCauses the next argument to be interpreted as the input file name
161757e8328SLionel Sambuc(i.e., a patchfile).
162757e8328SLionel SambucThis option may be specified multiple times.
163757e8328SLionel Sambuc.It Fl l , Fl Fl ignore-whitespace
164757e8328SLionel SambucCauses the pattern matching to be done loosely, in case the tabs and
165757e8328SLionel Sambucspaces have been munged in your input file.
166757e8328SLionel SambucAny sequence of whitespace in the pattern line will match any sequence
167757e8328SLionel Sambucin the input file.
168757e8328SLionel SambucNormal characters must still match exactly.
169757e8328SLionel SambucEach line of the context must still match a line in the input file.
170757e8328SLionel Sambuc.It Fl N , Fl Fl forward
171757e8328SLionel SambucCauses
172757e8328SLionel Sambuc.Nm
173757e8328SLionel Sambucto ignore patches that it thinks are reversed or already applied.
174757e8328SLionel SambucSee also
175757e8328SLionel Sambuc.Fl R .
176757e8328SLionel Sambuc.It Fl n , Fl Fl normal
177757e8328SLionel SambucForces
178757e8328SLionel Sambuc.Nm
179757e8328SLionel Sambucto interpret the patch file as a normal diff.
180757e8328SLionel Sambuc.It Fl o Ar out-file , Fl Fl output Ar out-file
181757e8328SLionel SambucCauses the next argument to be interpreted as the output file name.
182757e8328SLionel Sambuc.It Fl p Ar strip-count , Fl Fl strip Ar strip-count
183757e8328SLionel SambucSets the pathname strip count,
184757e8328SLionel Sambucwhich controls how pathnames found in the patch file are treated,
185757e8328SLionel Sambucin case you keep your files in a different directory than the person who sent
186757e8328SLionel Sambucout the patch.
187757e8328SLionel SambucThe strip count specifies how many slashes are to be stripped from
188757e8328SLionel Sambucthe front of the pathname.
189757e8328SLionel Sambuc(Any intervening directory names also go away.)
190757e8328SLionel SambucFor example, supposing the file name in the patch file was
191757e8328SLionel Sambuc.Pa /u/howard/src/blurfl/blurfl.c :
192757e8328SLionel Sambuc.Pp
193757e8328SLionel SambucSetting
194757e8328SLionel Sambuc.Fl p Ns Ar 0
195757e8328SLionel Sambucgives the entire pathname unmodified.
196757e8328SLionel Sambuc.Pp
197757e8328SLionel Sambuc.Fl p Ns Ar 1
198757e8328SLionel Sambucgives
199757e8328SLionel Sambuc.Pp
200757e8328SLionel Sambuc.D1 Pa u/howard/src/blurfl/blurfl.c
201757e8328SLionel Sambuc.Pp
202757e8328SLionel Sambucwithout the leading slash.
203757e8328SLionel Sambuc.Pp
204757e8328SLionel Sambuc.Fl p Ns Ar 4
205757e8328SLionel Sambucgives
206757e8328SLionel Sambuc.Pp
207757e8328SLionel Sambuc.D1 Pa blurfl/blurfl.c
208757e8328SLionel Sambuc.Pp
209757e8328SLionel SambucNot specifying
210757e8328SLionel Sambuc.Fl p
211757e8328SLionel Sambucat all just gives you
212757e8328SLionel Sambuc.Pa blurfl.c ,
213757e8328SLionel Sambucunless all of the directories in the leading path
214757e8328SLionel Sambuc.Pq Pa u/howard/src/blurfl
215757e8328SLionel Sambucexist and that path is relative,
216757e8328SLionel Sambucin which case you get the entire pathname unmodified.
217757e8328SLionel SambucWhatever you end up with is looked for either in the current directory,
218757e8328SLionel Sambucor the directory specified by the
219757e8328SLionel Sambuc.Fl d
220757e8328SLionel Sambucoption.
221757e8328SLionel Sambuc.It Fl R , Fl Fl reverse
222757e8328SLionel SambucTells
223757e8328SLionel Sambuc.Nm
224757e8328SLionel Sambucthat this patch was created with the old and new files swapped.
225757e8328SLionel Sambuc(Yes, I'm afraid that does happen occasionally, human nature being what it
226757e8328SLionel Sambucis.)
227757e8328SLionel Sambuc.Nm
228757e8328SLionel Sambucwill attempt to swap each hunk around before applying it.
229757e8328SLionel SambucRejects will come out in the swapped format.
230757e8328SLionel SambucThe
231757e8328SLionel Sambuc.Fl R
232757e8328SLionel Sambucoption will not work with ed diff scripts because there is too little
233757e8328SLionel Sambucinformation to reconstruct the reverse operation.
234757e8328SLionel Sambuc.Pp
235757e8328SLionel SambucIf the first hunk of a patch fails,
236757e8328SLionel Sambuc.Nm
237757e8328SLionel Sambucwill reverse the hunk to see if it can be applied that way.
238757e8328SLionel SambucIf it can, you will be asked if you want to have the
239757e8328SLionel Sambuc.Fl R
240757e8328SLionel Sambucoption set.
241757e8328SLionel SambucIf it can't, the patch will continue to be applied normally.
242757e8328SLionel Sambuc(Note: this method cannot detect a reversed patch if it is a normal diff
243757e8328SLionel Sambucand if the first command is an append (i.e., it should have been a delete)
244757e8328SLionel Sambucsince appends always succeed, due to the fact that a null context will match
245757e8328SLionel Sambucanywhere.
246757e8328SLionel SambucLuckily, most patches add or change lines rather than delete them, so most
247757e8328SLionel Sambucreversed normal diffs will begin with a delete, which will fail, triggering
248757e8328SLionel Sambucthe heuristic.)
249757e8328SLionel Sambuc.It Fl r Ar rej-name , Fl Fl reject-file Ar rej-name
250757e8328SLionel SambucCauses the next argument to be interpreted as the reject file name.
251757e8328SLionel Sambuc.It Fl s , Fl Fl quiet , Fl Fl silent
252757e8328SLionel SambucMakes
253757e8328SLionel Sambuc.Nm
254757e8328SLionel Sambucdo its work silently, unless an error occurs.
255757e8328SLionel Sambuc.It Fl t , Fl Fl batch
256757e8328SLionel SambucSimilar to
257757e8328SLionel Sambuc.Fl f ,
258757e8328SLionel Sambucin that it suppresses questions, but makes some different assumptions:
259757e8328SLionel Sambucskip patches for which a file to patch can't be found (the same as
260757e8328SLionel Sambuc.Fl f ) ;
261757e8328SLionel Sambucskip patches for which the file has the wrong version for the
262757e8328SLionel Sambuc.Qq Prereq:
263757e8328SLionel Sambucline in the patch;
264757e8328SLionel Sambucand assume that patches are reversed if they look like they are.
265757e8328SLionel Sambuc.It Fl u , Fl Fl unified
266757e8328SLionel SambucForces
267757e8328SLionel Sambuc.Nm
268757e8328SLionel Sambucto interpret the patch file as a unified context diff (a unidiff).
269*0a6a1f1dSLionel Sambuc.It Fl V Cm t | nil | never | none , Fl Fl version-control Cm t | nil | never | none
270757e8328SLionel SambucCauses the next argument to be interpreted as a method for creating
271757e8328SLionel Sambucbackup file names.
272757e8328SLionel SambucThe type of backups made can also be given in the
273757e8328SLionel Sambuc.Ev PATCH_VERSION_CONTROL
274757e8328SLionel Sambucor
275757e8328SLionel Sambuc.Ev VERSION_CONTROL
276757e8328SLionel Sambucenvironment variables, which are overridden by this option.
277757e8328SLionel SambucThe
278757e8328SLionel Sambuc.Fl B
279757e8328SLionel Sambucoption overrides this option, causing the prefix to always be used for
280757e8328SLionel Sambucmaking backup file names.
281757e8328SLionel SambucThe values of the
282757e8328SLionel Sambuc.Ev PATCH_VERSION_CONTROL
283757e8328SLionel Sambucand
284757e8328SLionel Sambuc.Ev VERSION_CONTROL
285757e8328SLionel Sambucenvironment variables and the argument to the
286757e8328SLionel Sambuc.Fl V
287757e8328SLionel Sambucoption are like the GNU Emacs
288757e8328SLionel Sambuc.Dq version-control
289757e8328SLionel Sambucvariable; they also recognize synonyms that are more descriptive.
290757e8328SLionel SambucThe valid values are (unique abbreviations are accepted):
291757e8328SLionel Sambuc.Bl -tag -width Ds -offset indent
292757e8328SLionel Sambuc.It Cm t , numbered
293757e8328SLionel SambucAlways make numbered backups.
294757e8328SLionel Sambuc.It Cm nil , existing
295757e8328SLionel SambucMake numbered backups of files that already have them,
296757e8328SLionel Sambucsimple backups of the others.
297757e8328SLionel Sambuc.It Cm never , simple
298757e8328SLionel SambucAlways make simple backups.
299757e8328SLionel Sambuc.El
300757e8328SLionel Sambuc.It Fl v , Fl Fl version
301757e8328SLionel SambucCauses
302757e8328SLionel Sambuc.Nm
303757e8328SLionel Sambucto print out its revision header and patch level.
304757e8328SLionel Sambuc.It Fl x Ar number , Fl Fl debug Ar number
305757e8328SLionel SambucSets internal debugging flags, and is of interest only to
306757e8328SLionel Sambuc.Nm
307757e8328SLionel Sambucpatchers.
308757e8328SLionel Sambuc.It Fl z Ar backup-ext , Fl Fl suffix Ar backup-ext
309757e8328SLionel SambucCauses the next argument to be interpreted as the backup extension, to be
310757e8328SLionel Sambucused in place of
311757e8328SLionel Sambuc.Qq .orig .
312757e8328SLionel Sambuc.It Fl Fl posix
313757e8328SLionel SambucEnables strict
314757e8328SLionel Sambuc.St -p1003.1-2004
315757e8328SLionel Sambucconformance, specifically:
316757e8328SLionel Sambuc.Bl -enum
317757e8328SLionel Sambuc.It
318757e8328SLionel SambucBackup files are not created unless the
319757e8328SLionel Sambuc.Fl b
320757e8328SLionel Sambucoption is specified.
321757e8328SLionel Sambuc.It
322757e8328SLionel SambucIf unspecified, the file name used is the first of the old, new and
323757e8328SLionel Sambucindex files that exists.
324757e8328SLionel Sambuc.El
325757e8328SLionel Sambuc.El
326757e8328SLionel Sambuc.Ss Patch Application
327757e8328SLionel Sambuc.Nm
328757e8328SLionel Sambucwill try to skip any leading garbage, apply the diff,
329757e8328SLionel Sambucand then skip any trailing garbage.
330757e8328SLionel SambucThus you could feed an article or message containing a
331757e8328SLionel Sambucdiff listing to
332757e8328SLionel Sambuc.Nm ,
333757e8328SLionel Sambucand it should work.
334757e8328SLionel SambucIf the entire diff is indented by a consistent amount,
335757e8328SLionel Sambucthis will be taken into account.
336757e8328SLionel Sambuc.Pp
337757e8328SLionel SambucWith context diffs, and to a lesser extent with normal diffs,
338757e8328SLionel Sambuc.Nm
339757e8328SLionel Sambuccan detect when the line numbers mentioned in the patch are incorrect,
340757e8328SLionel Sambucand will attempt to find the correct place to apply each hunk of the patch.
341757e8328SLionel SambucAs a first guess, it takes the line number mentioned for the hunk, plus or
342757e8328SLionel Sambucminus any offset used in applying the previous hunk.
343757e8328SLionel SambucIf that is not the correct place,
344757e8328SLionel Sambuc.Nm
345757e8328SLionel Sambucwill scan both forwards and backwards for a set of lines matching the context
346757e8328SLionel Sambucgiven in the hunk.
347757e8328SLionel SambucFirst
348757e8328SLionel Sambuc.Nm
349757e8328SLionel Sambuclooks for a place where all lines of the context match.
350757e8328SLionel SambucIf no such place is found, and it's a context diff, and the maximum fuzz factor
351757e8328SLionel Sambucis set to 1 or more, then another scan takes place ignoring the first and last
352757e8328SLionel Sambucline of context.
353757e8328SLionel SambucIf that fails, and the maximum fuzz factor is set to 2 or more,
354757e8328SLionel Sambucthe first two and last two lines of context are ignored,
355757e8328SLionel Sambucand another scan is made.
356757e8328SLionel Sambuc.Pq The default maximum fuzz factor is 2.
357757e8328SLionel Sambuc.Pp
358757e8328SLionel SambucIf
359757e8328SLionel Sambuc.Nm
360757e8328SLionel Sambuccannot find a place to install that hunk of the patch, it will put the hunk
361757e8328SLionel Sambucout to a reject file, which normally is the name of the output file plus
362757e8328SLionel Sambuc.Qq .rej .
363757e8328SLionel Sambuc(Note that the rejected hunk will come out in context diff form whether the
364757e8328SLionel Sambucinput patch was a context diff or a normal diff.
365757e8328SLionel SambucIf the input was a normal diff, many of the contexts will simply be null.)
366757e8328SLionel SambucThe line numbers on the hunks in the reject file may be different than
367757e8328SLionel Sambucin the patch file: they reflect the approximate location patch thinks the
368757e8328SLionel Sambucfailed hunks belong in the new file rather than the old one.
369757e8328SLionel Sambuc.Pp
370757e8328SLionel SambucAs each hunk is completed, you will be told whether the hunk succeeded or
371757e8328SLionel Sambucfailed, and which line (in the new file)
372757e8328SLionel Sambuc.Nm
373757e8328SLionel Sambucthought the hunk should go on.
374757e8328SLionel SambucIf this is different from the line number specified in the diff,
375757e8328SLionel Sambucyou will be told the offset.
376757e8328SLionel SambucA single large offset MAY be an indication that a hunk was installed in the
377757e8328SLionel Sambucwrong place.
378757e8328SLionel SambucYou will also be told if a fuzz factor was used to make the match, in which
379757e8328SLionel Sambuccase you should also be slightly suspicious.
380757e8328SLionel Sambuc.Ss Filename Determination
381757e8328SLionel SambucIf no original file is specified on the command line,
382757e8328SLionel Sambuc.Nm
383757e8328SLionel Sambucwill try to figure out from the leading garbage what the name of the file
384757e8328SLionel Sambucto edit is.
385757e8328SLionel SambucWhen checking a prospective file name, pathname components are stripped
386757e8328SLionel Sambucas specified by the
387757e8328SLionel Sambuc.Fl p
388757e8328SLionel Sambucoption and the file's existence and writability are checked relative
389757e8328SLionel Sambucto the current working directory (or the directory specified by the
390757e8328SLionel Sambuc.Fl d
391757e8328SLionel Sambucoption).
392757e8328SLionel Sambuc.Pp
393757e8328SLionel SambucIf the diff is a context or unified diff,
394757e8328SLionel Sambuc.Nm
395757e8328SLionel Sambucis able to determine the old and new file names from the diff header.
396757e8328SLionel SambucFor context diffs, the
397757e8328SLionel Sambuc.Dq old
398757e8328SLionel Sambucfile is specified in the line beginning with
399757e8328SLionel Sambuc.Qq ***
400757e8328SLionel Sambucand the
401757e8328SLionel Sambuc.Dq new
402757e8328SLionel Sambucfile is specified in the line beginning with
403757e8328SLionel Sambuc.Qq --- .
404757e8328SLionel SambucFor a unified diff, the
405757e8328SLionel Sambuc.Dq old
406757e8328SLionel Sambucfile is specified in the line beginning with
407757e8328SLionel Sambuc.Qq ---
408757e8328SLionel Sambucand the
409757e8328SLionel Sambuc.Dq new
410757e8328SLionel Sambucfile is specified in the line beginning with
411757e8328SLionel Sambuc.Qq +++ .
412757e8328SLionel SambucIf there is an
413757e8328SLionel Sambuc.Qq Index:
414757e8328SLionel Sambucline in the leading garbage (regardless of the diff type),
415757e8328SLionel Sambuc.Nm
416757e8328SLionel Sambucwill use the file name from that line as the
417757e8328SLionel Sambuc.Dq index
418757e8328SLionel Sambucfile.
419757e8328SLionel Sambuc.Pp
420757e8328SLionel Sambuc.Nm
421757e8328SLionel Sambucwill choose the file name by performing the following steps, with the first
422757e8328SLionel Sambucmatch used:
423757e8328SLionel Sambuc.Bl -enum
424757e8328SLionel Sambuc.It
425757e8328SLionel SambucIf
426757e8328SLionel Sambuc.Nm
427757e8328SLionel Sambucis operating in strict
428757e8328SLionel Sambuc.St -p1003.1-2004
429757e8328SLionel Sambucmode, the first of the
430757e8328SLionel Sambuc.Dq old ,
431757e8328SLionel Sambuc.Dq new
432757e8328SLionel Sambucand
433757e8328SLionel Sambuc.Dq index
434757e8328SLionel Sambucfile names that exist is used.
435757e8328SLionel SambucOtherwise,
436757e8328SLionel Sambuc.Nm
437757e8328SLionel Sambucwill examine either the
438757e8328SLionel Sambuc.Dq old
439757e8328SLionel Sambucand
440757e8328SLionel Sambuc.Dq new
441757e8328SLionel Sambucfile names or, for a non-context diff, the
442757e8328SLionel Sambuc.Dq index
443757e8328SLionel Sambucfile name, and choose the file name with the fewest path components,
444757e8328SLionel Sambucthe shortest basename, and the shortest total file name length (in that order).
445757e8328SLionel Sambuc.It
446757e8328SLionel SambucIf no file exists,
447757e8328SLionel Sambuc.Nm
448*0a6a1f1dSLionel Sambucchecks for the existence of the files in an RCS directory using the criteria
449*0a6a1f1dSLionel Sambucspecified above.
450757e8328SLionel SambucIf found,
451757e8328SLionel Sambuc.Nm
452757e8328SLionel Sambucwill attempt to get or check out the file.
453757e8328SLionel Sambuc.It
454757e8328SLionel SambucIf no suitable file was found to patch, the patch file is a context or
455757e8328SLionel Sambucunified diff, and the old file was zero length, the new file name is
456757e8328SLionel Sambuccreated and used.
457757e8328SLionel Sambuc.It
458757e8328SLionel SambucIf the file name still cannot be determined,
459757e8328SLionel Sambuc.Nm
460757e8328SLionel Sambucwill prompt the user for the file name to use.
461757e8328SLionel Sambuc.El
462757e8328SLionel Sambuc.Pp
463757e8328SLionel SambucAdditionally, if the leading garbage contains a
464757e8328SLionel Sambuc.Qq Prereq:\ \&
465757e8328SLionel Sambucline,
466757e8328SLionel Sambuc.Nm
467757e8328SLionel Sambucwill take the first word from the prerequisites line (normally a version
468757e8328SLionel Sambucnumber) and check the input file to see if that word can be found.
469757e8328SLionel SambucIf not,
470757e8328SLionel Sambuc.Nm
471757e8328SLionel Sambucwill ask for confirmation before proceeding.
472757e8328SLionel Sambuc.Pp
473757e8328SLionel SambucThe upshot of all this is that you should be able to say, while in a news
474757e8328SLionel Sambucinterface, the following:
475757e8328SLionel Sambuc.Pp
476757e8328SLionel Sambuc.Dl | patch -d /usr/src/local/blurfl
477757e8328SLionel Sambuc.Pp
478757e8328SLionel Sambucand patch a file in the blurfl directory directly from the article containing
479757e8328SLionel Sambucthe patch.
480757e8328SLionel Sambuc.Ss Backup Files
481757e8328SLionel SambucBy default, the patched version is put in place of the original, with
482757e8328SLionel Sambucthe original file backed up to the same name with the extension
483757e8328SLionel Sambuc.Qq .orig ,
484757e8328SLionel Sambucor as specified by the
485757e8328SLionel Sambuc.Fl B ,
486757e8328SLionel Sambuc.Fl V ,
487757e8328SLionel Sambucor
488757e8328SLionel Sambuc.Fl z
489757e8328SLionel Sambucoptions.
490757e8328SLionel SambucThe extension used for making backup files may also be specified in the
491757e8328SLionel Sambuc.Ev SIMPLE_BACKUP_SUFFIX
492757e8328SLionel Sambucenvironment variable, which is overridden by the options above.
493757e8328SLionel Sambuc.Pp
494757e8328SLionel SambucIf the backup file is a symbolic or hard link to the original file,
495757e8328SLionel Sambuc.Nm
496757e8328SLionel Sambuccreates a new backup file name by changing the first lowercase letter
497757e8328SLionel Sambucin the last component of the file's name into uppercase.
498757e8328SLionel SambucIf there are no more lowercase letters in the name,
499757e8328SLionel Sambucit removes the first character from the name.
500757e8328SLionel SambucIt repeats this process until it comes up with a
501757e8328SLionel Sambucbackup file that does not already exist or is not linked to the original file.
502757e8328SLionel Sambuc.Pp
503757e8328SLionel SambucYou may also specify where you want the output to go with the
504757e8328SLionel Sambuc.Fl o
505757e8328SLionel Sambucoption; if that file already exists, it is backed up first.
506757e8328SLionel Sambuc.Ss Notes For Patch Senders
507757e8328SLionel SambucThere are several things you should bear in mind if you are going to
508757e8328SLionel Sambucbe sending out patches:
509757e8328SLionel Sambuc.Pp
510757e8328SLionel SambucFirst, you can save people a lot of grief by keeping a
511757e8328SLionel Sambuc.Pa patchlevel.h
512757e8328SLionel Sambucfile which is patched to increment the patch level as the first diff in the
513757e8328SLionel Sambucpatch file you send out.
514757e8328SLionel SambucIf you put a
515757e8328SLionel Sambuc.Qq Prereq:
516757e8328SLionel Sambucline in with the patch, it won't let them apply
517757e8328SLionel Sambucpatches out of order without some warning.
518757e8328SLionel Sambuc.Pp
519757e8328SLionel SambucSecond, make sure you've specified the file names right, either in a
520757e8328SLionel Sambuccontext diff header, or with an
521757e8328SLionel Sambuc.Qq Index:
522757e8328SLionel Sambucline.
523757e8328SLionel SambucIf you are patching something in a subdirectory, be sure to tell the patch
524757e8328SLionel Sambucuser to specify a
525757e8328SLionel Sambuc.Fl p
526757e8328SLionel Sambucoption as needed.
527757e8328SLionel Sambuc.Pp
528757e8328SLionel SambucThird, you can create a file by sending out a diff that compares a
529757e8328SLionel Sambucnull file to the file you want to create.
530757e8328SLionel SambucThis will only work if the file you want to create doesn't exist already in
531757e8328SLionel Sambucthe target directory.
532757e8328SLionel Sambuc.Pp
533757e8328SLionel SambucFourth, take care not to send out reversed patches, since it makes people wonder
534757e8328SLionel Sambucwhether they already applied the patch.
535757e8328SLionel Sambuc.Pp
536757e8328SLionel SambucFifth, while you may be able to get away with putting 582 diff listings into
537757e8328SLionel Sambucone file, it is probably wiser to group related patches into separate files in
538757e8328SLionel Sambuccase something goes haywire.
539757e8328SLionel Sambuc.Sh ENVIRONMENT
540757e8328SLionel Sambuc.Bl -tag -width "PATCH_VERSION_CONTROL" -compact
541757e8328SLionel Sambuc.It Ev POSIXLY_CORRECT
542757e8328SLionel SambucWhen set,
543757e8328SLionel Sambuc.Nm
544757e8328SLionel Sambucbehaves as if the
545757e8328SLionel Sambuc.Fl Fl posix
546757e8328SLionel Sambucoption has been specified.
547757e8328SLionel Sambuc.It Ev SIMPLE_BACKUP_SUFFIX
548757e8328SLionel SambucExtension to use for backup file names instead of
549757e8328SLionel Sambuc.Qq .orig .
550757e8328SLionel Sambuc.It Ev TMPDIR
551757e8328SLionel SambucDirectory to put temporary files in; default is
552757e8328SLionel Sambuc.Pa /tmp .
553757e8328SLionel Sambuc.It Ev PATCH_VERSION_CONTROL
554757e8328SLionel SambucSelects when numbered backup files are made.
555757e8328SLionel Sambuc.It Ev VERSION_CONTROL
556757e8328SLionel SambucSame as
557757e8328SLionel Sambuc.Ev PATCH_VERSION_CONTROL .
558757e8328SLionel Sambuc.El
559757e8328SLionel Sambuc.Sh FILES
560757e8328SLionel Sambuc.Bl -tag -width "$TMPDIR/patch*" -compact
561757e8328SLionel Sambuc.It Pa $TMPDIR/patch*
562757e8328SLionel Sambuc.Nm
563757e8328SLionel Sambuctemporary files
564757e8328SLionel Sambuc.It Pa /dev/tty
565757e8328SLionel Sambucused to read input when
566757e8328SLionel Sambuc.Nm
567757e8328SLionel Sambucprompts the user
568757e8328SLionel Sambuc.El
569757e8328SLionel Sambuc.Sh DIAGNOSTICS
570757e8328SLionel SambucToo many to list here, but generally indicative that
571757e8328SLionel Sambuc.Nm
572757e8328SLionel Sambuccouldn't parse your patch file.
573757e8328SLionel Sambuc.Pp
574757e8328SLionel SambucThe message
575757e8328SLionel Sambuc.Qq Hmm...
576757e8328SLionel Sambucindicates that there is unprocessed text in the patch file and that
577757e8328SLionel Sambuc.Nm
578757e8328SLionel Sambucis attempting to intuit whether there is a patch in that text and, if so,
579757e8328SLionel Sambucwhat kind of patch it is.
580757e8328SLionel Sambuc.Pp
581757e8328SLionel SambucThe
582757e8328SLionel Sambuc.Nm
583757e8328SLionel Sambucutility exits with one of the following values:
584757e8328SLionel Sambuc.Pp
585757e8328SLionel Sambuc.Bl -tag -width Ds -compact -offset indent
586757e8328SLionel Sambuc.It \&0
587757e8328SLionel SambucSuccessful completion.
588757e8328SLionel Sambuc.It \&1
589757e8328SLionel SambucOne or more lines were written to a reject file.
590757e8328SLionel Sambuc.It \*[Gt]\&1
591757e8328SLionel SambucAn error occurred.
592757e8328SLionel Sambuc.El
593757e8328SLionel Sambuc.Pp
594757e8328SLionel SambucWhen applying a set of patches in a loop it behooves you to check this
595757e8328SLionel Sambucexit status so you don't apply a later patch to a partially patched file.
596757e8328SLionel Sambuc.Sh SEE ALSO
597757e8328SLionel Sambuc.Xr diff 1
598757e8328SLionel Sambuc.Sh STANDARDS
599757e8328SLionel SambucThe
600757e8328SLionel Sambuc.Nm
601757e8328SLionel Sambucutility is compliant with the
602757e8328SLionel Sambuc.St -p1003.1-2004
603757e8328SLionel Sambucspecification
604757e8328SLionel Sambuc(except as detailed above for the
605757e8328SLionel Sambuc.Fl -posix
606757e8328SLionel Sambucoption),
607757e8328SLionel Sambucthough the presence of
608757e8328SLionel Sambuc.Nm
609757e8328SLionel Sambucitself is optional.
610757e8328SLionel Sambuc.Pp
611757e8328SLionel SambucThe flags
612757e8328SLionel Sambuc.Op Fl CEfstuvBFVxz
613757e8328SLionel Sambucand
614757e8328SLionel Sambuc.Op Fl -posix
615757e8328SLionel Sambucare extensions to that specification.
616757e8328SLionel Sambuc.Sh AUTHORS
617757e8328SLionel Sambuc.An Larry Wall
618757e8328SLionel Sambucwith many other contributors.
619757e8328SLionel Sambuc.Sh CAVEATS
620757e8328SLionel Sambuc.Nm
621757e8328SLionel Sambuccannot tell if the line numbers are off in an ed script, and can only detect
622757e8328SLionel Sambucbad line numbers in a normal diff when it finds a
623757e8328SLionel Sambuc.Qq change
624757e8328SLionel Sambucor a
625757e8328SLionel Sambuc.Qq delete
626757e8328SLionel Sambuccommand.
627757e8328SLionel SambucA context diff using fuzz factor 3 may have the same problem.
628757e8328SLionel SambucUntil a suitable interactive interface is added, you should probably do
629757e8328SLionel Sambuca context diff in these cases to see if the changes made sense.
630757e8328SLionel SambucOf course, compiling without errors is a pretty good indication that the patch
631757e8328SLionel Sambucworked, but not always.
632757e8328SLionel Sambuc.Pp
633757e8328SLionel Sambuc.Nm
634757e8328SLionel Sambucusually produces the correct results, even when it has to do a lot of
635757e8328SLionel Sambucguessing.
636757e8328SLionel SambucHowever, the results are guaranteed to be correct only when the patch is
637757e8328SLionel Sambucapplied to exactly the same version of the file that the patch was
638757e8328SLionel Sambucgenerated from.
639757e8328SLionel Sambuc.Sh BUGS
640757e8328SLionel SambucCould be smarter about partial matches, excessively deviant offsets and
641757e8328SLionel Sambucswapped code, but that would take an extra pass.
642757e8328SLionel Sambuc.Pp
643757e8328SLionel SambucCheck patch mode
644757e8328SLionel Sambuc.Pq Fl C
645757e8328SLionel Sambucwill fail if you try to check several patches in succession that build on
646757e8328SLionel Sambuceach other.
647757e8328SLionel SambucThe entire
648757e8328SLionel Sambuc.Nm
649757e8328SLionel Sambuccode would have to be restructured to keep temporary files around so that it
650757e8328SLionel Sambuccan handle this situation.
651757e8328SLionel Sambuc.Pp
652757e8328SLionel SambucIf code has been duplicated (for instance with #ifdef OLDCODE ... #else ...
653757e8328SLionel Sambuc#endif),
654757e8328SLionel Sambuc.Nm
655757e8328SLionel Sambucis incapable of patching both versions, and, if it works at all, will likely
656757e8328SLionel Sambucpatch the wrong one, and tell you that it succeeded to boot.
657757e8328SLionel Sambuc.Pp
658757e8328SLionel SambucIf you apply a patch you've already applied,
659757e8328SLionel Sambuc.Nm
660757e8328SLionel Sambucwill think it is a reversed patch, and offer to un-apply the patch.
661757e8328SLionel SambucThis could be construed as a feature.
662