1PATCH(1P) POSIX Programmer's Manual PATCH(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 patch — apply changes to files
13
15 patch [-blNR] [-c|-e|-n|-u] [-d dir] [-D define] [-i patchfile]
16 [-o outfile] [-p num] [-r rejectfile] [file]
17
19 The patch utility shall read a source (patch) file containing any of
20 four forms of difference (diff) listings produced by the diff utility
21 (normal, copied context, unified context, or in the style of ed) and
22 apply those differences to a file. By default, patch shall read from
23 the standard input.
24 The patch utility shall attempt to determine the type of the diff list‐
26 ing, unless overruled by a -c, -e, -n, or -u option.
27 If the patch file contains more than one patch, patch shall attempt to
29 apply each of them as if they came from separate patch files. (In this
30 case, the application shall ensure that the name of the patch file is
31 determinable for each diff listing.)
32
34 The patch utility shall conform to the Base Definitions volume of
35 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
36 The following options shall be supported:
38 -b Save a copy of the original contents of each modified file,
40 before the differences are applied, in a file of the same
41 name with the suffix .orig appended to it. If the file
42 already exists, it shall be overwritten; if multiple patches
43 are applied to the same file, the .orig file shall be written
44 only for the first patch. When the -o outfile option is also
45 specified, file.orig shall not be created but, if outfile
46 already exists, outfile.orig shall be created.
47 -c Interpret the patch file as a copied context difference (the
49 output of the utility diff when the -c or -C options are
50 specified).
51 -d dir Change the current directory to dir before processing as
53 described in the EXTENDED DESCRIPTION section.
54 -D define Mark changes with one of the following C preprocessor con‐
56 structs:
57 #ifdef define
60 ...
61 #endif
62 #ifndef define
64 ...
65 #endif
66 optionally combined with the C preprocessor construct #else.
68 If the patched file is processed with the C preprocessor,
69 where the macro define is defined, the output shall contain
70 the changes from the patch file; otherwise, the output shall
71 not contain the patches specified in the patch file.
72 -e Interpret the patch file as an ed script, rather than a diff
74 script.
75 -i patchfile
77 Read the patch information from the file named by the path‐
78 name patchfile, rather than the standard input.
79 -l (The letter ell.) Cause any sequence of <blank> characters in
81 the difference script to match any sequence of <blank> char‐
82 acters in the input file. Other characters shall be matched
83 exactly.
84 -n Interpret the script as a normal difference.
86 -N Ignore patches where the differences have already been
88 applied to the file; by default, already-applied patches
89 shall be rejected.
90 -o outfile
92 Instead of modifying the files (specified by the file operand
93 or the difference listings) directly, write a copy of the
94 file referenced by each patch, with the appropriate differ‐
95 ences applied, to outfile. Multiple patches for a single
96 file shall be applied to the intermediate versions of the
97 file created by any previous patches, and shall result in
98 multiple, concatenated versions of the file being written to
99 outfile.
100 -p num For all pathnames in the patch file that indicate the names
102 of files to be patched, delete num pathname components from
103 the beginning of each pathname. If the pathname in the patch
104 file is absolute, any leading <slash> characters shall be
105 considered the first component (that is, -p 1 shall remove
106 the leading <slash> characters). Specifying -p 0 shall cause
107 the full pathname to be used. If -p is not specified, only
108 the basename (the final pathname component) shall be used.
109 -R Reverse the sense of the patch script; that is, assume that
111 the difference script was created from the new version to the
112 old version. The -R option cannot be used with ed scripts.
113 The patch utility shall attempt to reverse each portion of
114 the script before applying it. Rejected differences shall be
115 saved in swapped format. If this option is not specified, and
116 until a portion of the patch file is successfully applied,
117 patch attempts to apply each portion in its reversed sense as
118 well as in its normal sense. If the attempt is successful,
119 the user shall be prompted to determine whether the -R option
120 should be set.
121 -r rejectfile
123 Override the default reject filename. In the default case,
124 the reject file shall have the same name as the output file,
125 with the suffix .rej appended to it; see Patch Application.
126 -u Interpret the patch file as a unified context difference (the
128 output of the diff utility when the -u or -U options are
129 specified).
130
132 The following operand shall be supported:
133 file A pathname of a file to patch.
135
137 See the INPUT FILES section.
138
140 Input files shall be text files.
141
143 The following environment variables shall affect the execution of
144 patch:
145 LANG Provide a default value for the internationalization vari‐
147 ables that are unset or null. (See the Base Definitions vol‐
148 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
149 ables the precedence of internationalization variables used
150 to determine the values of locale categories.)
151 LC_ALL If set to a non-empty string value, override the values of
153 all the other internationalization variables.
154 LC_COLLATE
156 Determine the locale for the behavior of ranges, equivalence
157 classes, and multi-character collating elements used in the
158 extended regular expression defined for the yesexpr locale
159 keyword in the LC_MESSAGES category.
160 LC_CTYPE Determine the locale for the interpretation of sequences of
162 bytes of text data as characters (for example, single-byte as
163 opposed to multi-byte characters in arguments and input
164 files), and the behavior of character classes used in the
165 extended regular expression defined for the yesexpr locale
166 keyword in the LC_MESSAGES category.
167 LC_MESSAGES
169 Determine the locale used to process affirmative responses,
170 and the locale used to affect the format and contents of
171 diagnostic messages and prompts written to standard error.
172 NLSPATH Determine the location of message catalogs for the processing
174 of LC_MESSAGES.
175 LC_TIME Determine the locale for recognizing the format of file time‐
177 stamps written by the diff utility in a context-difference
178 input file.
179
181 Default.
182
184 Not used.
185
187 The standard error shall be used for diagnostic and informational mes‐
188 sages.
189
191 The output of the patch utility, the save files (.orig suffixes), and
192 the reject files (.rej suffixes) shall be text files.
193
195 A patch file may contain patching instructions for more than one file;
196 filenames shall be determined as specified in Filename Determination.
197 When the -b option is specified, for each patched file, the original
198 shall be saved in a file of the same name with the suffix .orig
199 appended to it.
200 For each patched file, a reject file may also be created as noted in
202 Patch Application. In the absence of a -r option, the name of this
203 file shall be formed by appending the suffix .rej to the original file‐
204 name.
205 Patch File Format
207 The patch file shall contain zero or more lines of header information
208 followed by one or more patches. Each patch shall contain zero or more
209 lines of filename identification in the format produced by the -c, -C,
210 -u, or -U options of the diff utility, and one or more sets of diff
211 output, which are customarily called hunks.
212 The patch utility shall recognize the following expression in the
214 header information:
215 Index: pathname
217 The file to be patched is named pathname.
218 If all lines (including headers) within a patch begin with the same
220 leading sequence of <blank> characters, the patch utility shall remove
221 this sequence before proceeding. Within each patch, if the type of dif‐
222 ference is common context, the patch utility shall recognize the fol‐
223 lowing expressions:
224 *** filename timestamp
226 The patches arose from filename.
227 --- filename timestamp
229 The patches should be applied to filename.
230 If the type of difference is unified context, the patch utility shall
232 recognize the following expressions:
233 --- filename timestamp
235 The patches arose from filename.
236 +++ filename timestamp
238 The patches should be applied to filename.
239 Each hunk within a patch shall be the diff output to change a line
241 range within the original file. The line numbers for successive hunks
242 within a patch shall occur in ascending order.
243 Filename Determination
245 If no file operand is specified, patch shall perform the following
246 steps to determine the filename to use:
247 1. If the type of diff is context, the patch utility shall delete
249 pathname components (as specified by the -p option) from the file‐
250 name on the line beginning with "***" (if copied context) or "---"
251 (if unified context), then test for the existence of this file rel‐
252 ative to the current directory (or the directory specified with the
253 -d option). If the file exists, the patch utility shall use this
254 filename.
255 2. If the type of diff is context, the patch utility shall delete the
257 pathname components (as specified by the -p option) from the file‐
258 name on the line beginning with "---" (if copied context) or "+++"
259 (if unified context), then test for the existence of this file rel‐
260 ative to the current directory (or the directory specified with the
261 -d option). If the file exists, the patch utility shall use this
262 filename.
263 3. If the header information contains a line beginning with the string
265 Index:, the patch utility shall delete pathname components (as
266 specified by the -p option) from this line, then test for the exis‐
267 tence of this file relative to the current directory (or the direc‐
268 tory specified with the -d option). If the file exists, the patch
269 utility shall use this filename.
270 4. If an SCCS directory exists in the current directory, patch shall
272 attempt to perform a get -e SCCS/s.filename command to retrieve an
273 editable version of the file. If the file exists, the patch utility
274 shall use this filename.
275 5. The patch utility shall write a prompt to standard output and
277 request a filename interactively from the controlling terminal (for
278 example, /dev/tty).
279 Patch Application
281 If the -c, -e, -n, or -u option is present, the patch utility shall
282 interpret information within each hunk as a copied context difference,
283 an ed difference, a normal difference, or a unified context difference,
284 respectively. In the absence of any of these options, the patch utility
285 shall determine the type of difference based on the format of informa‐
286 tion within the hunk.
287 For each hunk, the patch utility shall begin to search for the place to
289 apply the patch at the line number at the beginning of the hunk, plus
290 or minus any offset used in applying the previous hunk. If lines match‐
291 ing the hunk context are not found, patch shall scan both forwards and
292 backwards at least 1000 bytes for a set of lines that match the hunk
293 context.
294 If no such place is found and it is a context difference, then another
296 scan shall take place, ignoring the first and last line of context. If
297 that fails, the first two and last two lines of context shall be
298 ignored and another scan shall be made. Implementations may search more
299 extensively for installation locations.
300 If no location can be found, the patch utility shall append the hunk to
302 the reject file. A rejected hunk that is a copied context difference,
303 an ed difference, or a normal difference shall be written in copied-
304 context-difference format regardless of the format of the patch file.
305 It is implementation-defined whether a rejected hunk that is a unified
306 context difference is written in copied-context-difference format or in
307 unified-context-difference format. If the input was a normal or ed-
308 style difference, the reject file may contain differences with zero
309 lines of context. The line numbers on the hunks in the reject file may
310 be different from the line numbers in the patch file since they shall
311 reflect the approximate locations for the failed hunks in the new file
312 rather than the old one.
313 If the type of patch is an ed diff, the implementation may accomplish
315 the patching by invoking the ed utility.
316
318 The following exit values shall be returned:
319 0 Successful completion.
321 1 One or more lines were written to a reject file.
323 >1 An error occurred.
325
327 Patches that cannot be correctly placed in the file shall be written to
328 a reject file.
329 The following sections are informative.
331
333 The -R option does not work with ed scripts because there is too little
334 information to reconstruct the reverse operation.
335 The -p option makes it possible to customize a patch file to local user
337 directory structures without manually editing the patch file. For exam‐
338 ple, if the filename in the patch file was:
339 /curds/whey/src/blurfl/blurfl.c
342 Setting -p 0 gives the entire pathname unmodified; -p 1 gives:
344 curds/whey/src/blurfl/blurfl.c
347 without the leading <slash>, -p 4 gives:
349 blurfl/blurfl.c
352 and not specifying -p at all gives:
354 blurfl.c .
357
359 None.
360
362 Some of the functionality in historical patch implementations was not
363 specified. The following documents those features present in historical
364 implementations that have not been specified.
365 A deleted piece of functionality was the '+' pseudo-option allowing an
367 additional set of options and a patch file operand to be given. This
368 was seen as being insufficiently useful to standardize.
369 In historical implementations, if the string "Prereq:" appeared in the
371 header, the patch utility would search for the corresponding version
372 information (the string specified in the header, delimited by <blank>
373 characters or the beginning or end of a line or the file) anywhere in
374 the original file. This was deleted as too simplistic and insuffi‐
375 ciently trustworthy a mechanism to standardize. For example, if:
376 Prereq: 1.2
379 were in the header, the presence of a delimited 1.2 anywhere in the
381 file would satisfy the prerequisite.
382 The following options were dropped from historical implementations of
384 patch as insufficiently useful to standardize:
385 -b The -b option historically provided a method for changing the
387 name extension of the backup file from the default .orig.
388 This option has been modified and retained in this volume of
389 POSIX.1‐2017.
390 -F The -F option specified the number of lines of a context diff
392 to ignore when searching for a place to install a patch.
393 -f The -f option historically caused patch not to request addi‐
395 tional information from the user.
396 -r The -r option historically provided a method of overriding
398 the extension of the reject file from the default .rej.
399 -s The -s option historically caused patch to work silently
401 unless an error occurred.
402 -x The -x option historically set internal debugging flags.
404 In some file system implementations, the saving of a .orig file may
406 produce unwanted results. In the case of 12, 13, or 14-character file‐
407 names (on file systems supporting 14-character maximum filenames), the
408 .orig file overwrites the new file. The reject file may also exceed
409 this filename limit. It was suggested, due to some historical practice,
410 that a <tilde> ('~') suffix be used instead of .orig and some other
411 character instead of the .rej suffix. This was rejected because it is
412 not obvious to the user which file is which. The suffixes .orig and
413 .rej are clearer and more understandable.
414 The -b option has the opposite sense in some historical implementa‐
416 tions—do not save the .orig file. The default case here is not to save
417 the files, making patch behave more consistently with the other stan‐
418 dard utilities.
419 The -w option in early proposals was changed to -l to match historical
421 practice.
422 The -N option was included because without it, a non-interactive appli‐
424 cation cannot reject previously applied patches. For example, if a user
425 is piping the output of diff into the patch utility, and the user only
426 wants to patch a file to a newer version non-interactively, the -N
427 option is required.
428 Changes to the -l option description were proposed to allow matching
430 across <newline> characters in addition to just <blank> characters.
431 Since this is not historical practice, and since some ambiguities could
432 result, it is suggested that future developments in this area utilize
433 another option letter, such as -L.
434 The -u option of GNU patch has been added, along with support for uni‐
436 fied context formats.
437
439 None.
440
442 diff, ed
443 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
445 Variables, Section 12.2, Utility Syntax Guidelines
446
448 Portions of this text are reprinted and reproduced in electronic form
449 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
450 table Operating System Interface (POSIX), The Open Group Base Specifi‐
451 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
452 Electrical and Electronics Engineers, Inc and The Open Group. In the
453 event of any discrepancy between this version and the original IEEE and
454 The Open Group Standard, the original IEEE and The Open Group Standard
455 is the referee document. The original Standard can be obtained online
456 at http://www.opengroup.org/unix/online.html .
457 Any typographical or formatting errors that appear in this page are
459 most likely to have been introduced during the conversion of the source
460 files to man page format. To report such errors, see https://www.ker‐
461 nel.org/doc/man-pages/reporting_bugs.html .
462IEEE/The Open Group 2017 PATCH(1P)