5 .Id $Id: patch.man,v 1.23 1997/07/16 12:26:36 eggert Exp $
14 patch \- apply a diff file to an original
29 containing a difference listing produced by the
31 program and applies those differences to one or more original files,
32 producing patched versions.
33 Normally the patched versions are put in place of the originals.
34 Backups can be made; see the
39 The names of the files to be patched are usually taken from the patch file,
40 but if there's just one file to be patched it can specified on the
44 Upon startup, patch attempts to determine the type of the diff listing,
46 \fB\-c\fP (\fB\*=context\fP),
47 \fB\-e\fP (\fB\*=ed\fP),
48 \fB\-n\fP (\fB\*=normal\fP),
50 \fB\-u\fP (\fB\*=unified\fP)
52 Context diffs (old-style, new-style, and unified) and
53 normal diffs are applied by the
57 diffs are simply fed to the
62 tries to skip any leading garbage, apply the diff,
63 and then skip any trailing garbage.
64 Thus you could feed an article or message containing a
68 If the entire diff is indented by a consistent amount,
69 or if a context diff is encapsulated one or more times by prepending
70 "\fB\- \fP" to lines starting with "\fB\-\fP" as specified by Internet RFC 934,
71 this is taken into account.
73 With context diffs, and to a lesser extent with normal diffs,
75 can detect when the line numbers mentioned in the patch are incorrect,
76 and attempts to find the correct place to apply each hunk of the patch.
77 As a first guess, it takes the line number mentioned for the hunk, plus or
78 minus any offset used in applying the previous hunk.
79 If that is not the correct place,
81 scans both forwards and backwards for a set of lines matching the context
85 looks for a place where all lines of the context match.
86 If no such place is found, and it's a context diff, and the maximum fuzz factor
87 is set to 1 or more, then another scan takes place ignoring the first and last
89 If that fails, and the maximum fuzz factor is set to 2 or more,
90 the first two and last two lines of context are ignored,
91 and another scan is made.
92 (The default maximum fuzz factor is 2.)
95 cannot find a place to install that hunk of the patch, it puts the
96 hunk out to a reject file, which normally is the name of the output file
103 would generate a file name that is too long
104 (if even appending the single character
106 makes the file name too long, then
108 replaces the file name's last character).
109 (The rejected hunk comes out in ordinary context diff form regardless of
110 the input patch's form.
111 If the input was a normal diff, many of the contexts are simply null.)
112 The line numbers on the hunks in the reject file may be different than
113 in the patch file: they reflect the approximate location patch thinks the
114 failed hunks belong in the new file rather than the old one.
116 As each hunk is completed, you are told if the hunk
117 failed, and if so which line (in the new file)
119 thought the hunk should go on.
120 If the hunk is installed at a different line
121 from the line number specified in the diff you
123 A single large offset
125 indicate that a hunk was installed in the
127 You are also told if a fuzz factor was used to make the match, in which
128 case you should also be slightly suspicious.
131 option is given, you are also told about hunks that match exactly.
135 is specified on the command line,
137 tries to figure out from the leading garbage what the name of the file
138 to edit is, using the following rules.
141 If the header is that of a context diff,
143 takes the old and new file names in the header.
151 line in the leading garbage
152 and if either the old and new names are both absent or the
154 environment variable is set,
156 takes the name in the
161 For the purpose of the following rules,
162 the names are considered to be in the order (old, new, index),
163 regardless of the order that they appear in the header.
166 If some of the named files exist,
168 uses the first name if the
170 environment variable is set, and the best name otherwise.
175 is not ignoring \s-1RCS\s0 and \s-1SCCS\s0 (see the
179 option), and no named files exist
180 but an \s-1RCS\s0 or \s-1SCCS\s0 master is found,
182 uses the first named file with an \s-1RCS\s0 or \s-1SCCS\s0 master.
185 If no named files exist, no \s-1RCS\s0 or \s-1SCCS\s0 master was found,
186 some names are given,
188 is not set, and the patch appears to create a file,
190 uses the best name requiring the creation of the fewest directories.
193 If no file name results from the above heuristics, you are asked
194 for the name of the file to patch.
198 of a nonempty list of file names,
200 first takes all the names with the fewest path name components;
201 of those, it then takes all the names with the shortest basename;
202 of those, it then takes all the shortest names;
203 finally, it takes the first remaining name.
205 Additionally, if the leading garbage contains a
209 takes the first word from the prerequisites line (normally a version
210 number) and checks the original file to see if that word can be found.
213 asks for confirmation before proceeding.
215 The upshot of all this is that you should be able to say, while in a news
216 interface, something like the following:
218 \fB| patch \-d /usr/src/local/blurfl\fP
220 and patch a file in the
222 directory directly from the article containing
225 If the patch file contains more than one patch,
227 tries to apply each of them as if they came from separate patch files.
228 This means, among other things, that it is assumed that the name of the file
229 to patch must be determined for each diff listing,
230 and that the garbage before each diff listing
231 contains interesting things such as file names and revision level, as
232 mentioned previously.
235 \fB\-b\fP or \fB\*=backup\fP
237 That is, when patching a file,
238 rename or copy the original instead of removing it.
239 When backing up a file that does not exist,
240 an empty, unreadable backup file is created
241 as a placeholder to represent the nonexistent file.
245 .B \*=version\-control
246 option for details about how backup file names are determined.
248 .B \*=backup\-if\-mismatch
249 Back up a file if the patch does not match the file exactly
250 and if backups are not otherwise requested.
251 This is the default unless the
253 environment variable is set.
255 .B \*=no\-backup\-if\-mismatch
256 Do not back up a file if the patch does not match the file exactly
257 and if backups are not otherwise requested.
258 This is the default if the
260 environment variable is set.
262 \fB\-B\fP \fIpref\fP or \fB\*=prefix=\fP\fIpref\fP
265 to a file name when generating its simple backup file name.
268 the simple backup file name for
271 .BR /junk/src/patch/util.c .
274 Read and write all files in binary mode,
275 except for standard output and
277 This option has no effect on \s-1POSIX\s0-compliant systems.
278 On systems like \s-1DOS\s0 where this option makes a difference,
279 the patch should be generated by
280 .BR "diff\ \-a\ \*=binary" .
282 \fB\-c\fP or \fB\*=context\fP
283 Interpret the patch file as a ordinary context diff.
285 \fB\-d\fP \fIdir\fP or \fB\*=directory=\fP\fIdir\fP
286 Change to the directory
288 immediately, before doing
291 \fB\-D\fP \fIdefine\fP or \fB\*=ifdef=\fP\fIdefine\fP
293 .BR #ifdef " .\|.\|. " #endif
294 construct to mark changes, with
296 as the differentiating symbol.
299 Print the results of applying the patches without actually changing any files.
301 \fB\-e\fP or \fB\*=ed\fP
302 Interpret the patch file as an
306 \fB\-E\fP or \fB\*=remove\-empty\-files\fP
307 Remove output files that are empty after the patches have been applied.
308 Normally this option is unnecessary, since
310 can examine the time stamps on the header to determine whether a file
311 should exist after patching.
312 However, if the input is not a context diff or if the
314 environment variable is set,
316 does not remove empty patched files unless this option is given.
319 removes a file, it also attempts to remove any empty ancestor directories.
321 \fB\-f\fP or \fB\*=force\fP
322 Assume that the user knows exactly what he or she is doing, and do not
323 ask any questions. Skip patches whose headers
324 do not say which file is to be patched; patch files even though they have the
325 wrong version for the
327 line in the patch; and assume that
328 patches are not reversed even if they look like they are.
329 This option does not suppress commentary; use
333 \fB\-F\fP \fInum\fP or \fB\*=fuzz=\fP\fInum\fP
334 Set the maximum fuzz factor.
335 This option only applies to diffs that have context, and causes
337 to ignore up to that many lines in looking for places to install a hunk.
338 Note that a larger fuzz factor increases the odds of a faulty patch.
339 The default fuzz factor is 2, and it may not be set to more than
340 the number of lines of context in the context diff, ordinarily 3.
342 \fB\-g\fP \fInum\fP or \fB\*=get=\fP\fInum\fP
345 actions when a file is under \s-1RCS\s0 or \s-1SCCS\s0 control,
346 and does not exist or is read-only and matches the default version.
351 gets (or checks out) the file from the revision control system; if zero,
353 ignores \s-1RCS\s0 and \s-1SCCS\s0 and does not get the file; and if negative,
355 asks the user whether to get the file.
356 The default value of this option is given by the value of the
358 environment variable if it is set; if not, the default value is zero if
360 is set, negative otherwise.
363 Print a summary of options and exit.
365 \fB\-i\fP \fIpatchfile\fP or \fB\*=input=\fP\fIpatchfile\fP
372 read from standard input, the default.
374 \fB\-l\fP or \fB\*=ignore\-whitespace\fP
375 Match patterns loosely, in case tabs or spaces
376 have been munged in your files.
377 Any sequence of one or more blanks in the patch file matches any sequence
378 in the original file, and sequences of blanks at the ends of lines are ignored.
379 Normal characters must still match exactly.
380 Each line of the context must still match a line in the original file.
382 \fB\-n\fP or \fB\*=normal\fP
383 Interpret the patch file as a normal diff.
385 \fB\-N\fP or \fB\*=forward\fP
386 Ignore patches that seem to be reversed or already applied.
390 \fB\-o\fP \fIoutfile\fP or \fB\*=output=\fP\fIoutfile\fP
393 instead of patching files in place.
395 \fB\-p\fP\fInum\fP or \fB\*=strip\fP\fB=\fP\fInum\fP
396 Strip the smallest prefix containing
398 leading slashes from each file name found in the patch file.
399 A sequence of one or more adjacent slashes is counted as a single slash.
400 This controls how file names found in the patch file are treated, in case
401 you keep your files in a different directory than the person who sent
403 For example, supposing the file name in the patch file was
405 \fB/u/howard/src/blurfl/blurfl.c\fP
409 gives the entire file name unmodified,
413 \fBu/howard/src/blurfl/blurfl.c\fP
415 without the leading slash,
419 \fBblurfl/blurfl.c\fP
423 at all just gives you \fBblurfl.c\fP.
424 Whatever you end up with is looked for either in the current directory,
425 or the directory specified by the
429 \fB\-r\fP \fIrejectfile\fP or \fB\*=reject\-file=\fP\fIrejectfile\fP
432 instead of the default
436 \fB\-R\fP or \fB\*=reverse\fP
437 Assume that this patch was created with the old and new files swapped.
438 (Yes, I'm afraid that does happen occasionally, human nature being what it
441 attempts to swap each hunk around before applying it.
442 Rejects come out in the swapped format.
445 option does not work with
447 diff scripts because there is too little
448 information to reconstruct the reverse operation.
450 If the first hunk of a patch fails,
452 reverses the hunk to see if it can be applied that way.
453 If it can, you are asked if you want to have the
456 If it can't, the patch continues to be applied normally.
457 (Note: this method cannot detect a reversed patch if it is a normal diff
458 and if the first command is an append (i.e. it should have been a delete)
459 since appends always succeed, due to the fact that a null context matches
461 Luckily, most patches add or change lines rather than delete them, so most
462 reversed normal diffs begin with a delete, which fails, triggering
465 \fB\-s\fP or \fB\*=silent\fP or \fB\*=quiet\fP
466 Work silently, unless an error occurs.
468 \fB\-t\fP or \fB\*=batch\fP
469 Suppress questions like
471 but make some different assumptions:
472 skip patches whose headers do not contain file names (the same as \fB\-f\fP);
473 skip patches for which the file has the wrong version for the
476 in the patch; and assume that patches are reversed if they look like
479 \fB\-T\fP or \fB\*=set\-time\fP
480 Set the modification and access times of patched files from time stamps
481 given in context diff headers, assuming that the context diff headers
482 use local time. This option is not recommended, because patches using
483 local time cannot easily be used by people in other time zones, and
484 because local time stamps are ambiguous when local clocks move backwards
485 during daylight-saving time adjustments. Instead of using this option,
486 generate patches with \s-1UTC\s0 and use the
492 \fB\-u\fP or \fB\*=unified\fP
493 Interpret the patch file as a unified context diff.
495 \fB\-v\fP or \fB\*=version\fP
498 revision header and patch level, and exit.
500 \fB\-V\fP \fImethod\fP or \fB\*=version\-control=\fP\fImethod\fP
504 backup file names. The method can also be given by the
505 .B PATCH_VERSION_CONTROL
506 (or, if that's not set, the
507 .BR VERSION_CONTROL )
508 environment variable, which is overridden by this option.
509 The method does not affect whether backup files are made;
510 it affects only the names of any backup files that are made.
514 is like the \s-1GNU\s0
515 Emacs `version-control' variable;
517 also recognizes synonyms that
518 are more descriptive. The valid values for
520 are (unique abbreviations are
524 \fBexisting\fP or \fBnil\fP
525 Make numbered backups of files that already have them,
526 otherwise simple backups.
529 \fBnumbered\fP or \fBt\fP
530 Make numbered backups. The numbered backup file name for
536 is the version number.
538 \fBsimple\fP or \fBnever\fP
546 .BR \*=basename\-prefix ,
551 options specify the simple backup file name.
552 If none of these options are given, then a simple backup suffix is used;
553 it is the value of the
554 .B SIMPLE_BACKUP_SUFFIX
555 environment variable if set, and is
559 With numbered or simple backups,
560 if the backup file name is too long, the backup suffix
562 is used instead; if even appending
564 would make the name too long, then
566 replaces the last character of the file name.
570 Output extra information about the work being done.
572 \fB\-x\fP \fInum\fP or \fB\*=debug=\fP\fInum\fP
573 Set internal debugging flags of interest only to
577 \fB\-Y\fP \fIpref\fP or \fB\*=basename\-prefix=\fP\fIpref\fP
580 to the basename of a file name when generating its simple backup file name.
583 the simple backup file name for
586 .BR src/patch/.del/util.c .
588 \fB\-z\fP \fIsuffix\fP or \fB\*=suffix=\fP\fIsuffix\fP
591 as the simple backup suffix.
594 the simple backup file name for
597 .BR src/patch/util.c- .
598 The backup suffix may also be specified by the
599 .B SIMPLE_BACKUP_SUFFIX
600 environment variable, which is overridden by this option.
602 \fB\-Z\fP or \fB\*=set\-utc\fP
603 Set the modification and access times of patched files from time stamps
604 given in context diff headers, assuming that the context diff headers
605 use Coordinated Universal Time (\s-1UTC\s0, often known as \s-1GMT\s0).
620 options normally refrain from setting a file's time if the file's original time
621 does not match the time given in the patch header, or if its
622 contents do not match the patch exactly. However, if the
626 option is given, the file time is set regardless.
628 Due to the limitations of
630 output format, these options cannot update the times of files whose
631 contents have not changed. Also, if you use these options, you should remove
634 all files that depend on the patched files, so that later invocations of
636 do not get confused by the patched files' times.
640 This specifies whether
642 gets missing or read-only files from \s-1RCS\s0 or \s-1SCCS\s0
652 conforms more strictly to the \s-1POSIX\s0 standard:
653 it takes the first existing file from the list (old, new, index)
654 when intuiting file names from diff headers,
655 it does not remove files that are empty after patching,
656 it does not ask whether to get files from \s-1RCS\s0 or \s-1SCCS\s0,
657 it requires that all options precede the files in the command line,
658 and it does not backup files when there is a mismatch.
660 .B SIMPLE_BACKUP_SUFFIX
661 Extension to use for simple backup file names instead of
664 \fBTMPDIR\fP, \fBTMP\fP, \fBTEMP\fP
665 Directory to put temporary files in;
667 uses the first environment variable in this list that is set.
668 If none are set, the default is system-dependent;
673 \fBVERSION_CONTROL\fP or \fBPATCH_VERSION_CONTROL\fP
674 Selects version control style; see the
677 .B \*=version\-control
685 controlling terminal; used to get answers to questions asked of the user
690 Marshall T. Rose and Einar A. Stefferud,
691 Proposed Standard for Message Encapsulation,
692 Internet RFC 934 <URL:ftp://ftp.isi.edu/in-notes/rfc934.txt> (1985-01).
693 .SH "NOTES FOR PATCH SENDERS"
694 There are several things you should bear in mind if you are going to
695 be sending out patches.
697 Create your patch systematically.
698 A good method is the command
699 .BI "diff\ \-Naur\ " "old\ new"
704 identify the old and new directories.
709 should not contain any slashes.
712 command's headers should have dates
713 and times in Universal Time using traditional Unix format,
714 so that patch recipients can use the
719 Here is an example command, using Bourne shell syntax:
721 \fBLC_ALL=C TZ=UTC0 diff \-Naur gcc\-2.7 gcc\-2.8\fP
723 Tell your recipients how to apply the patch
724 by telling them which directory to
728 options to use. The option string
731 Test your procedure by pretending to be a recipient and applying
732 your patch to a copy of the original files.
734 You can save people a lot of grief by keeping a
736 file which is patched to increment the patch level
737 as the first diff in the patch file you send out.
740 line in with the patch, it won't let them apply
741 patches out of order without some warning.
743 You can create a file by sending out a diff that compares
745 or an empty file dated the Epoch (1970-01-01 00:00:00 \s-1UTC\s0)
746 to the file you want to create.
747 This only works if the file you want to create doesn't exist already in
748 the target directory.
749 Conversely, you can remove a file by sending out a context diff that compares
750 the file to be deleted with an empty file dated the Epoch.
751 The file will be removed unless the
753 environment variable is set and the
756 .B \*=remove\-empty\-files
758 An easy way to generate patches that create and remove files
766 If the recipient is supposed to use the
768 option, do not send output that looks like this:
772 diff \-Naur v2.0.29/prog/README prog/README
774 \-\^\-\^\- v2.0.29/prog/README Mon Mar 10 15:13:12 1997
776 +\^+\^+ prog/README Mon Mar 17 14:58:22 1997
779 because the two file names have different numbers of slashes,
780 and different versions of
782 interpret the file names differently.
783 To avoid confusion, send output that looks like this instead:
787 diff \-Naur v2.0.29/prog/README v2.0.30/prog/README
789 \-\^\-\^\- v2.0.29/prog/README Mon Mar 10 15:13:12 1997
791 +\^+\^+ v2.0.30/prog/README Mon Mar 17 14:58:22 1997
795 Avoid sending patches that compare backup file names like
797 since this might confuse
799 into patching a backup file instead of the real file.
800 Instead, send patches that compare the same base file names
801 in different directories, e.g.\&
806 Take care not to send out reversed patches, since it makes people wonder
807 whether they already applied the patch.
809 Try not to have your patch modify derived files
812 where there is a line
813 .B "configure: configure.in"
814 in your makefile), since the recipient should be
815 able to regenerate the derived files anyway.
816 If you must send diffs of derived files,
817 generate the diffs using \s-1UTC\s0,
818 have the recipients apply the patch with the
822 option, and have them remove any unpatched files that depend on patched files
826 While you may be able to get away with putting 582 diff listings into
827 one file, it may be wiser to group related patches into separate files in
828 case something goes haywire.
830 Diagnostics generally indicate that
832 couldn't parse your patch file.
836 option is given, the message
838 indicates that there is unprocessed text in
839 the patch file and that
841 is attempting to intuit whether there is a patch in that text and, if so,
842 what kind of patch it is.
846 0 if all hunks are applied successfully,
847 1 if some hunks cannot be applied,
848 and 2 if there is more serious trouble.
849 When applying a set of patches in a loop it behooves you to check this
850 exit status so you don't apply a later patch to a partially patched file.
852 Context diffs cannot reliably represent the creation or deletion of
853 empty files, empty directories, or special files such as symbolic links.
854 Nor can they represent changes to file metadata like ownership, permissions,
855 or whether one file is a hard link to another.
856 If changes like these are also required, separate instructions
857 (e.g. a shell script) to accomplish them should accompany the patch.
860 cannot tell if the line numbers are off in an
862 script, and can detect
863 bad line numbers in a normal diff only when it finds a change or deletion.
864 A context diff using fuzz factor 3 may have the same problem.
865 Until a suitable interactive interface is added, you should probably do
866 a context diff in these cases to see if the changes made sense.
867 Of course, compiling without errors is a pretty good indication that the patch
868 worked, but not always.
871 usually produces the correct results, even when it has to do a lot of
873 However, the results are guaranteed to be correct only when the patch is
874 applied to exactly the same version of the file that the patch was
876 .SH "COMPATIBILITY ISSUES"
877 The \s-1POSIX\s0 standard specifies behavior that differs from
879 traditional behavior.
880 You should be aware of these differences if you must interoperate with
882 versions 2.1 and earlier, which are not \s-1POSIX\s0-compliant.
889 option's operand was optional, and a bare
895 option now requires an operand, and
899 For maximum compatibility, use options like
907 simply counted slashes when stripping path prefixes;
909 now counts pathname components.
910 That is, a sequence of one or more adjacent slashes
911 now counts as a single slash.
912 For maximum portability, avoid sending patches containing
919 backups were enabled by default.
920 This behavior is now enabled with the
926 Conversely, in \s-1POSIX\s0
928 backups are never made, even when there is a mismatch.
931 this behavior is enabled with the
932 .B \*=no\-backup\-if\-mismatch
933 option or by setting the
935 environment variable.
943 .BI "\-b\ \-z" "\ suffix"
944 options of \s-1GNU\s0
950 used a complicated (and incompletely documented) method
951 to intuit the name of the file to be patched from the patch header.
952 This method was not \s-1POSIX\s0-compliant, and had a few gotchas.
955 uses a different, equally complicated (but better documented) method
956 that is optionally \s-1POSIX\s0-compliant; we hope it has
957 fewer gotchas. The two methods are compatible if the
958 file names in the context diff header and the
960 line are all identical after prefix-stripping.
961 Your patch is normally compatible if each header's file names
962 all contain the same number of slashes.
967 asked the user a question, it sent the question to standard error
968 and looked for an answer from
969 the first file in the following list that was a terminal:
970 standard error, standard output,
975 sends questions to standard output and gets answers from
977 Defaults for some answers have been changed so that
979 never goes into an infinite loop when using default answers.
984 exited with a status value that counted the number of bad hunks,
985 or with status 1 if there was real trouble.
988 exits with status 1 if some hunks failed,
989 or with 2 if there was real trouble.
992 Limit yourself to the following options when sending instructions
993 meant to be executed by anyone running \s-1GNU\s0
997 or a \s-1POSIX\s0-compliant
999 Spaces are significant in the following list, and operands are required.
1014 .BI \-r " rejectfile"
1019 could be smarter about partial matches, excessively deviant offsets and
1020 swapped code, but that would take an extra pass.
1022 If code has been duplicated (for instance with
1023 \fB#ifdef OLDCODE\fP .\|.\|. \fB#else .\|.\|. #endif\fP),
1025 is incapable of patching both versions, and, if it works at all, will likely
1026 patch the wrong one, and tell you that it succeeded to boot.
1028 If you apply a patch you've already applied,
1030 thinks it is a reversed patch, and offers to un-apply the patch.
1031 This could be construed as a feature.
1035 1984, 1985, 1986, 1988 Larry Wall.
1039 1997 Free Software Foundation, Inc.
1041 Permission is granted to make and distribute verbatim copies of
1042 this manual provided the copyright notice and this permission notice
1043 are preserved on all copies.
1045 Permission is granted to copy and distribute modified versions of this
1046 manual under the conditions for verbatim copying, provided that the
1047 entire resulting derived work is distributed under the terms of a
1048 permission notice identical to this one.
1050 Permission is granted to copy and distribute translations of this
1051 manual into another language, under the above conditions for modified
1052 versions, except that this permission notice may be included in
1053 translations approved by the copyright holders instead of in
1054 the original English.
1056 Larry Wall wrote the original version of
1060 arbitrary limits; added support for binary files,
1061 setting file times, and deleting files;
1062 and made it conform better to \s-1POSIX\s0.
1063 Other contributors include Wayne Davison, who added unidiff support,
1064 and David MacKenzie, who added configuration and backup support.
projects / dragonfly.git / blob