6 .Nd Comparing and Merging Files
7 .Sh Comparing and Merging Files
9 Computer users often find occasion to ask how two files differ. Perhaps one
10 file is a newer version of the other file. Or maybe the two files started
11 out as identical copies but were changed by different people.
15 command to show differences between two files, or each corresponding file
18 outputs differences between files line by line in any of several formats,
19 selectable by command line options. This set of differences is often called
24 For files that are identical,
26 normally produces no output; for binary (non-text) files,
28 normally reports only that they are different.
32 command to show the byte and line numbers where two files differ.
34 can also show all the bytes that differ between the two files, side by side.
35 A way to compare two files character by character is the Emacs command
36 .Li M-x compare-windows .
37 See Section.Dq Other Window ,
38 for more information on that command.
42 command to show differences among three files. When two people have made independent
43 changes to a common original,
45 can report the differences between the original and the two changed versions,
46 and can produce a merged file that contains both persons' changes together
47 with warnings about conflicts.
51 command to merge two files interactively.
53 You can use the set of differences produced by
55 to distribute updates to text files (such as program source code) to other
56 people. This method is especially useful when the differences are small compared
57 to the complete files. Given
59 output, you can use the
63 a copy of the file. If you think of
65 as subtracting one file from another to produce their difference, you can
68 as adding the difference to one file to reproduce the other.
70 This manual first concentrates on making diffs, and later shows how to use
71 diffs to update files.
75 was written by Paul Eggert, Mike Haertel, David Hayes, Richard Stallman, and
76 Len Tower. Wayne Davison designed and implemented the unified output format.
77 The basic algorithm is described by Eugene W. Myers in \(lqAn O(ND) Difference
78 Algorithm and its Variations\(rq,
80 Vol. 1 No. 2, 1986, pp. 251--266; and in \(lqA File Comparison Program\(rq, Webb Miller
82 .Em Software---Practice and Experience
83 Vol. 15 No. 11, 1985, pp. 1025--1040. The algorithm was independently discovered
84 as described by E. Ukkonen in \(lqAlgorithms for Approximate String Matching\(rq,
85 .Em Information and Control
86 Vol. 64, 1985, pp. 100--118. Unless the
90 uses a heuristic by Paul Eggert that limits the cost to O(N^1.5 log N) at
91 the price of producing suboptimal output for large inputs with many differences.
92 Related algorithms are surveyed by Alfred V. Aho in section 6.3 of \(lqAlgorithms
93 for Finding Patterns in Strings\(rq,
94 .Em Handbook of Theoretical Computer Science
95 (Jan Van Leeuwen, ed.), Vol. A,
96 .Em Algorithms and Complexity ,
97 Elsevier/MIT Press, 1990, pp. 255--300.
101 was written by Randy Smith. GNU
103 was written by Thomas Lord. GNU
105 was written by Torbj\(:orn Granlund and David MacKenzie.
109 was written mainly by Larry Wall and Paul Eggert; several GNU enhancements
110 were contributed by Wayne Davison and David MacKenzie. Parts of this manual
111 are adapted from a manual page written by Larry Wall, with his permission.
113 .Sh What Comparison Means
114 There are several ways to think about the differences between two files. One
115 way to think of the differences is as a series of lines that were deleted
116 from, inserted in, or changed in one file to produce the other file.
118 compares two files line by line, finds groups of lines that differ, and reports
119 each group of differing lines. It can report the differing lines in several
120 formats, which have different purposes.
124 can show whether files are different without detailing the differences. It
125 also provides ways to suppress certain kinds of differences that are not important
126 to you. Most commonly, such differences are changes in the amount of white
127 space between words or lines.
129 also provides ways to suppress differences in alphabetic case or in lines
130 that match a regular expression that you provide. These options can accumulate;
131 for example, you can ignore changes in both white space and alphabetic case.
133 Another way to think of the differences between two files is as a sequence
134 of pairs of bytes that can be either identical or different.
136 reports the differences between two files byte by byte, instead of line by
137 line. As a result, it is often more useful than
139 for comparing binary files. For text files,
141 is useful mainly when you want to know only whether two files are identical,
142 or whether one file is a prefix of the other.
144 To illustrate the effect that considering changes byte by byte can have compared
145 with considering them line by line, think of what happens if a single newline
146 character is added to the beginning of a file. If that file is then compared
147 with an otherwise identical file that lacks the newline at the beginning,
149 will report that a blank line has been added to the file, while
151 will report that almost every byte of the two files differs.
154 normally compares three input files line by line, finds groups of lines that
155 differ, and reports each group of differing lines. Its output is designed
156 to make it easy to inspect two different sets of changes to the same file.
159 When comparing two files,
161 finds sequences of lines common to both files, interspersed with groups of
162 differing lines called
164 Comparing two identical files yields one sequence of common lines and no hunks,
165 because no lines differ. Comparing two entirely different files yields no
166 common lines and one large hunk that contains all lines of both files. In
167 general, there are many ways to match up lines between two given files.
169 tries to minimize the total hunk size by finding large sequences of common
170 lines interspersed with small hunks of differing lines.
172 For example, suppose the file
174 contains the three lines
180 contains the same three lines in reverse order
188 as common, then the command
190 produces this output:
192 .Bd -literal -offset indent
203 notices the common line
205 instead, it produces this output:
207 .Bd -literal -offset indent
218 It is also possible to find
222 does not always find an optimal matching between the files; it takes shortcuts
223 to run faster. But its output is usually close to the shortest possible. You
224 can adjust this tradeoff with the
229 .Dq diff Performance ) .
231 .Ss Suppressing Differences in Blank and Tab Spacing
235 .Op --ignore-tab-expansion
236 option ignores the distinction between tabs and spaces on input. A tab is
237 considered to be equivalent to the number of spaces to the next tab stop (see Section
243 .Op --ignore-space-change
244 option is stronger. It ignores white space at line end, and considers all
245 other sequences of one or more white space characters within a line to be
246 equivalent. With this option,
248 considers the following two lines to be equivalent, where
250 denotes the line end:
252 .Bd -literal -offset indent
253 Here lyeth muche rychnesse in lytell space. -- John Heywood$
254 Here lyeth muche rychnesse in lytell space. -- John Heywood $
260 .Op --ignore-all-space
261 option is stronger still. It ignores differences even if one line has white
262 space where the other line has none.
264 characters include tab, newline, vertical tab, form feed, carriage return,
265 and space; some locales may define additional characters to be white space.
268 considers the following two lines to be equivalent, where
270 denotes the line end and
272 denotes a carriage return:
274 .Bd -literal -offset indent
275 Here lyeth muche rychnesse in lytell space.-- John Heywood$
276 He relyeth much erychnes seinly tells pace. --John Heywood ^M$
279 .Ss Suppressing Differences Whose Lines Are All Blank
283 .Op --ignore-blank-lines
284 option ignores changes that consist entirely of blank lines. With this option,
285 for example, a file containing
286 .Bd -literal -offset indent
287 1. A point is that which has no part.
289 2. A line is breadthless length.
290 -- Euclid, The Elements, I
292 is considered identical to a file containing
293 .Bd -literal -offset indent
294 1. A point is that which has no part.
295 2. A line is breadthless length.
298 -- Euclid, The Elements, I
301 Normally this option affects only lines that are completely empty, but if
305 .Op --ignore-space-change
309 .Op --ignore-all-space
310 option, lines are also affected if they look empty but contain white space.
315 by default, but it is equivalent to
316 .Op -I '^[[:space:]]*$'
323 .Ss Suppressing Differences Whose Lines All Match a Regular Expression
324 To ignore insertions and deletions of lines that match a
326 -style regular expression, use the
329 .Op --ignore-matching-lines= Va regexp
330 option. You should escape regular expressions that contain shell metacharacters
331 to prevent the shell from expanding them. For example,
332 .Li diff -I '^[[:digit:]]'
333 ignores all changes to lines beginning with a digit.
337 only ignores the insertion or deletion of lines that contain the regular expression
338 if every changed line in the hunk---every insertion and every deletion---matches
339 the regular expression. In other words, for each nonignorable change,
341 prints the complete set of changes in its vicinity, including the ignorable
344 You can specify more than one regular expression for lines to ignore by using
349 tries to match each line against each regular expression.
351 .Ss Suppressing Case Differences
354 can treat lower case letters as equivalent to their upper case counterparts,
355 so that, for example, it considers
360 to all be the same. To request this, use the
366 .Ss Summarizing Which Files Differ
367 When you only want to find out whether files are different, and you don't
368 care what the differences are, you can use the summary output format. In this
369 format, instead of showing the differences between the files,
371 simply reports whether files differ. The
375 option selects this output format.
377 This format is especially useful when comparing the contents of two directories.
378 It is also much faster than doing the normal line by line comparisons, because
380 can stop analyzing the files as soon as it knows that there are any differences.
382 You can also get a brief indication of whether two files differ by using
384 For files that are identical,
386 produces no output. When the files differ, by default,
388 outputs the byte and line number where the first difference occurs, or reports
389 that one file is a prefix of the other. You can use the
394 option to suppress that information, so that
396 produces no output and reports whether the files differ using only its exit
403 cannot compare directories; it can only compare two files.
405 .Ss Binary Files and Forcing Text Comparisons
408 thinks that either of the two files it is comparing is binary (a non-text
409 file), it normally treats that pair of files much as if the summary output
410 format had been selected (see Section
412 and reports only that the binary files are different. This is because line
413 by line comparisons are usually not meaningful for binary files.
416 determines whether a file is text or binary by checking the first few bytes
417 in the file; the exact number of bytes is system dependent, but it is typically
418 several thousand. If every byte in that part of the file is non-null,
420 considers the file to be text; otherwise it considers the file to be binary.
422 Sometimes you might want to force
424 to consider files to be text. For example, you might be comparing text files
425 that contain null characters;
427 would erroneously decide that those are non-text files. Or you might be comparing
428 documents that are in a format used by a word processing system that uses
429 null characters to indicate special formatting. You can force
431 to consider all files to be text files, and compare them line by line, by
436 option. If the files you compare using this option do not in fact contain
437 text, they will probably contain few newline characters, and the
439 output will consist of hunks showing differences between long lines of whatever
440 characters the files contain.
444 to report only whether files differ (but not how). Use the
450 Normally, differing binary files count as trouble because the resulting
452 output does not capture all the differences. This trouble causes
454 to exit with status 2. However, this trouble cannot occur with the
462 option, as these options both cause
464 to generate a form of output that represents differences as requested.
466 In operating systems that distinguish between text and binary files,
468 normally reads and writes all data as text. Use the
472 to read and write binary data instead. This option has no effect on a POSIX-compliant
473 system like GNU or traditional Unix. However, many personal computer operating
474 systems represent the end of a line with a carriage return followed by a newline.
477 normally ignores these carriage returns on input and generates them at the
478 end of each output line, but with the
482 treats each carriage return as just another input character, and does not
483 generate a carriage return at the end of each output line. This can be useful
484 when dealing with non-text files that are meant to be interchanged with POSIX-compliant
488 .Op --strip-trailing-cr
491 to treat input lines that end in carriage return followed by newline as if
492 they end in plain newline. This can be useful when comparing text that is
493 imperfectly imported from many personal computer operating systems. This option
494 affects how lines are read, which in turn affects how they are compared and
497 If you want to compare two files byte by byte, you can use the
503 option to show the values of each differing byte in the two files. With GNU
509 option to show the ASCII representation of those bytes.See Section
511 for more information.
515 thinks that any of the files it is comparing is binary (a non-text file),
516 it normally reports an error, because such comparisons are usually not useful.
518 uses the same test as
520 to decide whether a file is binary. As with
522 if the input files contain a few non-text bytes but otherwise are like text
525 to consider all files to be text files and compare them line by line by using
532 .Sh Xr diff Output Formats
534 has several mutually exclusive options for output format. The following sections
535 describe each format, illustrating how
537 reports the differences between two sample input files.
539 .Ss Two Sample Input Files
540 Here are two sample files that we will use in numerous examples to illustrate
543 and how various options can change it.
548 .Bd -literal -offset indent
549 The Way that can be told of is not the eternal Way;
550 The name that can be named is not the eternal name.
551 The Nameless is the origin of Heaven and Earth;
552 The Named is the mother of all things.
553 Therefore let there always be non-being,
554 so we may see their subtlety,
555 And let there always be being,
556 so we may see their outcome.
557 The two are the same,
558 But after they are produced,
559 they have different names.
565 .Bd -literal -offset indent
566 The Nameless is the origin of Heaven and Earth;
567 The named is the mother of all things.
569 Therefore let there always be non-being,
570 so we may see their subtlety,
571 And let there always be being,
572 so we may see their outcome.
573 The two are the same,
574 But after they are produced,
575 they have different names.
576 They both may be called deep and profound.
577 Deeper and more profound,
578 The door of all subtleties!
581 In this example, the first hunk contains just the first two lines of
583 the second hunk contains the fourth line of
585 opposing the second and third lines of
587 and the last hunk contains just the last three lines of
590 .Ss Showing Differences in Their Context
591 Usually, when you are looking at the differences between files, you will also
592 want to see the parts of the files near the lines that differ, to help you
593 understand exactly what has changed. These nearby parts of the files are called
599 provides two output formats that show context around the differing lines:
603 It can optionally show in which function or section of the file the differing
606 If you are distributing new versions of files to other people in the form
609 output, you should use one of the output formats that show context so that
610 they can apply the diffs even if they have made small changes of their own
613 can apply the diffs in this case by searching in the files for the lines of
614 context around the differing lines; if those lines are actually a few lines
615 away from where the diff says they are,
617 can adjust the line numbers accordingly and still apply the diff correctly.See Section
619 for more information on using
621 to apply imperfect diffs.
625 The context output format shows several lines of context around the lines
626 that differ. It is the standard format for distributing updates to source
629 To select this output format, use the
631 .Op --context[= Va lines] ,
636 that some of these options take is the number of lines of context to show.
637 If you do not specify
639 it defaults to three. For proper operation,
641 typically needs at least two lines of context.
643 .No An Example of Context Format
645 Here is the output of
648 .Dq Sample diff Input ,
649 for the complete contents of the two files). Notice that up to three lines
650 that are not different are shown around each line that is different; they
651 are the context lines. Also notice that the first two hunks have run together,
652 because their contents overlap.
654 .Bd -literal -offset indent
655 *** lao 2002-02-21 23:30:39.942229878 -0800
656 --- tzu 2002-02-21 23:30:50.442260588 -0800
659 - The Way that can be told of is not the eternal Way;
660 - The name that can be named is not the eternal name.
661 The Nameless is the origin of Heaven and Earth;
662 ! The Named is the mother of all things.
663 Therefore let there always be non-being,
664 so we may see their subtlety,
665 And let there always be being,
667 The Nameless is the origin of Heaven and Earth;
668 ! The named is the mother of all things.
670 Therefore let there always be non-being,
671 so we may see their subtlety,
672 And let there always be being,
676 The two are the same,
677 But after they are produced,
678 they have different names.
679 + They both may be called deep and profound.
680 + Deeper and more profound,
681 + The door of all subtleties!
684 .No An Example of Context Format with Less Context
686 Here is the output of
687 .Li diff -C 1 lao tzu
689 .Dq Sample diff Input ,
690 for the complete contents of the two files). Notice that at most one context
691 line is reported here.
693 .Bd -literal -offset indent
694 *** lao 2002-02-21 23:30:39.942229878 -0800
695 --- tzu 2002-02-21 23:30:50.442260588 -0800
698 - The Way that can be told of is not the eternal Way;
699 - The name that can be named is not the eternal name.
700 The Nameless is the origin of Heaven and Earth;
701 ! The Named is the mother of all things.
702 Therefore let there always be non-being,
704 The Nameless is the origin of Heaven and Earth;
705 ! The named is the mother of all things.
707 Therefore let there always be non-being,
711 they have different names.
712 + They both may be called deep and profound.
713 + Deeper and more profound,
714 + The door of all subtleties!
717 .No Detailed Description of Context Format
719 The context output format starts with a two-line header, which looks like
722 .Bd -literal -offset indent
723 *** from-file from-file-modification-time
724 --- to-file to-file-modification time
727 The time stamp normally looks like
728 .Li 2002-02-21 23:30:39.942229878 -0800
729 to indicate the date, time with fractional seconds, and time zone in
730 .Lk ftp://ftp.isi.edu/in-notes/rfc2822.txt .
731 (The fractional seconds are omitted on hosts that do not support fractional
732 time stamps.) However, a traditional time stamp like
733 .Li Thu Feb 21 23:30:39 2002
736 locale category is either
741 You can change the header's content with the
742 .Op --label= Va label
743 option; see Alternate Names.
745 Next come one or more hunks of differences; each hunk shows one area where
746 the files differ. Context format hunks look like this:
748 .Bd -literal -offset indent
750 *** from-file-line-numbers ****
753 --- to-file-line-numbers ----
758 If a hunk contains two or more lines, its line numbers look like
759 .Li Va start, Va end .
760 Otherwise only its end line number appears. An empty hunk is considered to
761 end at the line that precedes the hunk.
763 The lines of context around the lines that differ start with two space characters.
764 The lines that differ between the two files start with one of the following
765 indicator characters, followed by a space character:
769 A line that is part of a group of one or more lines that changed between the
770 two files. There is a corresponding group of lines marked with
772 in the part of this hunk for the other file.
775 An \(lqinserted\(rq line in the second file that corresponds to nothing in the first
779 A \(lqdeleted\(rq line in the first file that corresponds to nothing in the second
783 If all of the changes in a hunk are insertions, the lines of
785 are omitted. If all of the changes are deletions, the lines of
791 The unified output format is a variation on the context format that is more
792 compact because it omits redundant context lines. To select this output format,
795 .Op --unified[= Va lines] ,
800 is the number of lines of context to show. When it is not given, it defaults
805 can produce this format and only GNU
807 can automatically apply diffs in this format. For proper operation,
809 typically needs at least three lines of context.
811 .No An Example of Unified Format
813 Here is the output of the command
816 .Dq Sample diff Input ,
817 for the complete contents of the two files):
819 .Bd -literal -offset indent
820 --- lao 2002-02-21 23:30:39.942229878 -0800
821 +++ tzu 2002-02-21 23:30:50.442260588 -0800
823 -The Way that can be told of is not the eternal Way;
824 -The name that can be named is not the eternal name.
825 The Nameless is the origin of Heaven and Earth;
826 -The Named is the mother of all things.
827 +The named is the mother of all things.
829 Therefore let there always be non-being,
830 so we may see their subtlety,
831 And let there always be being,
833 The two are the same,
834 But after they are produced,
835 they have different names.
836 +They both may be called deep and profound.
837 +Deeper and more profound,
838 +The door of all subtleties!
841 .No Detailed Description of Unified Format
843 The unified output format starts with a two-line header, which looks like
846 .Bd -literal -offset indent
847 --- from-file from-file-modification-time
848 +++ to-file to-file-modification-time
851 The time stamp looks like
852 .Li 2002-02-21 23:30:39.942229878 -0800
853 to indicate the date, time with fractional seconds, and time zone. The fractional
854 seconds are omitted on hosts that do not support fractional time stamps.
856 You can change the header's content with the
857 .Op --label= Va label
858 option; seeSee Section
859 .Dq Alternate Names .
861 Next come one or more hunks of differences; each hunk shows one area where
862 the files differ. Unified format hunks look like this:
864 .Bd -literal -offset indent
865 @@ from-file-line-numbers to-file-line-numbers @@
866 line-from-either-file
867 line-from-either-file...
870 If a hunk contains just one line, only its start line number appears. Otherwise
871 its line numbers look like
872 .Li Va start, Va count .
873 An empty hunk is considered to start at the line that follows the hunk.
875 If a hunk and its context contain two or more lines, its line numbers look
877 .Li Va start, Va count .
878 Otherwise only its end line number appears. An empty hunk is considered to
879 end at the line that precedes the hunk.
881 The lines common to both files begin with a space character. The lines that
882 actually differ between the two files have one of the following indicator
883 characters in the left print column:
887 A line was added here to the first file.
890 A line was removed here from the first file.
893 .Em Showing Which Sections Differences Are in
895 Sometimes you might want to know which part of the files each change falls
896 in. If the files are source code, this could mean which function was changed.
897 If the files are documents, it could mean which chapter or appendix was changed.
900 can show this by displaying the nearest section heading line that precedes
901 the differing lines. Which lines are \(lqsection headings\(rq is determined by a regular
904 .No Showing Lines That Match Regular Expressions
906 To show in which sections differences occur for files that are not source
907 code for C or similar languages, use the
910 .Op --show-function-line= Va regexp
913 considers lines that match the
915 -style regular expression
917 to be the beginning of a section of the file. Here are suggested regular expressions
918 for some common languages:
929 This option does not automatically select an output format; in order to use
930 it, you must select the context format (see Section
932 or unified format (see Section
933 .Dq Unified Format ) .
934 In other output formats it has no effect.
939 .Op --show-function-line
940 option finds the nearest unchanged line that precedes each hunk of differences
941 and matches the given regular expression. Then it adds that line to the end
942 of the line of asterisks in the context format, or to the
944 line in unified format. If no matching line exists, this option leaves the
945 output for that hunk unchanged. If that line is more than 40 characters long,
946 it outputs only the first 40 characters. You can specify more than one regular
947 expression for such lines;
949 tries to match each line against each regular expression, starting with the
950 last one given. This means that you can use
954 together, if you wish.
956 .No Showing C Function Headings
958 To show in which functions differences occur for C and similar languages,
962 .Op --show-c-function
963 option. This option automatically defaults to the context output format (see Section
964 .Dq Context Format ) ,
965 with the default number of lines of context. You can override that number
968 elsewhere in the command line. You can override both the format and the number
971 elsewhere in the command line.
976 .Op --show-c-function
977 option is equivalent to
978 .Op -F '^[[:alpha:]$_]'
979 if the unified format is specified, otherwise
980 .Op -c -F '^[[:alpha:]$_]'
982 .Dq Specified Headings ) .
985 provides this option for the sake of convenience.
987 .Em Showing Alternate File Names
989 If you are comparing two files that have meaningless or uninformative names,
992 to show alternate names in the header of the context and unified output formats.
994 .Op --label= Va label
995 option. The first time you give this option, its argument replaces the name
996 and date of the first file in the header; the second time, its argument replaces
997 the name and date of the second file. If you give this option more than twice,
999 reports an error. The
1001 option does not affect the file names in the
1007 option is used (see Section
1010 Here are the first two lines of the output from
1011 .Li diff -C 2 --label=original --label=modified lao tzu :
1013 .Bd -literal -offset indent
1018 .Ss Showing Differences Side by Side
1020 can produce a side by side difference listing of two files. The files are
1021 listed in two columns with a gutter between them. The gutter contains one
1022 of the following markers:
1026 The corresponding lines are in common. That is, either the lines are identical,
1027 or the difference is ignored because of one of the
1029 options (see Section
1033 The corresponding lines differ, and they are either both complete or both
1037 The files differ and only the first file contains the line.
1040 The files differ and only the second file contains the line.
1043 Only the first file contains the line, but the difference is ignored.
1046 Only the second file contains the line, but the difference is ignored.
1049 The corresponding lines differ, and only the first line is incomplete.
1052 The corresponding lines differ, and only the second line is incomplete.
1055 Normally, an output line is incomplete if and only if the lines that it contains
1056 are incomplete;See Section
1057 .Dq Incomplete Lines .
1058 However, when an output line represents two differing lines, one might be
1059 incomplete while the other is not. In this case, the output line is complete,
1060 but its the gutter is marked
1062 if the first line is incomplete,
1064 if the second line is.
1066 Side by side format is sometimes easiest to read, but it has limitations.
1067 It generates much wider output than usual, and truncates lines that are too
1068 long to fit. Also, it relies on lining up output more heavily than usual,
1069 so its output looks particularly bad if you use varying width fonts, nonstandard
1070 tab stops, or nonprinting characters.
1074 command to interactively merge side by side differences.See Section
1075 .Dq Interactive Merging ,
1076 for more information on merging files.
1078 .Em Controlling Side by Side Format
1084 option selects side by side format. Because side by side output lines contain
1085 two input lines, the output is wider than usual: normally 130 print columns,
1086 which can fit onto a traditional printer line. You can set the width of the
1090 .Op --width= Va columns
1091 option. The output is split into two halves of equal width, separated by a
1092 small gutter to mark differences; the right half is aligned to a tab stop
1093 so that tabs line up. Input lines that are too long to fit in half of an output
1094 line are truncated for output.
1098 option prints only the left column of two common lines. The
1099 .Op --suppress-common-lines
1100 option suppresses common lines entirely.
1102 .Em An Example of Side by Side Format
1104 Here is the output of the command
1105 .Li diff -y -W 72 lao tzu
1107 .Dq Sample diff Input ,
1108 for the complete contents of the two files).
1110 .Bd -literal -offset indent
1111 The Way that can be told of is n <
1112 The name that can be named is no <
1113 The Nameless is the origin of He The Nameless is the origin of He
1114 The Named is the mother of all t | The named is the mother of all t
1116 Therefore let there always be no Therefore let there always be no
1117 so we may see their subtlety, so we may see their subtlety,
1118 And let there always be being, And let there always be being,
1119 so we may see their outcome. so we may see their outcome.
1120 The two are the same, The two are the same,
1121 But after they are produced, But after they are produced,
1122 they have different names. they have different names.
1123 > They both may be called deep and
1124 > Deeper and more profound,
1125 > The door of all subtleties!
1128 .Ss Showing Differences Without Context
1131 output format shows each hunk of differences without any surrounding context.
1132 Sometimes such output is the clearest way to see how lines have changed, without
1133 the clutter of nearby unchanged lines (although you can get similar results
1134 with the context or unified formats by using 0 lines of context). However,
1135 this format is no longer widely used for sending out patches; for that purpose,
1136 the context format (see Section
1137 .Dq Context Format )
1138 and the unified format (see Section
1139 .Dq Unified Format )
1140 are superior. Normal format is the default for compatibility with older versions
1143 and the POSIX standard. Use the
1145 option to select this output format explicitly.
1147 .Em An Example of Normal Format
1149 Here is the output of the command
1152 .Dq Sample diff Input ,
1153 for the complete contents of the two files). Notice that it shows only the
1154 lines that are different between the two files.
1156 .Bd -literal -offset indent
1158 < The Way that can be told of is not the eternal Way;
1159 < The name that can be named is not the eternal name.
1161 < The Named is the mother of all things.
1163 > The named is the mother of all things.
1166 > They both may be called deep and profound.
1167 > Deeper and more profound,
1168 > The door of all subtleties!
1171 .Em Detailed Description of Normal Format
1173 The normal output format consists of one or more hunks of differences; each
1174 hunk shows one area where the files differ. Normal format hunks look like
1177 .Bd -literal -offset indent
1186 There are three types of change commands. Each consists of a line number or
1187 comma-separated range of lines in the first file, a single character indicating
1188 the kind of change to make, and a line number or comma-separated range of
1189 lines in the second file. All line numbers are the original line numbers in
1190 each file. The types of change commands are:
1194 Add the lines in range
1196 of the second file after line
1198 of the first file. For example,
1200 means append lines 12--15 of file 2 after line 8 of file 1; or, if changing
1201 file 2 into file 1, delete lines 12--15 of file 2.
1204 Replace the lines in range
1206 of the first file with lines in range
1208 of the second file. This is like a combined add and delete, but more compact.
1211 means change lines 5--7 of file 1 to read as lines 8--10 of file 2; or, if
1212 changing file 2 into file 1, change lines 8--10 of file 2 to read as lines
1216 Delete the lines in range
1218 from the first file; line
1220 is where they would have appeared in the second file had they not been deleted.
1223 means delete lines 5--7 of file 1; or, if changing file 2 into file 1, append
1224 lines 5--7 of file 1 after line 3 of file 2.
1227 .Ss Making Edit Scripts
1228 Several output modes produce command scripts for editing
1236 can produce commands that direct the
1238 text editor to change the first file into the second file. Long ago, this
1239 was the only output mode that was suitable for editing one file into another
1240 automatically; today, with
1242 it is almost obsolete. Use the
1246 option to select this output format.
1248 Like the normal format (see Section
1250 this output format does not show any context; unlike the normal format, it
1251 does not include the information necessary to apply the diff in reverse (to
1252 produce the first file if all you have is the second file and the diff).
1256 contains the output of
1257 .Li diff -e old new ,
1259 .Li (cat d && echo w) | ed - old
1262 to make it a copy of
1269 contain the outputs of
1270 .Li diff -e old new1 ,
1271 .Li diff -e new1 new2 ,
1273 .Li diff -e newN-1 newN ,
1274 respectively, then the command
1275 .Li (cat d1 d2 ... dN && echo w) | ed - old
1278 to make it a copy of
1281 .No Example Xr ed Script
1283 Here is the output of
1286 .Dq Sample diff Input ,
1287 for the complete contents of the two files):
1289 .Bd -literal -offset indent
1291 They both may be called deep and profound.
1292 Deeper and more profound,
1293 The door of all subtleties!
1296 The named is the mother of all things.
1302 .No Detailed Description of Xr ed Format
1306 output format consists of one or more hunks of differences. The changes closest
1307 to the ends of the files come first so that commands that change the number
1308 of lines do not affect how
1310 interprets line numbers in succeeding commands.
1312 format hunks look like this:
1314 .Bd -literal -offset indent
1323 uses a single period on a line to indicate the end of input, GNU
1325 protects lines of changes that contain a single period on a line by writing
1326 two periods instead, then writing a subsequent
1328 command to change the two periods into one. The
1330 format cannot represent an incomplete line, so if the second file ends in
1331 a changed incomplete line,
1333 reports an error and then pretends that a newline was appended.
1335 There are three types of change commands. Each consists of a line number or
1336 comma-separated range of lines in the first file and a single character indicating
1337 the kind of change to make. All line numbers are the original line numbers
1338 in the file. The types of change commands are:
1342 Add text from the second file after line
1344 in the first file. For example,
1346 means to add the following lines after line 8 of file 1.
1349 Replace the lines in range
1351 in the first file with the following lines. Like a combined add and delete,
1352 but more compact. For example,
1354 means change lines 5--7 of file 1 to read as the text file 2.
1357 Delete the lines in range
1359 from the first file. For example,
1361 means delete lines 5--7 of file 1.
1364 .Em Forward Xr ed Scripts
1367 can produce output that is like an
1369 script, but with hunks in forward (front to back) order. The format of the
1370 commands is also changed slightly: command characters precede the lines they
1371 modify, spaces separate line numbers in ranges, and no attempt is made to
1372 disambiguate hunk lines consisting of a single period. Like
1376 format cannot represent incomplete lines.
1380 format is not very useful, because neither
1384 can apply diffs in this format. It exists mainly for compatibility with older
1391 option to select it.
1395 The RCS output format is designed specifically for use by the Revision Control
1396 System, which is a set of free programs used for organizing different versions
1397 and systems of files. Use the
1401 option to select this output format. It is like the forward
1405 but it can represent arbitrary changes to the contents of a file because it
1408 format's problems with lines consisting of a single period and with incomplete
1409 lines. Instead of ending text sections with a line consisting of a single
1410 period, each command specifies the number of lines it affects; a combination
1415 commands are used instead of
1417 Also, if the second file ends in a changed incomplete line, then the output
1418 also ends in an incomplete line.
1420 Here is the output of
1423 .Dq Sample diff Input ,
1424 for the complete contents of the two files):
1426 .Bd -literal -offset indent
1430 The named is the mother of all things.
1433 They both may be called deep and profound.
1434 Deeper and more profound,
1435 The door of all subtleties!
1438 .Ss Merging Files with If-then-else
1441 to merge two files of C source code. The output of
1443 in this format contains all the lines of both files. Lines common to both
1444 files are output just once; the differing parts are separated by the C preprocessor
1448 .Li #ifndef Va name ,
1452 When compiling the output, you select which version to use by either defining
1453 or leaving undefined the macro
1456 To merge two files, use
1461 .Op --ifdef= Va name
1462 option. The argument
1464 is the C preprocessor identifier to use in the
1470 For example, if you change an instance of
1473 .Li waitpid (-1, &s, 0)
1474 and then merge the old and new files with the
1475 .Op --ifdef=HAVE_WAITPID
1476 option, then the affected part of your code might look like this:
1478 .Bd -literal -offset indent
1480 #ifndef HAVE_WAITPID
1481 if ((w = wait (&s)) < 0 && errno != EINTR)
1482 #else /* HAVE_WAITPID */
1483 if ((w = waitpid (-1, &s, 0)) < 0 && errno != EINTR)
1484 #endif /* HAVE_WAITPID */
1486 } while (w != child);
1489 You can specify formats for languages other than C by using line group formats
1490 and line formats, as described in the next sections.
1492 .Em Line Group Formats
1494 Line group formats let you specify formats suitable for many applications
1495 that allow if-then-else input, including programming languages and text formatting
1496 languages. A line group format specifies the output format for a contiguous
1497 group of similar lines.
1499 For example, the following command compares the TeX files
1503 and outputs a merged file in which old regions are surrounded by
1507 lines, and new regions are surrounded by
1513 .Bd -literal -offset indent
1515 --old-group-format='\ebegin{em}
1518 --new-group-format='\ebegin{bf}
1524 The following command is equivalent to the above example, but it is a little
1525 more verbose, because it spells out the default line group formats.
1527 .Bd -literal -offset indent
1529 --old-group-format='\ebegin{em}
1532 --new-group-format='\ebegin{bf}
1535 --unchanged-group-format='%=' \e
1536 --changed-group-format='\ebegin{em}
1544 Here is a more advanced example, which outputs a diff listing with headers
1545 containing line numbers in a \(lqplain English\(rq style.
1547 .Bd -literal -offset indent
1549 --unchanged-group-format=\(rq \e
1550 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
1552 --new-group-format='-------- %dN line%(N=1?:s) added after %de:
1554 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
1560 To specify a line group format, use
1562 with one of the options listed below. You can specify up to four line group
1563 formats, one for each kind of line group. You should quote
1565 because it typically contains shell metacharacters.
1568 .It --old-group-format= Va format
1569 These line groups are hunks containing only lines from the first file. The
1570 default old group format is the same as the changed group format if it is
1571 specified; otherwise it is a format that outputs the line group as-is.
1573 .It --new-group-format= Va format
1574 These line groups are hunks containing only lines from the second file. The
1575 default new group format is same as the changed group format if it is specified;
1576 otherwise it is a format that outputs the line group as-is.
1578 .It --changed-group-format= Va format
1579 These line groups are hunks containing lines from both files. The default
1580 changed group format is the concatenation of the old and new group formats.
1582 .It --unchanged-group-format= Va format
1583 These line groups contain lines common to both files. The default unchanged
1584 group format is a format that outputs the line group as-is.
1587 In a line group format, ordinary characters represent themselves; conversion
1588 specifications start with
1590 and have one of the following forms.
1594 stands for the lines from the first file, including the trailing newline.
1595 Each line is formatted according to the old line format (see Section
1596 .Dq Line Formats ) .
1599 stands for the lines from the second file, including the trailing newline.
1600 Each line is formatted according to the new line format.
1603 stands for the lines common to both files, including the trailing newline.
1604 Each line is formatted according to the unchanged line format.
1613 is a single character, stands for
1616 may not be a backslash or an apostrophe. For example,
1618 stands for a colon, even inside the then-part of an if-then-else format, which
1619 a colon would normally terminate.
1624 is a string of 1, 2, or 3 octal digits, stands for the character with octal
1629 stands for a null character.
1636 conversion specification and
1638 is one of the following letters, stands for
1640 \&'s value formatted with
1645 The line number of the line just before the group in the old file.
1648 The line number of the first line in the group in the old file; equals
1653 The line number of the last line in the group in the old file.
1656 The line number of the line just after the group in the old file; equals
1661 The number of lines in the group in the old file; equals
1668 Likewise, for lines in the new file.
1673 conversion specification can be
1679 specifying decimal, octal, lower case hexadecimal, or upper case hexadecimal
1680 output respectively. After the
1682 the following options can appear in sequence: a series of zero or more flags;
1683 an integer specifying the minimum field width; and a period followed by an
1684 optional integer specifying the minimum number of digits. The flags are
1686 for left-justification,
1688 for separating the digit into groups as specified by the
1690 locale category, and
1692 for padding with zeros instead of spaces. For example,
1694 prints the number of new lines in the group in a field of width 5 characters,
1700 .It ( Va A= Va B? Va T: Va E)
1712 are each either a decimal constant or a single letter interpreted as above.
1713 This format spec is equivalent to
1719 \&'s; otherwise it is equivalent to
1723 .Li %(N=0?no:%dN) line%(N=1?:s)
1728 (the number of lines in the group in the new file) is 0, to
1739 Line formats control how each line taken from an input file is output as part
1740 of a line group in if-then-else format.
1742 For example, the following command outputs text with a one-character change
1743 indicator to the left of the text. The first character of output is
1747 for added lines, and a space for unchanged lines. The formats contain newline
1748 characters where newlines are desired on output.
1750 .Bd -literal -offset indent
1752 --old-line-format='-%l
1754 --new-line-format='|%l
1756 --unchanged-line-format=' %l
1761 To specify a line format, use one of the following options. You should quote
1763 since it often contains shell metacharacters.
1766 .It --old-line-format= Va format
1767 formats lines just from the first file.
1769 .It --new-line-format= Va format
1770 formats lines just from the second file.
1772 .It --unchanged-line-format= Va format
1773 formats lines common to both files.
1775 .It --line-format= Va format
1776 formats all lines; in effect, it sets all three above options simultaneously.
1779 In a line format, ordinary characters represent themselves; conversion specifications
1782 and have one of the following forms.
1786 stands for the contents of the line, not counting its trailing newline (if
1787 any). This format ignores whether the line is incomplete;See Section
1788 .Dq Incomplete Lines .
1791 stands for the contents of the line, including its trailing newline (if any).
1792 If a line is incomplete, this format preserves its incompleteness.
1801 is a single character, stands for
1804 may not be a backslash or an apostrophe. For example,
1811 is a string of 1, 2, or 3 octal digits, stands for the character with octal
1816 stands for a null character.
1823 conversion specification, stands for the line number formatted with
1827 prints the line number using the
1831 See Section.Dq Line Group Formats ,
1832 for more about printf conversion specifications.
1835 The default line format is
1837 followed by a newline character.
1839 If the input contains tab characters and it is important that they line up
1840 on output, you should ensure that
1844 in a line format is just after a tab stop (e.g. by preceding
1848 with a tab character), or you should use the
1854 Taken together, the line and line group formats let you specify many different
1855 formats. For example, the following command uses a format similar to normal
1857 format. You can tailor this command to get fine control over
1861 .Bd -literal -offset indent
1863 --old-line-format='< %l
1865 --new-line-format='> %l
1867 --old-group-format='%df%(f=l?:,%dl)d%dE
1869 --new-group-format='%dea%dF%(F=L?:,%dL)
1871 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
1874 --unchanged-group-format=\(rq \e
1878 .Em An Example of If-then-else Format
1880 Here is the output of
1881 .Li diff -DTWO lao tzu
1883 .Dq Sample diff Input ,
1884 for the complete contents of the two files):
1886 .Bd -literal -offset indent
1888 The Way that can be told of is not the eternal Way;
1889 The name that can be named is not the eternal name.
1891 The Nameless is the origin of Heaven and Earth;
1893 The Named is the mother of all things.
1895 The named is the mother of all things.
1898 Therefore let there always be non-being,
1899 so we may see their subtlety,
1900 And let there always be being,
1901 so we may see their outcome.
1902 The two are the same,
1903 But after they are produced,
1904 they have different names.
1906 They both may be called deep and profound.
1907 Deeper and more profound,
1908 The door of all subtleties!
1912 .Em Detailed Description of If-then-else Format
1914 For lines common to both files,
1916 uses the unchanged line group format. For each hunk of differences in the
1917 merged output format, if the hunk contains only lines from the first file,
1919 uses the old line group format; if the hunk contains only lines from the second
1922 uses the new group format; otherwise,
1924 uses the changed group format.
1926 The old, new, and unchanged line formats specify the output format of lines
1927 from the first file, lines from the second file, and lines common to both
1928 files, respectively.
1931 .Op --ifdef= Va name
1932 is equivalent to the following sequence of options using shell syntax:
1934 .Bd -literal -offset indent
1935 --old-group-format='#ifndef name
1936 %<#endif /* ! name */
1938 --new-group-format='#ifdef name
1941 --unchanged-group-format='%=' \e
1942 --changed-group-format='#ifndef name
1948 You should carefully check the
1950 output for proper nesting. For example, when using the
1953 .Op --ifdef= Va name
1954 option, you should check that if the differing lines contain any of the C
1955 preprocessor directives
1962 they are nested properly and match. If they don't, you must make corrections
1963 manually. It is a good idea to carefully check the resulting code anyway to
1964 make sure that it really does what you want it to; depending on how the input
1965 files were produced, the output might contain duplicate or otherwise incorrect
1971 option behaves like the
1974 option, except it operates on a file and a diff to produce a merged file;See Section
1977 .Sh Incomplete Lines
1978 When an input file ends in a non-newline character, its last line is called
1981 because its last character is not a newline. All other lines are called
1983 and end in a newline character. Incomplete lines do not match full lines unless
1984 differences in white space are ignored (see Section
1987 An incomplete line is normally distinguished on output from a full line by
1988 a following line that starts with
1990 However, the RCS format (see Section
1992 outputs the incomplete line as-is, without any trailing newline or following
1993 line. The side by side format normally represents incomplete lines as-is,
1994 but in some cases uses a
1998 gutter marker;See Section
2000 The if-then-else line format preserves a line's incompleteness with
2002 and discards the newline with
2010 output formats (see Section
2011 .Dq Output Formats )
2013 cannot represent an incomplete line, so it pretends there was a newline and
2016 For example, suppose
2020 are one-byte files that contain just
2028 .Bd -literal -offset indent
2031 \e No newline at end of file
2034 \e No newline at end of file
2037 (The exact message may differ in non-English locales.)
2039 outputs the following without a trailing newline:
2041 .Bd -literal -offset indent
2048 reports two errors and outputs the following:
2050 .Bd -literal -offset indent
2056 .Sh Comparing Directories
2059 to compare some or all of the files in two directory trees. When both file
2062 are directories, it compares each file that is contained in both directories,
2063 examining file names in alphabetical order as specified by the
2065 locale category. Normally
2067 is silent about pairs of files that contain no differences, but if you use
2071 .Op --report-identical-files
2072 option, it reports pairs of identical files. Normally
2074 reports subdirectories common to both directories without comparing subdirectories'
2075 files, but if you use the
2079 option, it compares every corresponding pair of files in the directory trees,
2080 as many levels deep as they go.
2082 For file names that are in only one of the directories,
2084 normally does not show the contents of the file that exists; it reports only
2085 that the file exists in that directory and not in the other. You can make
2087 act as though the file existed but was empty in the other directory, so that
2088 it outputs the entire contents of the file that actually exists. (It is output
2089 as either an insertion or a deletion, depending on whether it is in the first
2090 or the second directory given.) To do this, use the
2096 If the older directory contains one or more large files that are not in the
2097 newer directory, you can make the patch smaller by using the
2098 .Op --unidirectional-new-file
2103 except that it only inserts the contents of files that appear in the second
2104 directory but not the first (that is, files that were added). At the top of
2105 the patch, write instructions for the user applying the patch to remove the
2106 files that were deleted before applying the patch.See Section
2107 .Dq Making Patches ,
2108 for more discussion of making patches for distribution.
2110 To ignore some files while comparing directories, use the
2113 .Op --exclude= Va pattern
2114 option. This option ignores any files or subdirectories whose base names match
2117 Unlike in the shell, a period at the start of the base of a file name matches
2118 a wildcard at the start of a pattern. You should enclose
2120 in quotes so that the shell does not expand it. For example, the option
2122 ignores any file whose name ends with
2127 This option accumulates if you specify it more than once. For example, using
2129 .Op -x 'RCS' -x '*,v'
2130 ignores any file or subdirectory whose base name is
2135 If you need to give this option many times, you can instead put the patterns
2136 in a file, one pattern per line, and use the
2139 .Op --exclude-from= Va file
2140 option. Trailing white space and empty lines are ignored in the pattern file.
2142 If you have been comparing two directories and stopped partway through, later
2143 you might want to continue where you left off. You can do this by using the
2146 .Op --starting-file= Va file
2147 option. This compares only the file
2149 and all alphabetically later files in the topmost directory level.
2151 If two directories differ only in that file names are lower case in one directory
2152 and upper case in the upper,
2154 normally reports many differences because it compares file names in a case
2155 sensitive way. With the
2156 .Op --ignore-file-name-case
2159 ignores case differences in file names, so that for example the contents of
2162 in one directory are compared to the contents of the file
2165 .Op --no-ignore-file-name-case
2166 option cancels the effect of the
2167 .Op --ignore-file-name-case
2168 option, reverting to the default behavior.
2173 .Op --exclude= Va pattern
2177 .Op --exclude-from= Va file
2178 option, is specified while the
2179 .Op --ignore-file-name-case
2180 option is in effect, case is ignored when excluding file names matching the
2183 .Sh Making Xr diff Output Prettier
2185 provides several ways to adjust the appearance of its output. These adjustments
2186 can be applied to any output format.
2188 .Ss Preserving Tab Stop Alignment
2189 The lines of text in some of the
2191 output formats are preceded by one or two characters that indicate whether
2192 the text is inserted, deleted, or changed. The addition of those characters
2193 can cause tabs to move to the next tab stop, throwing off the alignment of
2194 columns in the line. GNU
2196 provides two ways to make tab-aligned columns line up correctly.
2198 The first way is to have
2200 convert all tabs into the correct number of spaces before outputting them;
2201 select this method with the
2205 option. To use this form of output with
2212 .Op --ignore-white-space
2214 .Dq Changed White Space ,
2215 for more information).
2217 normally assumes that tab stops are set every 8 print columns, but this can
2219 .Op --tabsize= Va columns
2222 The other method for making tabs line up correctly is to add a tab character
2223 instead of a space after the indicator character at the beginning of the line.
2224 This ensures that all following tab characters are in the same position relative
2225 to tab stops that they were in the original files, so that the output is aligned
2226 correctly. Its disadvantage is that it can make long lines too long to fit
2227 on one line of the screen or the paper. It also does not work with the unified
2228 output format, which does not have a space character after the change type
2229 indicator character. Select this method with the
2235 .Ss Paginating Xr diff Output
2236 It can be convenient to have long output page-numbered and time-stamped. The
2240 option does this by sending the
2244 program. Here is what the page header might look like for
2245 .Li diff -lc lao tzu :
2247 .Bd -literal -offset indent
2248 2002-02-22 14:20 diff -lc lao tzu Page 1
2251 .Sh Xr diff Performance Tradeoffs
2254 runs quite efficiently; however, in some circumstances you can cause it to
2255 run faster or produce a more compact set of changes.
2259 performance is to use hard or symbolic links to files instead of copies. This
2260 improves performance because
2262 normally does not need to read two hard or symbolic links to the same file,
2263 since their contents must be identical. For example, suppose you copy a large
2264 directory hierarchy, make a few changes to the copy, and then often use
2266 to compare the original to the copy. If the original files are read-only,
2267 you can greatly improve performance by creating the copy using hard or symbolic
2268 links (e.g., with GNU
2272 Before editing a file in the copy for the first time, you should break the
2273 link and replace it with a regular copy.
2275 You can also affect the performance of GNU
2277 by giving it options that change the way it compares files. Performance has
2278 more than one dimension. These options improve one aspect of performance at
2279 the cost of another, or they improve performance in some cases while hurting
2284 determines which lines have changed always comes up with a near-minimal set
2285 of differences. Usually it is good enough for practical purposes. If the
2287 output is large, you might want
2289 to use a modified algorithm that sometimes produces a smaller set of differences.
2294 option does this; however, it can also cause
2296 to run more slowly than usual, so it is not the default behavior.
2298 When the files you are comparing are large and have small groups of changes
2299 scattered throughout them, you can use the
2300 .Op --speed-large-files
2301 option to make a different modification to the algorithm that
2303 uses. If the input files have a constant small density of changes, this option
2304 speeds up the comparisons without changing the output. If not,
2306 might produce a larger set of differences; however, the output will still
2311 discards the prefix and suffix that is common to both files before it attempts
2312 to find a minimal set of differences. This makes
2314 run faster, but occasionally it may produce non-minimal output. The
2315 .Op --horizon-lines= Va lines
2318 from discarding the last
2320 lines of the prefix and the first
2322 lines of the suffix. This gives
2324 further opportunities to find a minimal output.
2326 Suppose a run of changed lines includes a sequence of lines at one end and
2327 there is an identical sequence of lines just outside the other end. The
2329 command is free to choose which identical sequence is included in the hunk.
2332 normally shifts the hunk's boundaries when this merges adjacent hunks, or
2333 shifts a hunk's lines towards the end of the file. Merging hunks can make
2334 the output look nicer in some cases.
2336 .Sh Comparing Three Files
2339 to compare three files and show any differences among them. (
2341 can also merge files; see diff3 Merging).
2345 output format shows each hunk of differences without surrounding context.
2346 Hunks are labeled depending on whether they are two-way or three-way, and
2347 lines are annotated by their location in the input files.
2349 See Section.Dq Invoking diff3 ,
2350 for more information on how to run
2353 .Ss A Third Sample Input File
2354 Here is a third sample file that will be used in examples to illustrate the
2357 and how various options can change it. The first two files are the same that
2361 .Dq Sample diff Input ) .
2362 This is the third sample file, called
2365 .Bd -literal -offset indent
2366 The Way that can be told of is not the eternal Way;
2367 The name that can be named is not the eternal name.
2368 The Nameless is the origin of Heaven and Earth;
2369 The named is the mother of all things.
2371 Therefore let there always be non-being,
2372 so we may see their subtlety,
2373 And let there always be being,
2374 so we may see their result.
2375 The two are the same,
2376 But after they are produced,
2377 they have different names.
2379 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2382 .Ss An Example of Xr diff3 Normal Format
2383 Here is the output of the command
2384 .Li diff3 lao tzu tao
2386 .Dq Sample diff3 Input ,
2387 for the complete contents of the files). Notice that it shows only the lines
2388 that are different among the three files.
2390 .Bd -literal -offset indent
2394 The Way that can be told of is not the eternal Way;
2395 The name that can be named is not the eternal name.
2399 The Named is the mother of all things.
2402 The named is the mother of all things.
2407 so we may see their outcome.
2409 so we may see their result.
2413 They both may be called deep and profound.
2414 Deeper and more profound,
2415 The door of all subtleties!
2418 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2421 .Ss Detailed Description of Xr diff3 Normal Format
2422 Each hunk begins with a line marked
2424 Three-way hunks have plain
2426 lines, and two-way hunks have
2431 appended to specify which of the three input files differ in that hunk. The
2432 hunks contain copies of two or three sets of input lines each preceded by
2433 one or two commands identifying where the lines came from.
2435 Normally, two spaces precede each copy of an input line to distinguish it
2436 from the commands. But with the
2442 uses a tab instead of two spaces; this lines up tabs correctly.See Section
2444 for more information.
2446 Commands take the following forms:
2450 This hunk appears after line
2454 and contains no lines in that file. To edit this file to yield the other files,
2455 one must append hunk lines taken from the other files. For example,
2457 means that the hunk follows line 11 in the first file and contains no lines
2461 This hunk contains the lines in the range
2467 is a comma-separated pair of line numbers, or just one number if the range
2468 is a singleton. To edit this file to yield the other files, one must change
2469 the specified lines to be the lines taken from the other files. For example,
2471 means that the hunk contains lines 11 through 13 from the second file.
2474 If the last line in a set of input lines is incomplete (see Section
2475 .Dq Incomplete Lines ) ,
2476 it is distinguished on output from a full line by a following line that starts
2481 Groups of lines that differ in two or three of the input files are called
2487 If all three input files differ in a
2489 hunk, the hunk is called a
2491 ; if just two input files differ, it is a
2496 several solutions are possible. When comparing the files
2504 hunks by merging the two-way hunks output by the two commands
2508 This does not necessarily minimize the size of the output, but exceptions
2511 For example, suppose
2513 contains the three lines
2529 might output the following:
2531 .Bd -literal -offset indent
2547 because it found a two-way hunk containing
2549 in the first and third files and
2551 in the second file, then the single line
2553 common to all three files, then a three-way hunk containing the last line
2556 .Sh Merging From a Common Ancestor
2557 When two people have made changes to copies of the same file,
2559 can produce a merged output that contains both sets of changes together with
2560 warnings about conflicts.
2562 One might imagine programs with names like
2566 to compare more than three files simultaneously, but in practice the need
2567 rarely arises. You can use
2569 to merge three or more sets of changes to a file by merging two change sets
2573 can incorporate changes from two modified versions into a common preceding
2574 version. This lets you merge the sets of changes represented by the two newer
2575 files. Specify the common ancestor version as the second argument and the
2576 two newer versions as the first and third arguments, like this:
2578 .Bd -literal -offset indent
2579 diff3 mine older yours
2582 You can remember the order of the arguments by noting that they are in alphabetical
2585 You can think of this as subtracting
2589 and adding the result to
2593 the changes that would turn
2597 This merging is well-defined as long as
2601 match in the neighborhood of each such change. This fails to be true when
2602 all three input files differ or when only
2604 differs; we call this a
2606 When all three input files differ, we call the conflict an
2610 gives you several ways to handle overlaps and conflicts. You can omit overlaps
2611 or conflicts, or select only overlaps, or mark conflicts with special
2618 can output the merge results as an
2620 script that that can be applied to the first file to yield the merged output.
2621 However, it is usually better to have
2623 generate the merged output directly; this bypasses some problems with
2626 .Ss Selecting Which Changes to Incorporate
2627 You can select all unmerged changes from
2637 option. You can select only the nonoverlapping unmerged changes with
2641 and you can select only the overlapping changes with
2644 .Op --overlap-only .
2652 .Em unmerged changes ,
2657 differ; they ignore changes from
2665 are identical, because they assume that such changes have already been merged.
2666 If this assumption is not a safe one, you can use the
2671 .Dq Marking Conflicts ) .
2673 Here is the output of the command
2675 with each of these three options (see Section
2676 .Dq Sample diff3 Input ,
2677 for the complete contents of the files). Notice that
2679 outputs the union of the disjoint sets of changes output by
2685 .Li diff3 -e lao tzu tao :
2686 .Bd -literal -offset indent
2689 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2692 so we may see their result.
2697 .Li diff3 -3 lao tzu tao :
2698 .Bd -literal -offset indent
2700 so we may see their result.
2705 .Li diff3 -x lao tzu tao :
2706 .Bd -literal -offset indent
2709 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2713 .Ss Marking Conflicts
2715 can mark conflicts in the merged output by bracketing them with special marker
2716 lines. A conflict that comes from two files
2720 is marked as follows:
2722 .Bd -literal -offset indent
2730 A conflict that comes from three files
2735 is marked as follows:
2737 .Bd -literal -offset indent
2751 option acts like the
2753 option, except that it brackets conflicts, and it outputs all changes from
2757 not just the unmerged changes. Thus, given the sample input files (see Section
2758 .Dq Sample diff3 Input ) ,
2759 .Li diff3 -A lao tzu tao
2760 puts brackets around the conflict where only
2764 .Bd -literal -offset indent
2767 The Way that can be told of is not the eternal Way;
2768 The name that can be named is not the eternal name.
2772 And it outputs the three-way conflict as follows:
2774 .Bd -literal -offset indent
2777 They both may be called deep and profound.
2778 Deeper and more profound,
2779 The door of all subtleties!
2782 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2790 option outputs less information than the
2794 option, because it outputs only unmerged changes, and it never outputs the
2795 contents of the second file. Thus the
2797 option acts like the
2799 option, except that it brackets the first and third files from three-way overlapping
2804 except it brackets all its (necessarily overlapping) changes. For example,
2805 for the three-way overlapping change above, the
2809 options output the following:
2811 .Bd -literal -offset indent
2815 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2819 If you are comparing files that have meaningless or uninformative names, you
2821 .Op --label= Va label
2822 option to show alternate names in the
2827 brackets. This option can be given up to three times, once for each input
2829 .Li diff3 -A --label X --label Y --label Z A B C
2831 .Li diff3 -A A B C ,
2832 except that the output looks like it came from files named
2837 rather than from files named
2843 .Ss Generating the Merged Output Directly
2850 outputs the merged file directly. This is more efficient than using
2852 to generate it, and works even with non-text files that
2854 would reject. If you specify
2862 For example, the command
2863 .Li diff3 -m lao tzu tao
2865 .Dq Sample diff3 Input
2866 for a copy of the input files) would output the following:
2868 .Bd -literal -offset indent
2871 The Way that can be told of is not the eternal Way;
2872 The name that can be named is not the eternal name.
2874 The Nameless is the origin of Heaven and Earth;
2875 The Named is the mother of all things.
2876 Therefore let there always be non-being,
2877 so we may see their subtlety,
2878 And let there always be being,
2879 so we may see their result.
2880 The two are the same,
2881 But after they are produced,
2882 they have different names.
2885 They both may be called deep and profound.
2886 Deeper and more profound,
2887 The door of all subtleties!
2890 -- The Way of Lao-Tzu, tr. Wing-tsit Chan
2894 .Ss How Xr diff3 Merges Incomplete Lines
2897 incomplete lines (see Section
2898 .Dq Incomplete Lines )
2899 are simply copied to the output as they are found; if the merged output ends
2900 in an conflict and one of the input files ends in an incomplete line, succeeding
2905 brackets appear somewhere other than the start of a line because they are
2906 appended to the incomplete line.
2912 script option is specified and an incomplete line is found,
2914 generates a warning and acts as if a newline had been present.
2916 .Ss Saving the Changed File
2921 script without the trailing
2925 commands that save the changes. System V
2927 generates these extra commands. GNU
2929 normally behaves like traditional Unix
2933 option it behaves like System V
2943 option requires one of the
2947 and is incompatible with the merged output option
2950 .Sh Interactive Merging with Xr sdiff
2953 you can merge two files interactively based on a side-by-side
2955 format comparison (see Section
2956 .Dq Side by Side ) .
2960 .Op --output= Va file
2961 to specify where to put the merged text.See Section
2962 .Dq Invoking sdiff ,
2963 for more details on the options to
2966 Another way to merge files interactively is to use the Emacs Lisp package
2968 See Section.Dq emerge ,
2969 for more information.
2971 .Ss Specifying Xr diff Options to Xr sdiff
2974 options have the same meaning as for
2976 See Section.Dq diff Options ,
2977 for the use of these options.
2979 .Bd -literal -offset indent
2984 --ignore-blank-lines --ignore-case
2985 --ignore-matching-lines=regexp --ignore-space-change
2986 --ignore-tab-expansion
2987 --left-column --minimal --speed-large-files
2988 --strip-trailing-cr --suppress-common-lines
2989 --tabsize=columns --text --version --width=columns
2992 For historical reasons,
2994 has alternate names for some options. The
2996 option is equivalent to the
2998 option, and similarly
3001 .Op --suppress-common-lines .
3007 options is interchanged from that of
3013 .Op --width= Va columns ,
3017 .Op --ignore-all-space .
3021 option is equivalent to
3028 .Dq Side by Side ) .
3031 Groups of common lines, with a blank gutter, are copied from the first file
3032 to the output. After each group of differing lines,
3036 and pauses, waiting for one of the following commands. Follow each command
3041 Discard both versions. Invoke a text editor on an empty temporary file, then
3042 copy the resulting file to the output.
3045 Concatenate the two versions, edit the result in a temporary file, then copy
3046 the edited result to the output.
3051 except precede each version with a header that shows what file and lines the
3056 Edit a copy of the left version, then copy the result to the output.
3060 Edit a copy of the right version, then copy the result to the output.
3064 Copy the left version to the output.
3071 Copy the right version to the output.
3074 Silently copy common lines.
3077 Verbosely copy common lines. This is the default.
3080 The text editor invoked is specified by the
3082 environment variable if it is set. The default is system-dependent.
3084 .Sh Merging with Xr patch
3086 takes comparison output produced by
3088 and applies the differences to a copy of the original file, producing a patched
3091 you can distribute just the changes to a set of files instead of distributing
3092 the entire file set; your correspondents can apply
3094 to update their copy of the files with your changes.
3096 automatically determines the diff format, skips any leading or trailing headers,
3097 and uses the headers to determine which file to patch. This lets your correspondents
3098 feed a mail message containing a difference listing directly to
3102 detects and warns about common problems like forward patches. It saves any
3103 patches that it could not apply. It can also maintain a
3105 file to ensure that your correspondents apply diffs in the proper order.
3108 accepts a series of diffs in its standard input, usually separated by headers
3109 that specify which file to patch. It applies
3113 one by one. If a hunk does not exactly match the original file,
3115 uses heuristics to try to patch the file as well as it can. If no approximate
3118 rejects the hunk and skips to the next hunk.
3120 normally replaces each file
3122 with its new version, putting reject hunks (if any) into
3125 See Section.Dq Invoking patch ,
3126 for detailed information on the options to
3129 .Ss Selecting the Xr patch Input Format
3131 normally determines which
3133 format the patch file uses by examining its contents. For patch files that
3134 contain particularly confusing leading text, you might need to use one of
3135 the following options to force
3137 to interpret the patch file as a certain format of diff. The output formats
3138 listed here are the only ones that
3161 .Ss Revision Control
3162 If a nonexistent input file is under a revision control system supported by
3165 normally asks the user whether to get (or check out) the file from the revision
3166 control system. Patch currently supports RCS, ClearCase and SCCS. Under RCS
3169 also asks when the input file is read-only and matches the default version
3170 in the revision control system.
3176 option affects access to files under supported revision control systems. If
3180 gets the file without asking the user; if zero,
3182 neither asks the user nor gets the file; and if negative,
3184 asks the user before getting the file. The default value of
3186 is given by the value of the
3188 environment variable if it is set; if not, the default value is zero if
3190 is conforming to POSIX, negative otherwise.See Section
3191 .Dq patch and POSIX .
3193 The choice of revision control system is unaffected by the
3195 environment variable (see Section
3196 .Dq Backup Names ) .
3198 .Ss Applying Imperfect Patches
3200 tries to skip any leading text in the patch file, apply the diff, and then
3201 skip any trailing text. Thus you can feed a mail message directly to
3203 and it should work. If the entire diff is indented by a constant amount of
3206 automatically ignores the indentation. If a context diff contains trailing
3207 carriage return on each line,
3209 automatically ignores the carriage return. If a context diff has been encapsulated
3212 to lines beginning with
3215 .Lk ftp://ftp.isi.edu/in-notes/rfc934.txt ,
3217 automatically unencapsulates the input.
3219 However, certain other types of imperfect input require user intervention
3222 .Em Applying Patches with Changed White Space
3224 Sometimes mailers, editors, or other programs change spaces into tabs, or
3225 vice versa. If this happens to a patch file or an input file, the files might
3228 will not be able to match them properly. If this problem occurs, use the
3231 .Op --ignore-white-space
3234 compare blank characters (i.e. spaces and tabs) loosely so that any nonempty
3235 sequence of blanks in the patch file matches any nonempty sequence of blanks
3236 in the input files. Non-blank characters must still match exactly. Each line
3237 of the context must still match a line in the input file.
3239 .Em Applying Reversed Patches
3241 Sometimes people run
3243 with the new file first instead of second. This creates a diff that is \(lqreversed\(rq.
3244 To apply such patches, give
3252 then attempts to swap each hunk around before applying it. Rejects come out
3253 in the swapped format.
3257 can guess that the patch is reversed. If the first hunk of a patch fails,
3259 reverses the hunk to see if it can apply it that way. If it can,
3261 asks you if you want to have the
3263 option set; if it can't,
3265 continues to apply the patch normally. This method cannot detect a reversed
3266 patch if it is a normal diff and the first command is an append (which should
3267 have been a delete) since appends always succeed, because a null context matches
3268 anywhere. But most patches add or change lines rather than delete them, so
3269 most reversed normal diffs begin with a delete, which fails, and
3273 If you apply a patch that you have already applied,
3275 thinks it is a reversed patch and offers to un-apply the patch. This could
3276 be construed as a feature. If you did this inadvertently and you don't want
3277 to un-apply the patch, just answer
3279 to this offer and to the subsequent \(lqapply anyway\(rq question---or type
3285 .Em Helping Xr patch Find Inexact Matches
3287 For context diffs, and to a lesser extent normal diffs,
3289 can detect when the line numbers mentioned in the patch are incorrect, and
3290 it attempts to find the correct place to apply each hunk of the patch. As
3291 a first guess, it takes the line number mentioned in the hunk, plus or minus
3292 any offset used in applying the previous hunk. If that is not the correct
3295 scans both forward and backward for a set of lines matching the context given
3300 looks for a place where all lines of the context match. If it cannot find
3301 such a place, and it is reading a context or unified diff, and the maximum
3302 fuzz factor is set to 1 or more, then
3304 makes another scan, ignoring the first and last line of context. If that fails,
3305 and the maximum fuzz factor is set to 2 or more, it makes another scan, ignoring
3306 the first two and last two lines of context are ignored. It continues similarly
3307 if the maximum fuzz factor is larger.
3312 .Op --fuzz= Va lines
3313 option sets the maximum fuzz factor to
3315 This option only applies to context and unified diffs; it ignores up to
3317 lines while looking for the place to install a hunk. Note that a larger fuzz
3318 factor increases the odds of making a faulty patch. The default fuzz factor
3319 is 2; there is no point to setting it to more than the number of lines of
3320 context in the diff, ordinarily 3.
3324 cannot find a place to install a hunk of the patch, it writes the hunk out
3325 to a reject file (see Section
3327 for information on how reject files are named). It writes out rejected hunks
3328 in context format no matter what form the input patch is in. If the input
3331 diff, many of the contexts are simply null. The line numbers on the hunks
3332 in the reject file may be different from those in the patch file: they show
3333 the approximate location where
3335 thinks the failed hunks belong in the new file rather than in the old one.
3339 option is given, then as it completes each hunk
3341 tells you whether the hunk succeeded or failed, and if it failed, on which
3342 line (in the new file)
3344 thinks the hunk should go. If this is different from the line number specified
3345 in the diff, it tells you the offset. A single large offset
3349 installed a hunk in the wrong place.
3351 also tells you if it used a fuzz factor to make the match, in which case you
3352 should also be slightly suspicious.
3355 cannot tell if the line numbers are off in an
3357 script, and can only detect wrong line numbers in a normal diff when it finds
3358 a change or delete command. It may have the same problem with a context diff
3359 using a fuzz factor equal to or greater than the number of lines of context
3360 shown in the diff (typically 3). In these cases, you should probably look
3361 at a context diff between your original and patched input files to see if
3362 the changes make sense. Compiling without errors is a pretty good indication
3363 that the patch worked, but not a guarantee.
3365 A patch against an empty file applies to a nonexistent file, and vice versa.See Section
3366 .Dq Creating and Removing .
3369 usually produces the correct results, even when it must make many guesses.
3370 However, the results are guaranteed only when the patch is applied to an exact
3371 copy of the file that the patch was generated from.
3373 .Em Predicting what Xr patch will do
3375 It may not be obvious in advance what
3377 will do with a complicated or poorly formatted patch. If you are concerned
3378 that the input might cause
3380 to modify the wrong files, you can use the
3382 option, which causes
3384 to print the results of applying patches without actually changing any files.
3385 You can then inspect the diagnostics generated by the dry run to see whether
3387 will modify the files that you expect. If the patch does not do what you want,
3388 you can modify the patch (or the other options to
3390 and try another dry run. Once you are satisfied with the proposed patch you
3391 can apply it by invoking
3393 as before, but this time without the
3397 .Ss Creating and Removing Files
3398 Sometimes when comparing two directories, a file may exist in one directory
3399 but not the other. If you give
3405 option, or if you supply an old or new file that is named
3407 or is empty and is dated the Epoch (1970-01-01 00:00:00 UTC),
3409 outputs a patch that adds or deletes the contents of this file. When given
3412 normally creates a new file or removes the old file. However, when conforming
3413 to POSIX (see Section
3414 .Dq patch and POSIX ) ,
3416 does not remove the old file, but leaves it empty. The
3419 .Op --remove-empty-files
3422 to remove output files that are empty after applying a patch, even if the
3423 patch does not appear to be one that removed the file.
3425 If the patch appears to create a file that already exists,
3427 asks for confirmation before applying the patch.
3429 .Ss Updating Time Stamps on Patched Files
3432 updates a file, it normally sets the file's last-modified time stamp to the
3433 current time of day. If you are using
3435 to track a software distribution, this can cause
3437 to incorrectly conclude that a patched file is out of date. For example, if
3449 will normally appear to be out of date with respect to
3451 even though its contents are actually up to date.
3459 to set a patched file's modification and access times to the time stamps given
3460 in context diff headers. If the context diff headers do not specify a time
3461 zone, they are assumed to use Coordinated Universal Time (UTC, often known
3472 except that it assumes that the context diff headers' time stamps use local
3473 time instead of UTC. This option is not recommended, because patches using
3474 local time cannot easily be used by people in other time zones, and because
3475 local time stamps are ambiguous when local clocks move backwards during daylight-saving
3476 time adjustments. If the context diff headers specify a time zone, this option
3483 normally refrains from setting a file's time stamps if the file's original
3484 last-modified time stamp does not match the time given in the diff header,
3485 of if the file's contents do not exactly match the patch. However, if the
3489 option is given, the file's time stamps are set regardless.
3491 Due to the limitations of the current
3495 cannot update the times of files whose contents have not changed. Also, if
3496 you set file time stamps to values other than the current time of day, you
3497 should also remove (e.g., with
3499 all files that depend on the patched files, so that later invocations of
3501 do not get confused by the patched files' times.
3503 .Ss Multiple Patches in a File
3504 If the patch file contains more than one patch, and if you do not specify
3505 an input file on the command line,
3507 tries to apply each patch as if they came from separate patch files. This
3508 means that it determines the name of the file to patch for each patch, and
3509 that it examines the leading text before each patch for file names and prerequisite
3510 revision level (see Section
3511 .Dq Making Patches ,
3512 for more on that topic).
3515 uses the following rules to intuit a file name from the leading text before
3518 takes an ordered list of candidate file names as follows:
3522 If the header is that of a context diff,
3524 takes the old and new file names in the header. A name is ignored if it does
3525 not have enough slashes to satisfy the
3536 line in the leading garbage and if either the old and new names are both absent
3539 is conforming to POSIX,
3541 takes the name in the
3546 For the purpose of the following rules, the candidate file names are considered
3547 to be in the order (old, new, index), regardless of the order that they appear
3553 selects a file name from the candidate list as follows:
3557 If some of the named files exist,
3559 selects the first name if conforming to POSIX, and the best name otherwise.
3564 is not ignoring RCS, ClearCase, and SCCS (see Section
3565 .Dq Revision Control ) ,
3566 and no named files exist but an RCS, ClearCase, or SCCS master is found,
3568 selects the first named file with an RCS, ClearCase, or SCCS master.
3571 If no named files exist, no RCS, ClearCase, or SCCS master was found, some
3574 is not conforming to POSIX, and the patch appears to create a file,
3576 selects the best name requiring the creation of the fewest directories.
3579 If no file name results from the above heuristics, you are asked for the name
3580 of the file to patch, and
3587 of a nonempty list of file names,
3589 first takes all the names with the fewest path name components; of those,
3590 it then takes all the names with the shortest basename; of those, it then
3591 takes all the shortest names; finally, it takes the first remaining name.
3593 See Section.Dq patch and POSIX ,
3596 is conforming to POSIX.
3598 .Ss Applying Patches in Other Directories
3602 .Op --directory= Va directory
3607 the current directory for interpreting both file names in the patch file,
3608 and file names given as arguments to other options (such as
3612 For example, while in a mail reading program, you can patch a file in the
3614 directory directly from a message containing the patch like this:
3616 .Bd -literal -offset indent
3617 | patch -d /usr/src/emacs
3620 Sometimes the file names given in a patch contain leading directories, but
3621 you keep your files in a directory different from the one given in the patch.
3622 In those cases, you can use the
3625 .Op --strip= Va number
3626 option to set the file name strip count to
3628 The strip count tells
3630 how many slashes, along with the directory names between them, to strip from
3631 the front of file names. A sequence of one or more adjacent slashes is counted
3632 as a single slash. By default,
3634 strips off all leading directories, leaving just the base file names.
3636 For example, suppose the file name in the patch file is
3637 .Pa /gnu/src/emacs/etc/NEWS .
3640 gives the entire file name unmodified,
3643 .Pa gnu/src/emacs/etc/NEWS
3654 looks for each file (after any slashes have been stripped) in the current
3655 directory, or if you used the
3657 option, in that directory.
3662 creates a backup file if the patch does not exactly match the original input
3663 file, because in that case the original data might not be recovered if you
3667 .Dq Reversed Patches ) .
3668 However, when conforming to POSIX,
3670 does not create backup files by default.See Section
3671 .Dq patch and POSIX .
3679 to make a backup file regardless of whether the patch matches the original
3681 .Op --backup-if-mismatch
3684 to create backup files for mismatches files; this is the default when not
3685 conforming to POSIX. The
3686 .Op --no-backup-if-mismatch
3689 to not create backup files, even for mismatched patches; this is the default
3690 when conforming to POSIX.
3692 When backing up a file that does not exist, an empty, unreadable backup file
3693 is created as a placeholder to represent the nonexistent file.
3695 .Ss Backup File Names
3698 renames an original input file into a backup file by appending to its name
3705 would make the backup file name too long. The
3706 .Op -z Va backup-suffix
3708 .Op --suffix= Va backup-suffix
3713 as the backup extension instead.
3715 Alternately, you can specify the extension for backup files with the
3716 .Ev SIMPLE_BACKUP_SUFFIX
3717 environment variable, which the options override.
3720 can also create numbered backup files the way GNU Emacs does. With this method,
3721 instead of having a single backup of each file,
3723 makes a new backup file name each time it patches a file. For example, the
3724 backups of a file named
3726 would be called, successively,
3733 .Op -V Va backup-style
3735 .Op --version-control= Va backup-style
3736 option takes as an argument a method for creating backup file names. You can
3737 alternately control the type of backups that
3740 .Ev PATCH_VERSION_CONTROL
3741 environment variable, which the
3743 option overrides. If
3744 .Ev PATCH_VERSION_CONTROL
3747 environment variable is used instead. Please note that these options and variables
3748 control backup file names; they do not affect the choice of revision control
3750 .Dq Revision Control ) .
3752 The values of these environment variables and the argument to the
3754 option are like the GNU Emacs
3756 variable (see Section
3758 for more information on backup versions in Emacs). They also recognize synonyms
3759 that are more descriptive. The valid values are listed below; unique abbreviations
3765 Always make numbered backups.
3769 Make numbered backups of files that already have them, simple backups of the
3770 others. This is the default.
3774 Always make simple backups.
3779 to prepend a prefix, such as a directory name, to produce backup file names.
3783 .Op --prefix= Va prefix
3784 option makes backup files by prepending
3789 .Op --basename-prefix= Va prefix
3792 to the last file name component of backup file names instead; for example,
3794 causes the backup name for
3798 If you use either of these prefix options, the suffix-based options are ignored.
3800 If you specify the output file with the
3802 option, that file is the one that is backed up, not the input file.
3804 Options that affect the names of backup files do not affect whether backups
3805 are made. For example, if you specify the
3806 .Op --no-backup-if-mismatch
3807 option, none of the options described in this section have any affect, because
3808 no backups are made.
3810 .Ss Reject File Names
3811 The names for reject files (files containing patches that
3813 could not find a place to apply) are normally the name of the output file
3820 would make the backup file name too long).
3822 Alternatively, you can tell
3824 to place all of the rejected patches in a single file. The
3825 .Op -r Va reject-file
3827 .Op --reject-file= Va reject-file
3830 as the reject file name.
3832 .Ss Messages and Questions from Xr patch
3834 can produce a variety of messages, especially if it has trouble decoding its
3835 input. In a few situations where it's not sure how to proceed,
3837 normally prompts you for more information from the keyboard. There are options
3838 to produce more or fewer messages, to have it not ask for keyboard input,
3839 and to affect the way that file names are quoted in messages.
3842 exits with status 0 if all hunks are applied successfully, 1 if some hunks
3843 cannot be applied, and 2 if there is more serious trouble. When applying a
3844 set of patches in a loop, you should check the exit status, so you don't apply
3845 a later patch to a partially patched file.
3847 .Em Controlling the Verbosity of Xr patch
3851 to produce more messages by using the
3853 option. For example, when you give this option, the message
3857 is reading text in the patch file, attempting to determine whether there is
3858 a patch in that text, and if so, what kind of patch it is.
3860 You can inhibit all terminal output from
3862 unless an error occurs, by using the
3869 .Em Inhibiting Keyboard Input
3871 There are two ways you can prevent
3873 from asking you any questions. The
3877 option assumes that you know what you are doing. It causes
3879 to do the following:
3883 Skip patches that do not contain file names in their headers.
3886 Patch files even though they have the wrong version for the
3891 Assume that patches are not reversed even if they look like they are.
3898 option is similar to
3900 in that it suppresses questions, but it makes somewhat different assumptions:
3904 Skip patches that do not contain file names in their headers (the same as
3908 Skip patches for which the file has the wrong version for the
3913 Assume that patches are reversed if they look like they are.
3916 .Em Xr patch Quoting Style
3920 outputs a file name in a diagnostic message, it can format the name in any
3921 of several ways. This can be useful to output file names unambiguously, even
3922 if they contain punctuation or special characters like newlines. The
3923 .Op --quoting-style= Va word
3924 option controls how names are output. The
3926 should be one of the following:
3932 Quote names for the shell if they contain shell metacharacters or would cause
3935 Quote names for the shell, even if they would normally not require quoting.
3937 Quote names as for a C language string.
3941 except omit the surrounding double-quote characters.
3944 You can specify the default value of the
3946 option with the environment variable
3948 If that environment variable is not set, the default value is
3950 but this default may change in a future version of
3953 .Ss Xr patch and the POSIX Standard
3958 environment variable,
3960 conforms more strictly to the POSIX standard, as follows:
3964 Take the first existing file from the list (old, new, index) when intuiting
3965 file names from diff headers.See Section
3966 .Dq Multiple Patches .
3969 Do not remove files that are removed by a diff.See Section
3970 .Dq Creating and Removing .
3973 Do not ask whether to get files from RCS, ClearCase, or SCCS.See Section
3974 .Dq Revision Control .
3977 Require that all options precede the files in the command line.
3980 Do not backup files, even when there is a mismatch.See Section
3984 .Ss GNU Xr patch and Traditional Xr patch
3985 The current version of GNU
3987 normally follows the POSIX standard.See Section
3988 .Dq patch and POSIX ,
3989 for the few exceptions to this general rule.
3991 Unfortunately, POSIX redefined the behavior of
3993 in several important ways. You should be aware of the following differences
3994 if you must interoperate with traditional
3998 version 2.1 and earlier.
4006 option's operand was optional, and a bare
4012 option now requires an operand, and
4014 is now equivalent to
4016 For maximum compatibility, use options like
4023 simply counted slashes when stripping path prefixes;
4025 now counts pathname components. That is, a sequence of one or more adjacent
4026 slashes now counts as a single slash. For maximum portability, avoid sending
4034 backups were enabled by default. This behavior is now enabled with the
4040 Conversely, in POSIX
4042 backups are never made, even when there is a mismatch. In GNU
4044 this behavior is enabled with the
4045 .Op --no-backup-if-mismatch
4046 option, or by conforming to POSIX.
4050 option of traditional
4052 is equivalent to the
4060 used a complicated (and incompletely documented) method to intuit the name
4061 of the file to be patched from the patch header. This method did not conform
4062 to POSIX, and had a few gotchas. Now
4064 uses a different, equally complicated (but better documented) method that
4065 is optionally POSIX-conforming; we hope it has fewer gotchas. The two methods
4066 are compatible if the file names in the context diff header and the
4068 line are all identical after prefix-stripping. Your patch is normally compatible
4069 if each header's file names all contain the same number of slashes.
4074 asked the user a question, it sent the question to standard error and looked
4075 for an answer from the first file in the following list that was a terminal:
4076 standard error, standard output,
4078 and standard input. Now
4080 sends questions to standard output and gets answers from
4082 Defaults for some answers have been changed so that
4084 never goes into an infinite loop when using default answers.
4089 exited with a status value that counted the number of bad hunks, or with status
4090 1 if there was real trouble. Now
4092 exits with status 1 if some hunks failed, or with 2 if there was real trouble.
4095 Limit yourself to the following options when sending instructions meant to
4096 be executed by anyone running GNU
4102 that conforms to POSIX. Spaces are significant in the following list, and
4103 operands are required.
4105 .Bd -literal -offset indent
4120 .Sh Tips for Making and Using Patches
4121 Use some common sense when making and using patches. For example, when sending
4122 bug fixes to a program's maintainer, send several small patches, one per independent
4123 subject, instead of one large, harder-to-digest patch that covers all the
4126 Here are some other things you should keep in mind if you are going to distribute
4127 patches for updating a software package.
4129 .Ss Tips for Patch Producers
4130 To create a patch that changes an older version of a package into a newer
4131 version, first make a copy of the older and newer versions in adjacent subdirectories.
4132 It is common to do that by unpacking
4134 archives of the two versions.
4136 To generate the patch, use the command
4137 .Li diff -Naur Va old Va new
4142 identify the old and new directories. The names
4146 should not contain any slashes. The
4148 option lets the patch create and remove files;
4150 lets the patch update non-text files;
4152 generates useful time stamps and enough context; and
4154 lets the patch update subdirectories. Here is an example command, using Bourne
4157 .Bd -literal -offset indent
4158 diff -Naur gcc-3.0.3 gcc-3.0.4
4161 Tell your recipients how to apply the patches. This should include which working
4162 directory to use, and which
4164 options to use; the option
4166 is recommended. Test your procedure by pretending to be a recipient and applying
4167 your patches to a copy of the original files.
4169 See Section.Dq Avoiding Common Mistakes ,
4170 for how to avoid common mistakes when generating a patch.
4172 .Ss Tips for Patch Consumers
4173 A patch producer should tell recipients how to apply the patches, so the first
4174 rule of thumb for a patch consumer is to follow the instructions supplied
4179 can analyze files with arbitrarily long lines and files that end in incomplete
4180 lines. However, older versions of
4182 cannot patch such files. If you are having trouble applying such patches,
4183 try upgrading to a recent version of GNU
4186 .Ss Avoiding Common Mistakes
4187 When producing a patch for multiple files, apply
4189 to directories whose names do not have slashes. This reduces confusion when
4190 the patch consumer specifies the
4192 option, since this option can have surprising results when the old and new
4193 file names have different numbers of slashes. For example, do not send a patch
4194 with a header that looks like this:
4196 .Bd -literal -offset indent
4197 diff -Naur v2.0.29/prog/README prog/README
4198 --- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800
4199 +++ prog/README 2002-03-17 20:49:32.442260588 -0800
4202 because the two file names have different numbers of slashes, and different
4205 interpret the file names differently. To avoid confusion, send output that
4206 looks like this instead:
4208 .Bd -literal -offset indent
4209 diff -Naur v2.0.29/prog/README v2.0.30/prog/README
4210 --- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800
4211 +++ v2.0.30/prog/README 2002-03-17 20:49:32.442260588 -0800
4214 Make sure you have specified the file names correctly, either in a context
4215 diff header or with an
4217 line. Take care to not send out reversed patches, since these make people
4218 wonder whether they have already applied the patch.
4220 Avoid sending patches that compare backup file names like
4224 since this might confuse
4226 into patching a backup file instead of the real file. Instead, send patches
4227 that compare the same base file names in different directories, e.g.
4232 To save people from partially applying a patch before other patches that should
4233 have gone before it, you can make the first patch in the patch file update
4234 a file with a name like
4238 which contains a patch level or version number. If the input file contains
4239 the wrong version number,
4241 will complain immediately.
4243 An even clearer way to prevent this problem is to put a
4245 line before the patch. If the leading text in the patch file contains a line
4249 takes the next word from that line (normally a version number) and checks
4250 whether the next input file contains that word, preceded and followed by either
4251 white space or a newline. If not,
4253 prompts you for confirmation before proceeding. This makes it difficult to
4254 accidentally apply patches in the wrong order.
4256 .Ss Generating Smaller Patches
4257 The simplest way to generate a patch is to use
4260 .Dq Tips for Patch Producers ) ,
4261 but you might be able to reduce the size of the patch by renaming or removing
4262 some files before making the patch. If the older version of the package contains
4263 any files that the newer version does not, or if any files have been renamed
4264 between the two versions, make a list of
4268 commands for the user to execute in the old version directory before applying
4269 the patch. Then run those commands yourself in the scratch directory.
4271 If there are any files that you don't need to include in the patch because
4272 they can easily be rebuilt from other files (for example,
4278 exclude them from the patch by giving
4283 .Dq Comparing Directories ) .
4284 If you want your patch to modify a derived file because your recipients lack
4285 tools to build it, make sure that the patch for the derived file follows any
4286 patches for files that it depends on, so that the recipients' time stamps
4290 Now you can create the patch using
4292 Make sure to specify the scratch directory first and the newer directory second.
4294 Add to the top of the patch a note telling the user any
4298 commands to run before applying the patch. Then you can remove the scratch
4301 You can also shrink the patch size by using fewer lines of context, but bear
4304 typically needs at least two lines for proper operation when patches do not
4305 exactly match the input files.
4310 command compares two files, and if they differ, tells the first byte and line
4311 number where they differ or reports that one file is a prefix of the other.
4312 Bytes and lines are numbered starting with 1. The arguments of
4316 .Bd -literal -offset indent
4317 cmp options... from-file [to-file [from-skip [to-skip]]]
4322 is always the standard input.
4324 also uses the standard input if one file name is omitted. The
4328 operands specify how many bytes to ignore at the start of each file; they
4329 are equivalent to the
4330 .Op --ignore-initial= Va from-skip: Va to-skip
4335 outputs nothing if the two files have the same contents. If one file is a
4336 prefix of the other,
4338 prints to standard error a message of the following form:
4340 .Bd -literal -offset indent
4341 cmp: EOF on shorter-file
4346 prints to standard output a message of the following form:
4348 .Bd -literal -offset indent
4349 from-file to-file differ: char byte-number, line line-number
4352 The message formats can differ outside the POSIX locale. Also, POSIX allows
4353 the EOF message to be followed by a blank and some additional information.
4355 An exit status of 0 means no differences were found, 1 means some differences
4356 were found, and 2 means trouble.
4358 .Ss Options to Xr cmp
4359 Below is a summary of all of the options that GNU
4361 accepts. Most options have two equivalent names, one of which is a single
4364 and the other of which is a long name preceded by
4366 Multiple single letter options (unless they take an argument) can be combined
4367 into a single command line word:
4375 Print the differing bytes. Display control bytes as a
4377 followed by a letter of the alphabet and precede bytes that have the high
4380 (which stands for \(lqmeta\(rq).
4383 Output a summary of usage and then exit.
4386 .It --ignore-initial= Va skip
4387 Ignore any differences in the first
4389 bytes of the input files. Treat files with fewer than
4391 bytes as if they are empty. If
4394 .Op Va from-skip: Va to-skip ,
4397 bytes of the first input file and the first
4399 bytes of the second.
4403 Output the (decimal) byte numbers and (octal) values of all differing bytes,
4404 instead of the default standard output.
4407 .It --bytes= Va count
4415 Do not print anything; only return an exit status indicating whether the files
4420 Output version information and then exit.
4423 In the above table, operands that are byte counts are normally decimal, but
4430 A byte count can be followed by a suffix to specify a multiple of that count;
4431 in this case an omitted integer is understood to be 1. A bare size letter,
4434 specifies a multiple using powers of 1024. A size letter followed by
4436 specifies powers of 1000 instead. For example,
4446 This notation is upward compatible with the
4447 .Lk http://www.bipm.fr/enus/3_SI/si-prefixes.html
4448 for decimal multiples and with the
4449 .Lk http://physics.nist.gov/cuu/Units/binary.html .
4451 The following suffixes are defined. Large sizes like
4453 may be rejected by your computer due to limitations of its arithmetic.
4457 kilobyte: 10^3 = 1000.
4461 kibibyte: 2^10 = 1024.
4463 is special: the SI prefix is
4465 and the IEC 60027-2 prefix is
4467 but tradition and POSIX use
4472 megabyte: 10^6 = 1,000,000.
4475 mebibyte: 2^20 = 1,048,576.
4477 gigabyte: 10^9 = 1,000,000,000.
4480 gibibyte: 2^30 = 1,073,741,824.
4482 terabyte: 10^12 = 1,000,000,000,000.
4485 tebibyte: 2^40 = 1,099,511,627,776.
4487 petabyte: 10^15 = 1,000,000,000,000,000.
4490 pebibyte: 2^50 = 1,125,899,906,842,624.
4492 exabyte: 10^18 = 1,000,000,000,000,000,000.
4495 exbibyte: 2^60 = 1,152,921,504,606,846,976.
4497 zettabyte: 10^21 = 1,000,000,000,000,000,000,000
4500 2^70 = 1,180,591,620,717,411,303,424. (
4502 is a GNU extension to IEC 60027-2.)
4504 yottabyte: 10^24 = 1,000,000,000,000,000,000,000,000.
4507 2^80 = 1,208,925,819,614,629,174,706,176. (
4509 is a GNU extension to IEC 60027-2.)
4512 .Sh Invoking Xr diff
4513 The format for running the
4517 .Bd -literal -offset indent
4518 diff options... files...
4521 In the simplest case, two file names
4527 compares the contents of
4533 stands for text read from the standard input. As a special case,
4535 compares a copy of standard input to itself.
4537 If one file is a directory and the other is not,
4539 compares the file in the directory whose name is that of the non-directory.
4540 The non-directory file must not be
4543 If two file names are given and both are directories,
4545 compares corresponding files in both directories, in alphabetical order; this
4546 comparison is not recursive unless the
4552 never compares the actual contents of a directory as if it were a file. The
4553 file that is fully specified may not be standard input, because standard input
4554 is nameless and the notion of \(lqfile with the same name\(rq does not apply.
4557 .Op --from-file= Va file
4558 option is given, the number of file names is arbitrary, and
4560 is compared to each named file. Similarly, if the
4561 .Op --to-file= Va file
4562 option is given, each named file is compared to
4568 so normally file names may not begin with
4572 as an argument by itself treats the remaining arguments as file names even
4576 An exit status of 0 means no differences were found, 1 means some differences
4577 were found, and 2 means trouble. Normally, differing binary files count as
4578 trouble, but this can be altered by using the
4588 .Ss Options to Xr diff
4589 Below is a summary of all of the options that GNU
4591 accepts. Most options have two equivalent names, one of which is a single
4594 and the other of which is a long name preceded by
4596 Multiple single letter options (unless they take an argument) can be combined
4597 into a single command line word:
4601 Long named options can be abbreviated to any unique prefix of their name.
4602 Brackets ([ and ]) indicate that an option takes an optional argument.
4607 Treat all files as text and compare them line-by-line, even if they do not
4608 seem to be text.See Section
4612 .It --ignore-space-change
4613 Ignore changes in amount of white space.See Section
4617 .It --ignore-blank-lines
4618 Ignore changes that just insert or delete blank lines.See Section
4622 Read and write data in binary mode.See Section
4626 Use the context output format, showing three lines of context.See Section
4627 .Dq Context Format .
4630 .It --context[= Va lines]
4631 Use the context output format, showing
4633 (an integer) lines of context, or three if
4635 is not given.See Section
4636 .Dq Context Format .
4637 For proper operation,
4639 typically needs at least two lines of context.
4643 supports an obsolete option
4645 that has effect when combined with
4649 POSIX 1003.1-2001 (see Section
4650 .Dq Standards conformance )
4651 does not allow this; use
4655 .It --changed-group-format= Va format
4658 to output a line group containing differing lines from both files in if-then-else
4660 .Dq Line Group Formats .
4664 Change the algorithm perhaps find a smaller set of changes. This makes
4666 slower (sometimes much slower).See Section
4667 .Dq diff Performance .
4670 .It --ifdef= Va name
4673 format output, conditional on the preprocessor macro
4675 See Section.Dq If-then-else .
4679 Make output that is a valid
4685 .It --ignore-tab-expansion
4686 Ignore changes due to tab expansion.See Section
4691 Make output that looks vaguely like an
4693 script but has changes in the order they appear in the file.See Section
4697 .It --show-function-line= Va regexp
4698 In context and unified format, for each hunk of differences, show some of
4699 the last preceding line that matches
4701 See Section.Dq Specified Headings .
4703 .It --from-file= Va file
4711 Output a summary of usage and then exit.
4713 .It --horizon-lines= Va lines
4714 Do not discard the last
4716 lines of the common prefix and the first
4718 lines of the common suffix.See Section
4719 .Dq diff Performance .
4723 Ignore changes in case; consider upper- and lower-case letters equivalent.See Section
4727 .It --ignore-matching-lines= Va regexp
4728 Ignore changes that just insert or delete lines that match
4730 See Section.Dq Specified Lines .
4732 .It --ignore-file-name-case
4733 Ignore case when comparing file names during recursive comparison.See Section
4734 .Dq Comparing Directories .
4738 Pass the output through
4740 to paginate it.See Section
4743 .It --label= Va label
4746 instead of the file name in the context format (see Section
4747 .Dq Context Format )
4748 and unified format (see Section
4749 .Dq Unified Format )
4754 Print only the left column of two common lines in side by side format.See Section
4755 .Dq Side by Side Format .
4757 .It --line-format= Va format
4760 to output all input lines in if-then-else format.See Section
4765 Output RCS-format diffs; like
4767 except that each command specifies the number of lines affected.See Section
4772 In directory comparison, if a file is found in only one directory, treat it
4773 as present but empty in the other directory.See Section
4774 .Dq Comparing Directories .
4776 .It --new-group-format= Va format
4779 to output a group of lines taken from just the second file in if-then-else
4781 .Dq Line Group Formats .
4783 .It --new-line-format= Va format
4786 to output a line taken from just the second file in if-then-else format.See Section
4789 .It --old-group-format= Va format
4792 to output a group of lines taken from just the first file in if-then-else
4794 .Dq Line Group Formats .
4796 .It --old-line-format= Va format
4799 to output a line taken from just the first file in if-then-else format.See Section
4803 .It --show-c-function
4804 Show which C function each change is in.See Section
4805 .Dq C Function Headings .
4809 Report only whether the files differ, not the details of the differences.See Section
4814 When comparing directories, recursively compare any subdirectories found.See Section
4815 .Dq Comparing Directories .
4818 .It --report-identical-files
4819 Report when two files are the same.See Section
4820 .Dq Comparing Directories .
4823 .It --starting-file= Va file
4824 When comparing directories, start with the file
4826 This is used for resuming an aborted comparison.See Section
4827 .Dq Comparing Directories .
4829 .It --speed-large-files
4830 Use heuristics to speed handling of large files that have numerous scattered
4831 small changes.See Section
4832 .Dq diff Performance .
4834 .It --strip-trailing-cr
4835 Strip any trailing carriage return at the end of an input line.See Section
4838 .It --suppress-common-lines
4839 Do not print common lines in side by side format.See Section
4840 .Dq Side by Side Format .
4844 Expand tabs to spaces in the output, to preserve the alignment of tabs in
4845 the input files.See Section
4850 Output a tab rather than a space before the text of a line in normal or context
4851 format. This causes the alignment of tabs in the line to look normal.See Section
4854 .It --tabsize= Va columns
4855 Assume that tab stops are set every
4857 (default 8) print columns.See Section
4860 .It --to-file= Va file
4861 Compare each operand to
4868 Use the unified output format, showing three lines of context.See Section
4869 .Dq Unified Format .
4871 .It --unchanged-group-format= Va format
4874 to output a group of common lines taken from both files in if-then-else format.See Section
4875 .Dq Line Group Formats .
4877 .It --unchanged-line-format= Va format
4880 to output a line common to both files in if-then-else format.See Section
4883 .It --unidirectional-new-file
4884 When comparing directories, if a file appears only in the second directory
4885 of the two, treat it as present but empty in the other.See Section
4886 .Dq Comparing Directories .
4889 .It --unified[= Va lines]
4890 Use the unified output format, showing
4892 (an integer) lines of context, or three if
4894 is not given.See Section
4895 .Dq Unified Format .
4896 For proper operation,
4898 typically needs at least two lines of context.
4902 supports an obsolete option
4904 that has effect when combined with
4906 POSIX 1003.1-2001 (see Section
4907 .Dq Standards conformance )
4908 does not allow this; use
4914 Output version information and then exit.
4917 .It --ignore-all-space
4918 Ignore white space when comparing lines.See Section
4922 .It --width= Va columns
4925 (default 130) print columns per line in side by side format.See Section
4926 .Dq Side by Side Format .
4929 .It --exclude= Va pattern
4930 When comparing directories, ignore files and subdirectories whose basenames
4933 See Section.Dq Comparing Directories .
4936 .It --exclude-from= Va file
4937 When comparing directories, ignore files and subdirectories whose basenames
4938 match any pattern contained in
4940 See Section.Dq Comparing Directories .
4944 Use the side by side output format.See Section
4945 .Dq Side by Side Format .
4948 .Sh Invoking Xr diff3
4951 command compares three files and outputs descriptions of their differences.
4952 Its arguments are as follows:
4954 .Bd -literal -offset indent
4955 diff3 options... mine older yours
4958 The files to compare are
4963 At most one of these three file names may be
4967 to read the standard input for that file.
4969 An exit status of 0 means
4971 was successful, 1 means some conflicts were found, and 2 means trouble.
4973 .Ss Options to Xr diff3
4974 Below is a summary of all of the options that GNU
4976 accepts. Multiple single letter options (unless they take an argument) can
4977 be combined into a single command line argument.
4982 Treat all files as text and compare them line-by-line, even if they do not
4983 appear to be text.See Section
4988 Incorporate all unmerged changes from
4994 surrounding conflicts with bracket lines.See Section
4995 .Dq Marking Conflicts .
4997 .It --diff-program= Va program
4998 Use the compatible comparison program
5000 to compare files instead of
5007 script that incorporates all the changes from
5013 See Section.Dq Which Changes .
5019 except bracket lines from overlapping changes' first and third files.See Section
5020 .Dq Marking Conflicts .
5023 an overlapping change looks like this:
5025 .Bd -literal -offset indent
5034 Output a summary of usage and then exit.
5041 commands at the end of the
5043 script for System V compatibility. This option must be combined with one of
5046 options, and may not be combined with
5048 See Section.Dq Saving the Changed File .
5050 .It --label= Va label
5053 for the brackets output by the
5058 options. This option may be given up to three times, one for each input file.
5059 The default labels are the names of the input files. Thus
5060 .Li diff3 --label X --label Y --label Z -m A B C
5062 .Li diff3 -m A B C ,
5063 except that the output looks like it came from files named
5068 rather than from files named
5073 See Section.Dq Marking Conflicts .
5077 Apply the edit script to the first file and send the result to standard output.
5078 Unlike piping the output from
5082 this works even for binary files and incomplete lines.
5084 is assumed if no edit script option is specified.See Section
5087 .It --strip-trailing-cr
5088 Strip any trailing carriage return at the end of an input line.See Section
5093 Output a tab rather than two spaces before the text of a line in normal format.
5094 This causes the alignment of tabs in the line to look normal.See Section
5099 Output version information and then exit.
5105 except output only the overlapping changes.See Section
5111 except output only the overlapping changes. In other words, like
5113 except bracket changes as in
5115 See Section.Dq Marking Conflicts .
5121 except output only the nonoverlapping changes.See Section
5125 .Sh Invoking Xr patch
5128 is invoked like this:
5130 .Bd -literal -offset indent
5134 The full format for invoking
5138 .Bd -literal -offset indent
5139 patch options... [origfile [patchfile]]
5142 You can also specify where to read the patch from with the
5145 .Op --input= Va patchfile
5146 option. If you do not specify
5153 reads the patch (that is, the
5155 output) from the standard input.
5157 If you do not specify an input file on the command line,
5159 tries to intuit from the
5161 (any text in the patch that comes before the
5163 output) which file to edit.See Section
5164 .Dq Multiple Patches .
5168 replaces the original input file with the patched version, possibly after
5169 renaming the original file into a backup file (see Section
5171 for a description of how
5173 names backup files). You can also specify where to put the output with the
5176 .Op --output= Va file
5177 option; however, do not use this option if
5179 is one of the input files.
5181 .Ss Options to Xr patch
5182 Here is a summary of all of the options that GNU
5185 .Dq patch and Tradition ,
5186 for which of these options are safe to use in older versions of
5189 Multiple single-letter options that do not take an argument can be combined
5190 into a single command line argument with only one dash.
5195 Back up the original contents of each file, even if backups would normally
5196 not be made.See Section
5200 .It --prefix= Va prefix
5203 to backup file names.See Section
5206 .It --backup-if-mismatch
5207 Back up the original contents of each file if the patch does not exactly match
5208 the file. This is the default behavior when not conforming to POSIX.See Section
5212 Read and write all files in binary mode, except for standard output and
5214 This option has no effect on POSIX-conforming systems like GNU/Linux. On systems
5215 where this option makes a difference, the patch should be generated by
5216 .Li diff -a --binary .
5217 See Section.Dq Binary .
5221 Interpret the patch file as a context diff.See Section
5225 .It --directory= Va directory
5228 the current directory for interpreting both file names in the patch file,
5229 and file names given as arguments to other options.See Section
5230 .Dq patch Directories .
5233 .It --ifdef= Va name
5234 Make merged if-then-else output using
5236 See Section.Dq If-then-else .
5239 Print the results of applying the patches without actually changing any files.See Section
5244 Interpret the patch file as an
5250 .It --remove-empty-files
5251 Remove output files that are empty after the patches have been applied.See Section
5252 .Dq Creating and Removing .
5256 Assume that the user knows exactly what he or she is doing, and do not ask
5257 any questions.See Section
5258 .Dq patch Messages .
5261 .It --fuzz= Va lines
5262 Set the maximum fuzz factor to
5264 See Section.Dq Inexact .
5270 is positive, get input files from a revision control system as necessary;
5271 if zero, do not get the files; if negative, ask the user whether to get the
5273 .Dq Revision Control .
5276 Output a summary of usage and then exit.
5279 .It --input= Va patchfile
5282 rather than from standard input.See Section
5286 .It --ignore-white-space
5287 Let any sequence of blanks (spaces or tabs) in the patch file match any sequence
5288 of blanks in the input file.See Section
5289 .Dq Changed White Space .
5293 Interpret the patch file as a normal diff.See Section
5300 thinks are reversed or already applied. See also
5302 See Section.Dq Reversed Patches .
5304 .It --no-backup-if-mismatch
5305 Do not back up the original contents of files. This is the default behavior
5306 when conforming to POSIX.See Section
5310 .It --output= Va file
5313 as the output file name.See Section
5317 .It --strip= Va number
5318 Set the file name strip count to
5320 See Section.Dq patch Directories .
5323 Conform to POSIX, as if the
5325 environment variable had been set.See Section
5326 .Dq patch and POSIX .
5328 .It --quoting-style= Va word
5331 to quote names in diagnostics, as if the
5333 environment variable had been set to
5335 See Section.Dq patch Quoting Style .
5337 .It -r Va reject-file
5338 .It --reject-file= Va reject-file
5341 as the reject file name.See Section
5346 Assume that this patch was created with the old and new files swapped.See Section
5347 .Dq Reversed Patches .
5352 Work silently unless an error occurs.See Section
5353 .Dq patch Messages .
5357 Do not ask any questions.See Section
5358 .Dq patch Messages .
5362 Set the modification and access times of patched files from time stamps given
5363 in context diff headers, assuming that the context diff headers use local
5365 .Dq Patching Time Stamps .
5369 Interpret the patch file as a unified diff.See Section
5374 Output version information and then exit.
5376 .It -V Va backup-style
5377 .It --version=control= Va backup-style
5378 Select the naming convention for backup file names.See Section
5382 Print more diagnostics than usual.See Section
5383 .Dq patch Messages .
5386 .It --debug= Va number
5387 Set internal debugging flags. Of interest only to
5392 .It --basename-prefix= Va prefix
5395 to base names of backup files.See Section
5399 .It --suffix= Va suffix
5402 as the backup extension instead of
5406 See Section.Dq Backup Names .
5410 Set the modification and access times of patched files from time stamps given
5411 in context diff headers, assuming that the context diff headers use UTC.See Section
5412 .Dq Patching Time Stamps .
5415 .Sh Invoking Xr sdiff
5418 command merges two files and interactively outputs the results. Its arguments
5421 .Bd -literal -offset indent
5422 sdiff -o outfile options... from-file to-file
5437 compares the file in
5439 whose file name is that of
5445 may not both be directories.
5458 as an argument by itself treats the remaining arguments as file names even
5470 produces a side-by-side difference. This usage is obsolete; use the
5478 An exit status of 0 means no differences were found, 1 means some differences
5479 were found, and 2 means trouble.
5481 .Ss Options to Xr sdiff
5482 Below is a summary of all of the options that GNU
5484 accepts. Each option has two equivalent names, one of which is a single letter
5487 and the other of which is a long name preceded by
5489 Multiple single letter options (unless they take an argument) can be combined
5490 into a single command line argument. Long named options can be abbreviated
5491 to any unique prefix of their name.
5496 Treat all files as text and compare them line-by-line, even if they do not
5497 appear to be text.See Section
5501 .It --ignore-space-change
5502 Ignore changes in amount of white space.See Section
5506 .It --ignore-blank-lines
5507 Ignore changes that just insert or delete blank lines.See Section
5512 Change the algorithm to perhaps find a smaller set of changes. This makes
5514 slower (sometimes much slower).See Section
5515 .Dq diff Performance .
5517 .It --diff-program= Va program
5518 Use the compatible comparison program
5520 to compare files instead of
5524 .It --ignore-tab-expansion
5525 Ignore changes due to tab expansion.See Section
5529 Output a summary of usage and then exit.
5533 Ignore changes in case; consider upper- and lower-case to be the same.See Section
5537 .It --ignore-matching-lines= Va regexp
5538 Ignore changes that just insert or delete lines that match
5540 See Section.Dq Specified Lines .
5544 Print only the left column of two common lines.See Section
5545 .Dq Side by Side Format .
5548 .It --output= Va file
5549 Put merged output into
5551 This option is required for merging.
5554 .It --suppress-common-lines
5555 Do not print common lines.See Section
5556 .Dq Side by Side Format .
5558 .It --speed-large-files
5559 Use heuristics to speed handling of large files that have numerous scattered
5560 small changes.See Section
5561 .Dq diff Performance .
5563 .It --strip-trailing-cr
5564 Strip any trailing carriage return at the end of an input line.See Section
5569 Expand tabs to spaces in the output, to preserve the alignment of tabs in
5570 the input files.See Section
5573 .It --tabsize= Va columns
5574 Assume that tab stops are set every
5576 (default 8) print columns.See Section
5581 Output version information and then exit.
5584 .It --width= Va columns
5587 (default 130) print columns per line.See Section
5588 .Dq Side by Side Format .
5589 Note that for historical reasons, this option is
5598 .It --ignore-all-space
5599 Ignore white space when comparing lines.See Section
5601 Note that for historical reasons, this option is
5610 .Sh Standards conformance
5611 In a few cases, the GNU utilities' default behavior is incompatible with the
5612 POSIX standard. To suppress these incompatibilities, define the
5614 environment variable. Unless you are checking for POSIX conformance, you probably
5615 do not need to define
5616 .Ev POSIXLY_CORRECT .
5618 Normally options and operands can appear in any order, and programs act as
5619 if all the options appear before any operands. For example,
5620 .Li diff lao tzu -C 2
5622 .Li diff -C 2 lao tzu ,
5625 is an option-argument of
5629 environment variable is set, options must appear before operands, unless otherwise
5630 specified for a particular command.
5632 Newer versions of POSIX are occasionally incompatible with older versions.
5633 For example, older versions of POSIX allowed the command
5635 to have the same meaning as
5637 but POSIX 1003.1-2001
5639 no longer allows digit-string options like
5642 The GNU utilities normally conform to the version of POSIX that is standard
5643 for your system. To cause them to conform to a different version of POSIX,
5646 environment variable to a value of the form
5648 specifying the year and month the standard was adopted. Two values are currently
5650 .Ev _POSIX2_VERSION :
5652 stands for POSIX 1003.2-1992, and
5654 stands for POSIX 1003.1-2001. For example, if you are running older software
5655 that assumes an older version of POSIX and uses
5657 you can work around the compatibility problems by setting
5658 .Li _POSIX2_VERSION=199209
5659 in your environment.
5662 Here are some ideas for improving GNU
5666 The GNU project has identified some improvements as potential programming
5667 projects for volunteers. You can also help by reporting any bugs that you
5670 If you are a programmer and would like to contribute something to the GNU
5671 project, please consider volunteering for one of these projects. If you are
5672 seriously contemplating work, please write to
5674 to coordinate with other volunteers.
5676 .Ss Suggested Projects for Improving GNU Xr diff and Xr patch
5677 One should be able to use GNU
5679 to generate a patch from any pair of directory trees, and given the patch
5680 and a copy of one such tree, use
5682 to generate a faithful copy of the other. Unfortunately, some changes to directory
5683 trees cannot be expressed using current patch formats; also,
5685 does not handle some of the existing formats. These shortcomings motivate
5686 the following suggested projects.
5688 .Em Handling Multibyte and Varying-Width Characters
5694 treat each line of input as a string of unibyte characters. This can mishandle
5695 multibyte characters in some cases. For example, when asked to ignore spaces,
5697 does not properly ignore a multibyte space character.
5701 currently assumes that each byte is one column wide, and this assumption is
5702 incorrect in some locales, e.g., locales that use UTF-8 encoding. This causes
5710 These problems need to be fixed without unduly affecting the performance of
5711 the utilities in unibyte environments.
5713 The IBM GNU/Linux Technology Center Internationalization Team has proposed
5714 .Lk http://oss.software.ibm.com/developer/opensource/linux/patches/i18n/diffutils-2.7.2-i18n-0.1.patch.gz .
5715 Unfortunately, these patches are incomplete and are to an older version of
5717 so more work needs to be done in this area.
5719 .Em Handling Changes to the Directory Structure
5724 do not handle some changes to directory structure. For example, suppose one
5725 directory tree contains a directory named
5727 with some subsidiary files, and another contains a file with the same name
5730 does not output enough information for
5732 to transform the directory subtree into the file.
5734 There should be a way to specify that a file has been removed without having
5735 to include its entire contents in the patch file. There should also be a way
5738 that a file was renamed, even if there is no way for
5740 to generate such information. There should be a way to tell
5742 that a file's time stamp has changed, even if its contents have not changed.
5744 These problems can be fixed by extending the
5746 output format to represent changes in directory structure, and extending
5748 to understand these extensions.
5750 .Em Files that are Neither Directories Nor Regular Files
5752 Some files are neither directories nor regular files: they are unusual files
5753 like symbolic links, device special files, named pipes, and sockets. Currently,
5755 treats symbolic links as if they were the pointed-to files, except that a
5758 reports an error if it detects infinite loops of symbolic links (e.g., symbolic
5762 treats other special files like regular files if they are specified at the
5763 top level, but simply reports their presence when comparing directories. This
5766 cannot represent changes to such files. For example, if you change which file
5767 a symbolic link points to,
5769 outputs the difference between the two files, instead of the change to the
5773 should optionally report changes to special files specially, and
5775 should be extended to understand these extensions.
5777 .Em File Names that Contain Unusual Characters
5779 When a file name contains an unusual character like a newline or white space,
5781 generates a patch that
5783 cannot parse. The problem is with format of
5785 output, not just with
5787 because with odd enough file names one can cause
5789 to generate a patch that is syntactically correct but patches the wrong files.
5792 output should be extended to handle all possible file names.
5794 .Em Outputting Diffs in Time Stamp Order
5798 to a multiple-file diff can result in files whose time stamps are out of order.
5801 has options to restore the time stamps of the updated files (see Section
5802 .Dq Patching Time Stamps ) ,
5803 but sometimes it is useful to generate a patch that works even if the recipient
5804 does not have GNU patch, or does not use these options. One way to do this
5805 would be to implement a
5807 option to output diffs in time stamp order.
5809 .Em Ignoring Certain Changes
5811 It would be nice to have a feature for specifying two strings, one in
5815 which should be considered to match. Thus, if the two strings are
5819 then if two lines differ only in that
5821 in file 1 corresponds to
5823 in file 2, the lines are treated as identical.
5825 It is not clear how general this feature can or should be, or what syntax
5826 should be used for it.
5828 A partial substitute is to filter one or both files before comparing, e.g.:
5830 .Bd -literal -offset indent
5831 sed 's/foo/bar/g' file1 | diff - file2
5834 However, this outputs the filtered text, not the original.
5836 .Em Improving Performance
5838 When comparing two large directory structures, one of which was originally
5839 copied from the other with time stamps preserved (e.g., with
5841 it would greatly improve performance if an option told
5843 to assume that two files with the same size and time stamps have the same
5845 .Dq diff Performance .
5848 If you think you have found a bug in GNU
5854 please report it by electronic mail to the
5855 .Lk http://mail.gnu.org/mailman/listinfo/bug-gnu-utils
5856 .Mt bug-gnu-utils@gnu.org .
5857 Please send bug reports for GNU
5860 .Mt bug-patch@gnu.org .
5861 Send as precise a description of the problem as you can, including the output
5864 option and sample input files that produce the bug, if applicable. If you
5865 have a nontrivial fix for the bug, please send it as well. If you have a patch,
5866 please send it too. It may simplify the maintainer's job if the patch is relative
5867 to a recent test release, which you can find in the directory
5868 .Lk ftp://alpha.gnu.org/gnu/diffutils/ .
5870 .Sh Copying This Manual
5871 .Ss GNU Free Documentation License
5872 .Bd -filled -offset indent
5873 Copyright \(co 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place,
5874 Suite 330, Boston, MA 02111-1307, USA
5876 Everyone is permitted to copy and distribute verbatim copies of this license
5877 document, but changing it is not allowed.
5884 The purpose of this License is to make a manual, textbook, or other functional
5887 in the sense of freedom: to assure everyone the effective freedom to copy
5888 and redistribute it, with or without modifying it, either commercially or
5889 noncommercially. Secondarily, this License preserves for the author and publisher
5890 a way to get credit for their work, while not being considered responsible
5891 for modifications made by others.
5893 This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the
5894 document must themselves be free in the same sense. It complements the GNU
5895 General Public License, which is a copyleft license designed for free software.
5897 We have designed this License in order to use it for manuals for free software,
5898 because free software needs free documentation: a free program should come
5899 with manuals providing the same freedoms that the software does. But this
5900 License is not limited to software manuals; it can be used for any textual
5901 work, regardless of subject matter or whether it is published as a printed
5902 book. We recommend this License principally for works whose purpose is instruction
5906 APPLICABILITY AND DEFINITIONS
5908 This License applies to any manual or other work, in any medium, that contains
5909 a notice placed by the copyright holder saying it can be distributed under
5910 the terms of this License. Such a notice grants a world-wide, royalty-free
5911 license, unlimited in duration, to use that work under the conditions stated
5912 herein. The \(lqDocument\(rq, below, refers to any such manual or work. Any member
5913 of the public is a licensee, and is addressed as \(lqyou\(rq. You accept the license
5914 if you copy, modify or distribute the work in a way requiring permission under
5917 A \(lqModified Version\(rq of the Document means any work containing the Document
5918 or a portion of it, either copied verbatim, or with modifications and/or translated
5919 into another language.
5921 A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document
5922 that deals exclusively with the relationship of the publishers or authors
5923 of the Document to the Document's overall subject (or to related matters)
5924 and contains nothing that could fall directly within that overall subject.
5925 (Thus, if the Document is in part a textbook of mathematics, a Secondary Section
5926 may not explain any mathematics.) The relationship could be a matter of historical
5927 connection with the subject or with related matters, or of legal, commercial,
5928 philosophical, ethical or political position regarding them.
5930 The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated,
5931 as being those of Invariant Sections, in the notice that says that the Document
5932 is released under this License. If a section does not fit the above definition
5933 of Secondary then it is not allowed to be designated as Invariant. The Document
5934 may contain zero Invariant Sections. If the Document does not identify any
5935 Invariant Sections then there are none.
5937 The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover
5938 Texts or Back-Cover Texts, in the notice that says that the Document is released
5939 under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover
5940 Text may be at most 25 words.
5942 A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented
5943 in a format whose specification is available to the general public, that is
5944 suitable for revising the document straightforwardly with generic text editors
5945 or (for images composed of pixels) generic paint programs or (for drawings)
5946 some widely available drawing editor, and that is suitable for input to text
5947 formatters or for automatic translation to a variety of formats suitable for
5948 input to text formatters. A copy made in an otherwise Transparent file format
5949 whose markup, or absence of markup, has been arranged to thwart or discourage
5950 subsequent modification by readers is not Transparent. An image format is
5951 not Transparent if used for any substantial amount of text. A copy that is
5952 not \(lqTransparent\(rq is called \(lqOpaque\(rq.
5954 Examples of suitable formats for Transparent copies include plain ascii without
5955 markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly
5956 available DTD, and standard-conforming simple HTML, PostScript or PDF designed
5957 for human modification. Examples of transparent image formats include PNG,
5958 XCF and JPG. Opaque formats include proprietary formats that can be read and
5959 edited only by proprietary word processors, SGML or XML for which the DTD
5960 and/or processing tools are not generally available, and the machine-generated
5961 HTML, PostScript or PDF produced by some word processors for output purposes
5964 The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such
5965 following pages as are needed to hold, legibly, the material this License
5966 requires to appear in the title page. For works in formats which do not have
5967 any title page as such, \(lqTitle Page\(rq means the text near the most prominent
5968 appearance of the work's title, preceding the beginning of the body of the
5971 A section \(lqEntitled XYZ\(rq means a named subunit of the Document whose title either
5972 is precisely XYZ or contains XYZ in parentheses following text that translates
5973 XYZ in another language. (Here XYZ stands for a specific section name mentioned
5974 below, such as \(lqAcknowledgements\(rq, \(lqDedications\(rq, \(lqEndorsements\(rq, or \(lqHistory\(rq.) To
5975 \(lqPreserve the Title\(rq of such a section when you modify the Document means that
5976 it remains a section \(lqEntitled XYZ\(rq according to this definition.
5978 The Document may include Warranty Disclaimers next to the notice which states
5979 that this License applies to the Document. These Warranty Disclaimers are
5980 considered to be included by reference in this License, but only as regards
5981 disclaiming warranties: any other implication that these Warranty Disclaimers
5982 may have is void and has no effect on the meaning of this License.
5987 You may copy and distribute the Document in any medium, either commercially
5988 or noncommercially, provided that this License, the copyright notices, and
5989 the license notice saying this License applies to the Document are reproduced
5990 in all copies, and that you add no other conditions whatsoever to those of
5991 this License. You may not use technical measures to obstruct or control the
5992 reading or further copying of the copies you make or distribute. However,
5993 you may accept compensation in exchange for copies. If you distribute a large
5994 enough number of copies you must also follow the conditions in section 3.
5996 You may also lend copies, under the same conditions stated above, and you
5997 may publicly display copies.
6002 If you publish printed copies (or copies in media that commonly have printed
6003 covers) of the Document, numbering more than 100, and the Document's license
6004 notice requires Cover Texts, you must enclose the copies in covers that carry,
6005 clearly and legibly, all these Cover Texts: Front-Cover Texts on the front
6006 cover, and Back-Cover Texts on the back cover. Both covers must also clearly
6007 and legibly identify you as the publisher of these copies. The front cover
6008 must present the full title with all words of the title equally prominent
6009 and visible. You may add other material on the covers in addition. Copying
6010 with changes limited to the covers, as long as they preserve the title of
6011 the Document and satisfy these conditions, can be treated as verbatim copying
6014 If the required texts for either cover are too voluminous to fit legibly,
6015 you should put the first ones listed (as many as fit reasonably) on the actual
6016 cover, and continue the rest onto adjacent pages.
6018 If you publish or distribute Opaque copies of the Document numbering more
6019 than 100, you must either include a machine-readable Transparent copy along
6020 with each Opaque copy, or state in or with each Opaque copy a computer-network
6021 location from which the general network-using public has access to download
6022 using public-standard network protocols a complete Transparent copy of the
6023 Document, free of added material. If you use the latter option, you must take
6024 reasonably prudent steps, when you begin distribution of Opaque copies in
6025 quantity, to ensure that this Transparent copy will remain thus accessible
6026 at the stated location until at least one year after the last time you distribute
6027 an Opaque copy (directly or through your agents or retailers) of that edition
6030 It is requested, but not required, that you contact the authors of the Document
6031 well before redistributing any large number of copies, to give them a chance
6032 to provide you with an updated version of the Document.
6037 You may copy and distribute a Modified Version of the Document under the conditions
6038 of sections 2 and 3 above, provided that you release the Modified Version
6039 under precisely this License, with the Modified Version filling the role of
6040 the Document, thus licensing distribution and modification of the Modified
6041 Version to whoever possesses a copy of it. In addition, you must do these
6042 things in the Modified Version:
6046 Use in the Title Page (and on the covers, if any) a title distinct from that
6047 of the Document, and from those of previous versions (which should, if there
6048 were any, be listed in the History section of the Document). You may use the
6049 same title as a previous version if the original publisher of that version
6053 List on the Title Page, as authors, one or more persons or entities responsible
6054 for authorship of the modifications in the Modified Version, together with
6055 at least five of the principal authors of the Document (all of its principal
6056 authors, if it has fewer than five), unless they release you from this requirement.
6059 State on the Title page the name of the publisher of the Modified Version,
6063 Preserve all the copyright notices of the Document.
6066 Add an appropriate copyright notice for your modifications adjacent to the
6067 other copyright notices.
6070 Include, immediately after the copyright notices, a license notice giving
6071 the public permission to use the Modified Version under the terms of this
6072 License, in the form shown in the Addendum below.
6075 Preserve in that license notice the full lists of Invariant Sections and required
6076 Cover Texts given in the Document's license notice.
6079 Include an unaltered copy of this License.
6082 Preserve the section Entitled \(lqHistory\(rq, Preserve its Title, and add to it an
6083 item stating at least the title, year, new authors, and publisher of the Modified
6084 Version as given on the Title Page. If there is no section Entitled \(lqHistory\(rq
6085 in the Document, create one stating the title, year, authors, and publisher
6086 of the Document as given on its Title Page, then add an item describing the
6087 Modified Version as stated in the previous sentence.
6090 Preserve the network location, if any, given in the Document for public access
6091 to a Transparent copy of the Document, and likewise the network locations
6092 given in the Document for previous versions it was based on. These may be
6093 placed in the \(lqHistory\(rq section. You may omit a network location for a work
6094 that was published at least four years before the Document itself, or if the
6095 original publisher of the version it refers to gives permission.
6098 For any section Entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, Preserve the Title
6099 of the section, and preserve in the section all the substance and tone of
6100 each of the contributor acknowledgements and/or dedications given therein.
6103 Preserve all the Invariant Sections of the Document, unaltered in their text
6104 and in their titles. Section numbers or the equivalent are not considered
6105 part of the section titles.
6108 Delete any section Entitled \(lqEndorsements\(rq. Such a section may not be included
6109 in the Modified Version.
6112 Do not retitle any existing section to be Entitled \(lqEndorsements\(rq or to conflict
6113 in title with any Invariant Section.
6116 Preserve any Warranty Disclaimers.
6119 If the Modified Version includes new front-matter sections or appendices that
6120 qualify as Secondary Sections and contain no material copied from the Document,
6121 you may at your option designate some or all of these sections as invariant.
6122 To do this, add their titles to the list of Invariant Sections in the Modified
6123 Version's license notice. These titles must be distinct from any other section
6126 You may add a section Entitled \(lqEndorsements\(rq, provided it contains nothing
6127 but endorsements of your Modified Version by various parties---for example,
6128 statements of peer review or that the text has been approved by an organization
6129 as the authoritative definition of a standard.
6131 You may add a passage of up to five words as a Front-Cover Text, and a passage
6132 of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts
6133 in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover
6134 Text may be added by (or through arrangements made by) any one entity. If
6135 the Document already includes a cover text for the same cover, previously
6136 added by you or by arrangement made by the same entity you are acting on behalf
6137 of, you may not add another; but you may replace the old one, on explicit
6138 permission from the previous publisher that added the old one.
6140 The author(s) and publisher(s) of the Document do not by this License give
6141 permission to use their names for publicity for or to assert or imply endorsement
6142 of any Modified Version.
6147 You may combine the Document with other documents released under this License,
6148 under the terms defined in section 4 above for modified versions, provided
6149 that you include in the combination all of the Invariant Sections of all of
6150 the original documents, unmodified, and list them all as Invariant Sections
6151 of your combined work in its license notice, and that you preserve all their
6152 Warranty Disclaimers.
6154 The combined work need only contain one copy of this License, and multiple
6155 identical Invariant Sections may be replaced with a single copy. If there
6156 are multiple Invariant Sections with the same name but different contents,
6157 make the title of each such section unique by adding at the end of it, in
6158 parentheses, the name of the original author or publisher of that section
6159 if known, or else a unique number. Make the same adjustment to the section
6160 titles in the list of Invariant Sections in the license notice of the combined
6163 In the combination, you must combine any sections Entitled \(lqHistory\(rq in the
6164 various original documents, forming one section Entitled \(lqHistory\(rq; likewise
6165 combine any sections Entitled \(lqAcknowledgements\(rq, and any sections Entitled
6166 \(lqDedications\(rq. You must delete all sections Entitled \(lqEndorsements.\(rq
6169 COLLECTIONS OF DOCUMENTS
6171 You may make a collection consisting of the Document and other documents released
6172 under this License, and replace the individual copies of this License in the
6173 various documents with a single copy that is included in the collection, provided
6174 that you follow the rules of this License for verbatim copying of each of
6175 the documents in all other respects.
6177 You may extract a single document from such a collection, and distribute it
6178 individually under this License, provided you insert a copy of this License
6179 into the extracted document, and follow this License in all other respects
6180 regarding verbatim copying of that document.
6183 AGGREGATION WITH INDEPENDENT WORKS
6185 A compilation of the Document or its derivatives with other separate and independent
6186 documents or works, in or on a volume of a storage or distribution medium,
6187 is called an \(lqaggregate\(rq if the copyright resulting from the compilation is
6188 not used to limit the legal rights of the compilation's users beyond what
6189 the individual works permit. When the Document is included in an aggregate,
6190 this License does not apply to the other works in the aggregate which are
6191 not themselves derivative works of the Document.
6193 If the Cover Text requirement of section 3 is applicable to these copies of
6194 the Document, then if the Document is less than one half of the entire aggregate,
6195 the Document's Cover Texts may be placed on covers that bracket the Document
6196 within the aggregate, or the electronic equivalent of covers if the Document
6197 is in electronic form. Otherwise they must appear on printed covers that bracket
6198 the whole aggregate.
6203 Translation is considered a kind of modification, so you may distribute translations
6204 of the Document under the terms of section 4. Replacing Invariant Sections
6205 with translations requires special permission from their copyright holders,
6206 but you may include translations of some or all Invariant Sections in addition
6207 to the original versions of these Invariant Sections. You may include a translation
6208 of this License, and all the license notices in the Document, and any Warranty
6209 Disclaimers, provided that you also include the original English version of
6210 this License and the original versions of those notices and disclaimers. In
6211 case of a disagreement between the translation and the original version of
6212 this License or a notice or disclaimer, the original version will prevail.
6214 If a section in the Document is Entitled \(lqAcknowledgements\(rq, \(lqDedications\(rq, or
6215 \(lqHistory\(rq, the requirement (section 4) to Preserve its Title (section 1) will
6216 typically require changing the actual title.
6221 You may not copy, modify, sublicense, or distribute the Document except as
6222 expressly provided for under this License. Any other attempt to copy, modify,
6223 sublicense or distribute the Document is void, and will automatically terminate
6224 your rights under this License. However, parties who have received copies,
6225 or rights, from you under this License will not have their licenses terminated
6226 so long as such parties remain in full compliance.
6229 FUTURE REVISIONS OF THIS LICENSE
6231 The Free Software Foundation may publish new, revised versions of the GNU
6232 Free Documentation License from time to time. Such new versions will be similar
6233 in spirit to the present version, but may differ in detail to address new
6234 problems or concerns. See
6235 .Lk http://www.gnu.org/copyleft/ .
6237 Each version of the License is given a distinguishing version number. If the
6238 Document specifies that a particular numbered version of this License \(lqor any
6239 later version\(rq applies to it, you have the option of following the terms and
6240 conditions either of that specified version or of any later version that has
6241 been published (not as a draft) by the Free Software Foundation. If the Document
6242 does not specify a version number of this License, you may choose any version
6243 ever published (not as a draft) by the Free Software Foundation.
6246 .Em ADDENDUM: How to use this License for your documents
6248 To use this License in a document you have written, include a copy of the
6249 License in the document and put the following copyright and license notices
6250 just after the title page:
6252 .Bd -literal -offset indent
6254 Copyright (C) year your name.
6255 Permission is granted to copy, distribute and/or modify this document
6256 under the terms of the GNU Free Documentation License, Version 1.2
6257 or any later version published by the Free Software Foundation;
6258 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
6259 Texts. A copy of the license is included in the section entitled \(lqGNU
6260 Free Documentation License\(rq.
6264 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace
6265 the \(lqwith...Texts.\(rq line with this:
6267 .Bd -literal -offset indent
6269 with the Invariant Sections being list their titles, with
6270 the Front-Cover Texts being list, and with the Back-Cover Texts
6275 If you have Invariant Sections without Cover Texts, or some other combination
6276 of the three, merge those two alternatives to suit the situation.
6278 If your document contains nontrivial examples of program code, we recommend
6279 releasing these examples in parallel under your choice of free software license,
6280 such as the GNU General Public License, to permit their use in free software.
6282 .Sh Translations of This Manual
6283 Nishio Futoshi of the GNUjdoc project has prepared a Japanese translation
6284 of this manual. Its most recent version can be found at
6285 .Lk http://openlab.ring.gr.jp/gnujdoc/cvsweb/cvsweb.cgi/gnujdoc/ .
projects / FreeBSD / FreeBSD.git / blob