Convert texinfo to mdoc(7) using texi2mdoc

1 files changed, 6287 insertions, 0 deletions

diff --git a/contrib/diff/doc/diff.7 b/contrib/diff/doc/diff.7
new file mode 100644
index 0000000..e973c12
--- /dev/null
+++ b/contrib/diff/doc/diff.7
@@ -0,0 +1,6287 @@
+.Dd 2015-03-02
+.Dt DIFF 7
+.Os
+.Sh NAME
+.Nm diff
+.Nd Comparing and Merging Files
+.Sh  Comparing and Merging Files
+.Sh  Overview
+Computer users often find occasion to ask how two files differ. Perhaps one
+file is a newer version of the other file. Or maybe the two files started
+out as identical copies but were changed by different people.
+.Pp
+You can use the
+.Xr diff
+command to show differences between two files, or each corresponding file
+in two directories.
+.Xr diff
+outputs differences between files line by line in any of several formats,
+selectable by command line options. This set of differences is often called
+a
+.Em diff
+or
+.Em patch .
+For files that are identical,
+.Xr diff
+normally produces no output; for binary (non-text) files,
+.Xr diff
+normally reports only that they are different.
+.Pp
+You can use the
+.Xr cmp
+command to show the byte and line numbers where two files differ.
+.Xr cmp
+can also show all the bytes that differ between the two files, side by side.
+A way to compare two files character by character is the Emacs command
+.Li M-x compare-windows .
+See Section.Dq Other Window ,
+for more information on that command.
+.Pp
+You can use the
+.Xr diff3
+command to show differences among three files. When two people have made independent
+changes to a common original,
+.Xr diff3
+can report the differences between the original and the two changed versions,
+and can produce a merged file that contains both persons' changes together
+with warnings about conflicts.
+.Pp
+You can use the
+.Xr sdiff
+command to merge two files interactively.
+.Pp
+You can use the set of differences produced by
+.Xr diff
+to distribute updates to text files (such as program source code) to other
+people. This method is especially useful when the differences are small compared
+to the complete files. Given
+.Xr diff
+output, you can use the
+.Xr patch
+program to update, or
+.Em patch ,
+a copy of the file. If you think of
+.Xr diff
+as subtracting one file from another to produce their difference, you can
+think of
+.Xr patch
+as adding the difference to one file to reproduce the other.
+.Pp
+This manual first concentrates on making diffs, and later shows how to use
+diffs to update files.
+.Pp
+GNU
+.Xr diff
+was written by Paul Eggert, Mike Haertel, David Hayes, Richard Stallman, and
+Len Tower. Wayne Davison designed and implemented the unified output format.
+The basic algorithm is described by Eugene W. Myers in \(lqAn O(ND) Difference
+Algorithm and its Variations\(rq,
+.Em Algorithmica
+Vol. 1 No. 2, 1986, pp. 251--266; and in \(lqA File Comparison Program\(rq, Webb Miller
+and Eugene W. Myers,
+.Em Software---Practice and Experience
+Vol. 15 No. 11, 1985, pp. 1025--1040. The algorithm was independently discovered
+as described by E. Ukkonen in \(lqAlgorithms for Approximate String Matching\(rq,
+.Em Information and Control
+Vol. 64, 1985, pp. 100--118. Unless the
+.Op --minimal
+option is used,
+.Xr diff
+uses a heuristic by Paul Eggert that limits the cost to O(N^1.5 log N) at
+the price of producing suboptimal output for large inputs with many differences.
+Related algorithms are surveyed by Alfred V. Aho in section 6.3 of \(lqAlgorithms
+for Finding Patterns in Strings\(rq,
+.Em Handbook of Theoretical Computer Science
+(Jan Van Leeuwen, ed.), Vol. A,
+.Em Algorithms and Complexity ,
+Elsevier/MIT Press, 1990, pp. 255--300.
+.Pp
+GNU
+.Xr diff3
+was written by Randy Smith. GNU
+.Xr sdiff
+was written by Thomas Lord. GNU
+.Xr cmp
+was written by Torbj\(:orn Granlund and David MacKenzie.
+.Pp
+GNU
+.Xr patch
+was written mainly by Larry Wall and Paul Eggert; several GNU enhancements
+were contributed by Wayne Davison and David MacKenzie. Parts of this manual
+are adapted from a manual page written by Larry Wall, with his permission.
+.Pp
+.Sh  What Comparison Means
+There are several ways to think about the differences between two files. One
+way to think of the differences is as a series of lines that were deleted
+from, inserted in, or changed in one file to produce the other file.
+.Xr diff
+compares two files line by line, finds groups of lines that differ, and reports
+each group of differing lines. It can report the differing lines in several
+formats, which have different purposes.
+.Pp
+GNU
+.Xr diff
+can show whether files are different without detailing the differences. It
+also provides ways to suppress certain kinds of differences that are not important
+to you. Most commonly, such differences are changes in the amount of white
+space between words or lines.
+.Xr diff
+also provides ways to suppress differences in alphabetic case or in lines
+that match a regular expression that you provide. These options can accumulate;
+for example, you can ignore changes in both white space and alphabetic case.
+.Pp
+Another way to think of the differences between two files is as a sequence
+of pairs of bytes that can be either identical or different.
+.Xr cmp
+reports the differences between two files byte by byte, instead of line by
+line. As a result, it is often more useful than
+.Xr diff
+for comparing binary files. For text files,
+.Xr cmp
+is useful mainly when you want to know only whether two files are identical,
+or whether one file is a prefix of the other.
+.Pp
+To illustrate the effect that considering changes byte by byte can have compared
+with considering them line by line, think of what happens if a single newline
+character is added to the beginning of a file. If that file is then compared
+with an otherwise identical file that lacks the newline at the beginning,
+.Xr diff
+will report that a blank line has been added to the file, while
+.Xr cmp
+will report that almost every byte of the two files differs.
+.Pp
+.Xr diff3
+normally compares three input files line by line, finds groups of lines that
+differ, and reports each group of differing lines. Its output is designed
+to make it easy to inspect two different sets of changes to the same file.
+.Pp
+.Ss  Hunks
+When comparing two files,
+.Xr diff
+finds sequences of lines common to both files, interspersed with groups of
+differing lines called
+.Em hunks .
+Comparing two identical files yields one sequence of common lines and no hunks,
+because no lines differ. Comparing two entirely different files yields no
+common lines and one large hunk that contains all lines of both files. In
+general, there are many ways to match up lines between two given files.
+.Xr diff
+tries to minimize the total hunk size by finding large sequences of common
+lines interspersed with small hunks of differing lines.
+.Pp
+For example, suppose the file
+.Pa F
+contains the three lines
+.Li a ,
+.Li b ,
+.Li c ,
+and the file
+.Pa G
+contains the same three lines in reverse order
+.Li c ,
+.Li b ,
+.Li a .
+If
+.Xr diff
+finds the line
+.Li c
+as common, then the command
+.Li diff F G
+produces this output:
+.Pp
+.Bd -literal -offset indent
+1,2d0
+< a
+< b
+3a2,3
+> b
+> a
+.Ed
+.Pp
+But if
+.Xr diff
+notices the common line
+.Li b
+instead, it produces this output:
+.Pp
+.Bd -literal -offset indent
+1c1
+< a
+---
+> c
+3c3
+< c
+---
+> a
+.Ed
+.Pp
+It is also possible to find
+.Li a
+as the common line.
+.Xr diff
+does not always find an optimal matching between the files; it takes shortcuts
+to run faster. But its output is usually close to the shortest possible. You
+can adjust this tradeoff with the
+.Op -d
+or
+.Op --minimal
+option (see Section
+.Dq diff Performance ) .
+.Pp
+.Ss  Suppressing Differences in Blank and Tab Spacing
+The
+.Op -E
+or
+.Op --ignore-tab-expansion
+option ignores the distinction between tabs and spaces on input. A tab is
+considered to be equivalent to the number of spaces to the next tab stop (see Section
+.Dq Tabs ) .
+.Pp
+The
+.Op -b
+or
+.Op --ignore-space-change
+option is stronger. It ignores white space at line end, and considers all
+other sequences of one or more white space characters within a line to be
+equivalent. With this option,
+.Xr diff
+considers the following two lines to be equivalent, where
+.Li $
+denotes the line end:
+.Pp
+.Bd -literal -offset indent
+Here lyeth  muche rychnesse  in lytell space.   -- John Heywood$
+Here lyeth muche rychnesse in lytell space. -- John Heywood   $
+.Ed
+.Pp
+The
+.Op -w
+or
+.Op --ignore-all-space
+option is stronger still. It ignores differences even if one line has white
+space where the other line has none.
+.Em White space
+characters include tab, newline, vertical tab, form feed, carriage return,
+and space; some locales may define additional characters to be white space.
+With this option,
+.Xr diff
+considers the following two lines to be equivalent, where
+.Li $
+denotes the line end and
+.Li ^M
+denotes a carriage return:
+.Pp
+.Bd -literal -offset indent
+Here lyeth  muche  rychnesse in lytell space.--  John Heywood$
+  He relyeth much erychnes  seinly tells pace.  --John Heywood   ^M$
+.Ed
+.Pp
+.Ss  Suppressing Differences Whose Lines Are All Blank
+The
+.Op -B
+or
+.Op --ignore-blank-lines
+option ignores changes that consist entirely of blank lines. With this option,
+for example, a file containing
+.Bd -literal -offset indent
+1.  A point is that which has no part.
+
+2.  A line is breadthless length.
+-- Euclid, The Elements, I
+.Ed
+is considered identical to a file containing
+.Bd -literal -offset indent
+1.  A point is that which has no part.
+2.  A line is breadthless length.
+
+
+-- Euclid, The Elements, I
+.Ed
+.Pp
+Normally this option affects only lines that are completely empty, but if
+you also specify the
+.Op -b
+or
+.Op --ignore-space-change
+option, or the
+.Op -w
+or
+.Op --ignore-all-space
+option, lines are also affected if they look empty but contain white space.
+In other words,
+.Op -B
+is equivalent to
+.Li -I '^$'
+by default, but it is equivalent to
+.Op -I '^[[:space:]]*$'
+if
+.Op -b
+or
+.Op -w
+is also specified.
+.Pp
+.Ss  Suppressing Differences Whose Lines All Match a Regular Expression
+To ignore insertions and deletions of lines that match a
+.Xr grep
+-style regular expression, use the
+.Op -I Va regexp
+or
+.Op --ignore-matching-lines= Va regexp
+option. You should escape regular expressions that contain shell metacharacters
+to prevent the shell from expanding them. For example,
+.Li diff -I '^[[:digit:]]'
+ignores all changes to lines beginning with a digit.
+.Pp
+However,
+.Op -I
+only ignores the insertion or deletion of lines that contain the regular expression
+if every changed line in the hunk---every insertion and every deletion---matches
+the regular expression. In other words, for each nonignorable change,
+.Xr diff
+prints the complete set of changes in its vicinity, including the ignorable
+ones.
+.Pp
+You can specify more than one regular expression for lines to ignore by using
+more than one
+.Op -I
+option.
+.Xr diff
+tries to match each line against each regular expression.
+.Pp
+.Ss  Suppressing Case Differences
+GNU
+.Xr diff
+can treat lower case letters as equivalent to their upper case counterparts,
+so that, for example, it considers
+.Li Funky Stuff ,
+.Li funky STUFF ,
+and
+.Li fUNKy stuFf
+to all be the same. To request this, use the
+.Op -i
+or
+.Op --ignore-case
+option.
+.Pp
+.Ss  Summarizing Which Files Differ
+When you only want to find out whether files are different, and you don't
+care what the differences are, you can use the summary output format. In this
+format, instead of showing the differences between the files,
+.Xr diff
+simply reports whether files differ. The
+.Op -q
+or
+.Op --brief
+option selects this output format.
+.Pp
+This format is especially useful when comparing the contents of two directories.
+It is also much faster than doing the normal line by line comparisons, because
+.Xr diff
+can stop analyzing the files as soon as it knows that there are any differences.
+.Pp
+You can also get a brief indication of whether two files differ by using
+.Xr cmp .
+For files that are identical,
+.Xr cmp
+produces no output. When the files differ, by default,
+.Xr cmp
+outputs the byte and line number where the first difference occurs, or reports
+that one file is a prefix of the other. You can use the
+.Op -s ,
+.Op --quiet ,
+or
+.Op --silent
+option to suppress that information, so that
+.Xr cmp
+produces no output and reports whether the files differ using only its exit
+status (see Section
+.Dq Invoking cmp ) .
+.Pp
+Unlike
+.Xr diff ,
+.Xr cmp
+cannot compare directories; it can only compare two files.
+.Pp
+.Ss  Binary Files and Forcing Text Comparisons
+If
+.Xr diff
+thinks that either of the two files it is comparing is binary (a non-text
+file), it normally treats that pair of files much as if the summary output
+format had been selected (see Section
+.Dq Brief ) ,
+and reports only that the binary files are different. This is because line
+by line comparisons are usually not meaningful for binary files.
+.Pp
+.Xr diff
+determines whether a file is text or binary by checking the first few bytes
+in the file; the exact number of bytes is system dependent, but it is typically
+several thousand. If every byte in that part of the file is non-null,
+.Xr diff
+considers the file to be text; otherwise it considers the file to be binary.
+.Pp
+Sometimes you might want to force
+.Xr diff
+to consider files to be text. For example, you might be comparing text files
+that contain null characters;
+.Xr diff
+would erroneously decide that those are non-text files. Or you might be comparing
+documents that are in a format used by a word processing system that uses
+null characters to indicate special formatting. You can force
+.Xr diff
+to consider all files to be text files, and compare them line by line, by
+using the
+.Op -a
+or
+.Op --text
+option. If the files you compare using this option do not in fact contain
+text, they will probably contain few newline characters, and the
+.Xr diff
+output will consist of hunks showing differences between long lines of whatever
+characters the files contain.
+.Pp
+You can also force
+.Xr diff
+to report only whether files differ (but not how). Use the
+.Op -q
+or
+.Op --brief
+option for this.
+.Pp
+Normally, differing binary files count as trouble because the resulting
+.Xr diff
+output does not capture all the differences. This trouble causes
+.Xr diff
+to exit with status 2. However, this trouble cannot occur with the
+.Op -a
+or
+.Op --text
+option, or with the
+.Op -q
+or
+.Op --brief
+option, as these options both cause
+.Xr diff
+to generate a form of output that represents differences as requested.
+.Pp
+In operating systems that distinguish between text and binary files,
+.Xr diff
+normally reads and writes all data as text. Use the
+.Op --binary
+option to force
+.Xr diff
+to read and write binary data instead. This option has no effect on a POSIX-compliant
+system like GNU or traditional Unix. However, many personal computer operating
+systems represent the end of a line with a carriage return followed by a newline.
+On such systems,
+.Xr diff
+normally ignores these carriage returns on input and generates them at the
+end of each output line, but with the
+.Op --binary
+option
+.Xr diff
+treats each carriage return as just another input character, and does not
+generate a carriage return at the end of each output line. This can be useful
+when dealing with non-text files that are meant to be interchanged with POSIX-compliant
+systems.
+.Pp
+The
+.Op --strip-trailing-cr
+causes
+.Xr diff
+to treat input lines that end in carriage return followed by newline as if
+they end in plain newline. This can be useful when comparing text that is
+imperfectly imported from many personal computer operating systems. This option
+affects how lines are read, which in turn affects how they are compared and
+output.
+.Pp
+If you want to compare two files byte by byte, you can use the
+.Xr cmp
+program with the
+.Op -l
+or
+.Op --verbose
+option to show the values of each differing byte in the two files. With GNU
+.Xr cmp ,
+you can also use the
+.Op -b
+or
+.Op --print-bytes
+option to show the ASCII representation of those bytes.See Section
+.Dq Invoking cmp ,
+for more information.
+.Pp
+If
+.Xr diff3
+thinks that any of the files it is comparing is binary (a non-text file),
+it normally reports an error, because such comparisons are usually not useful.
+.Xr diff3
+uses the same test as
+.Xr diff
+to decide whether a file is binary. As with
+.Xr diff ,
+if the input files contain a few non-text bytes but otherwise are like text
+files, you can force
+.Xr diff3
+to consider all files to be text files and compare them line by line by using
+the
+.Op -a
+or
+.Op --text
+option.
+.Pp
+.Sh  Xr diff Output Formats
+.Xr diff
+has several mutually exclusive options for output format. The following sections
+describe each format, illustrating how
+.Xr diff
+reports the differences between two sample input files.
+.Pp
+.Ss  Two Sample Input Files
+Here are two sample files that we will use in numerous examples to illustrate
+the output of
+.Xr diff
+and how various options can change it.
+.Pp
+This is the file
+.Pa lao :
+.Pp
+.Bd -literal -offset indent
+The Way that can be told of is not the eternal Way;
+The name that can be named is not the eternal name.
+The Nameless is the origin of Heaven and Earth;
+The Named is the mother of all things.
+Therefore let there always be non-being,
+  so we may see their subtlety,
+And let there always be being,
+  so we may see their outcome.
+The two are the same,
+But after they are produced,
+  they have different names.
+.Ed
+.Pp
+This is the file
+.Pa tzu :
+.Pp
+.Bd -literal -offset indent
+The Nameless is the origin of Heaven and Earth;
+The named is the mother of all things.
+
+Therefore let there always be non-being,
+  so we may see their subtlety,
+And let there always be being,
+  so we may see their outcome.
+The two are the same,
+But after they are produced,
+  they have different names.
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+.Ed
+.Pp
+In this example, the first hunk contains just the first two lines of
+.Pa lao ,
+the second hunk contains the fourth line of
+.Pa lao
+opposing the second and third lines of
+.Pa tzu ,
+and the last hunk contains just the last three lines of
+.Pa tzu .
+.Pp
+.Ss  Showing Differences in Their Context
+Usually, when you are looking at the differences between files, you will also
+want to see the parts of the files near the lines that differ, to help you
+understand exactly what has changed. These nearby parts of the files are called
+the
+.Em context .
+.Pp
+GNU
+.Xr diff
+provides two output formats that show context around the differing lines:
+.Em context format
+and
+.Em unified format .
+It can optionally show in which function or section of the file the differing
+lines are found.
+.Pp
+If you are distributing new versions of files to other people in the form
+of
+.Xr diff
+output, you should use one of the output formats that show context so that
+they can apply the diffs even if they have made small changes of their own
+to the files.
+.Xr patch
+can apply the diffs in this case by searching in the files for the lines of
+context around the differing lines; if those lines are actually a few lines
+away from where the diff says they are,
+.Xr patch
+can adjust the line numbers accordingly and still apply the diff correctly.See Section
+.Dq Imperfect ,
+for more information on using
+.Xr patch
+to apply imperfect diffs.
+.Pp
+.Em  Context Format
+.Pp
+The context output format shows several lines of context around the lines
+that differ. It is the standard format for distributing updates to source
+code.
+.Pp
+To select this output format, use the
+.Op -C Va lines ,
+.Op --context[= Va lines] ,
+or
+.Op -c
+option. The argument
+.Va lines
+that some of these options take is the number of lines of context to show.
+If you do not specify
+.Va lines ,
+it defaults to three. For proper operation,
+.Xr patch
+typically needs at least two lines of context.
+.Pp
+.No  An Example of Context Format
+.Pp
+Here is the output of
+.Li diff -c lao tzu
+(see Section
+.Dq Sample diff Input ,
+for the complete contents of the two files). Notice that up to three lines
+that are not different are shown around each line that is different; they
+are the context lines. Also notice that the first two hunks have run together,
+because their contents overlap.
+.Pp
+.Bd -literal -offset indent
+*** lao	2002-02-21 23:30:39.942229878 -0800
+--- tzu	2002-02-21 23:30:50.442260588 -0800
+***************
+*** 1,7 ****
+- The Way that can be told of is not the eternal Way;
+- The name that can be named is not the eternal name.
+  The Nameless is the origin of Heaven and Earth;
+! The Named is the mother of all things.
+  Therefore let there always be non-being,
+    so we may see their subtlety,
+  And let there always be being,
+--- 1,6 ----
+  The Nameless is the origin of Heaven and Earth;
+! The named is the mother of all things.
+! 
+  Therefore let there always be non-being,
+    so we may see their subtlety,
+  And let there always be being,
+***************
+*** 9,11 ****
+--- 8,13 ----
+  The two are the same,
+  But after they are produced,
+    they have different names.
++ They both may be called deep and profound.
++ Deeper and more profound,
++ The door of all subtleties!
+.Ed
+.Pp
+.No  An Example of Context Format with Less Context
+.Pp
+Here is the output of
+.Li diff -C 1 lao tzu
+(see Section
+.Dq Sample diff Input ,
+for the complete contents of the two files). Notice that at most one context
+line is reported here.
+.Pp
+.Bd -literal -offset indent
+*** lao	2002-02-21 23:30:39.942229878 -0800
+--- tzu	2002-02-21 23:30:50.442260588 -0800
+***************
+*** 1,5 ****
+- The Way that can be told of is not the eternal Way;
+- The name that can be named is not the eternal name.
+  The Nameless is the origin of Heaven and Earth;
+! The Named is the mother of all things.
+  Therefore let there always be non-being,
+--- 1,4 ----
+  The Nameless is the origin of Heaven and Earth;
+! The named is the mother of all things.
+! 
+  Therefore let there always be non-being,
+***************
+*** 11 ****
+--- 10,13 ----
+    they have different names.
++ They both may be called deep and profound.
++ Deeper and more profound,
++ The door of all subtleties!
+.Ed
+.Pp
+.No  Detailed Description of Context Format
+.Pp
+The context output format starts with a two-line header, which looks like
+this:
+.Pp
+.Bd -literal -offset indent
+*** from-file from-file-modification-time
+--- to-file to-file-modification time
+.Ed
+.Pp
+The time stamp normally looks like
+.Li 2002-02-21 23:30:39.942229878 -0800
+to indicate the date, time with fractional seconds, and time zone in
+.Lk ftp://ftp.isi.edu/in-notes/rfc2822.txt .
+(The fractional seconds are omitted on hosts that do not support fractional
+time stamps.) However, a traditional time stamp like
+.Li Thu Feb 21 23:30:39 2002
+is used if the
+.Ev LC_TIME
+locale category is either
+.Li C
+or
+.Li POSIX .
+.Pp
+You can change the header's content with the
+.Op --label= Va label
+option; see Alternate Names.
+.Pp
+Next come one or more hunks of differences; each hunk shows one area where
+the files differ. Context format hunks look like this:
+.Pp
+.Bd -literal -offset indent
+***************
+*** from-file-line-numbers ****
+  from-file-line
+  from-file-line...
+--- to-file-line-numbers ----
+  to-file-line
+  to-file-line...
+.Ed
+.Pp
+If a hunk contains two or more lines, its line numbers look like
+.Li  Va start, Va end .
+Otherwise only its end line number appears. An empty hunk is considered to
+end at the line that precedes the hunk.
+.Pp
+The lines of context around the lines that differ start with two space characters.
+The lines that differ between the two files start with one of the following
+indicator characters, followed by a space character:
+.Pp
+.Bl -tag -width Ds
+.It  !
+A line that is part of a group of one or more lines that changed between the
+two files. There is a corresponding group of lines marked with
+.Li !
+in the part of this hunk for the other file.
+.Pp
+.It  +
+An \(lqinserted\(rq line in the second file that corresponds to nothing in the first
+file.
+.Pp
+.It  -
+A \(lqdeleted\(rq line in the first file that corresponds to nothing in the second
+file.
+.El
+.Pp
+If all of the changes in a hunk are insertions, the lines of
+.Va from-file
+are omitted. If all of the changes are deletions, the lines of
+.Va to-file
+are omitted.
+.Pp
+.Em  Unified Format
+.Pp
+The unified output format is a variation on the context format that is more
+compact because it omits redundant context lines. To select this output format,
+use the
+.Op -U Va lines ,
+.Op --unified[= Va lines] ,
+or
+.Op -u
+option. The argument
+.Va lines
+is the number of lines of context to show. When it is not given, it defaults
+to three.
+.Pp
+At present, only GNU
+.Xr diff
+can produce this format and only GNU
+.Xr patch
+can automatically apply diffs in this format. For proper operation,
+.Xr patch
+typically needs at least three lines of context.
+.Pp
+.No  An Example of Unified Format
+.Pp
+Here is the output of the command
+.Li diff -u lao tzu
+(see Section
+.Dq Sample diff Input ,
+for the complete contents of the two files):
+.Pp
+.Bd -literal -offset indent
+--- lao	2002-02-21 23:30:39.942229878 -0800
++++ tzu	2002-02-21 23:30:50.442260588 -0800
+@@ -1,7 +1,6 @@
+-The Way that can be told of is not the eternal Way;
+-The name that can be named is not the eternal name.
+ The Nameless is the origin of Heaven and Earth;
+-The Named is the mother of all things.
++The named is the mother of all things.
++
+ Therefore let there always be non-being,
+   so we may see their subtlety,
+ And let there always be being,
+@@ -9,3 +8,6 @@
+ The two are the same,
+ But after they are produced,
+   they have different names.
++They both may be called deep and profound.
++Deeper and more profound,
++The door of all subtleties!
+.Ed
+.Pp
+.No  Detailed Description of Unified Format
+.Pp
+The unified output format starts with a two-line header, which looks like
+this:
+.Pp
+.Bd -literal -offset indent
+--- from-file from-file-modification-time
++++ to-file to-file-modification-time
+.Ed
+.Pp
+The time stamp looks like
+.Li 2002-02-21 23:30:39.942229878 -0800
+to indicate the date, time with fractional seconds, and time zone. The fractional
+seconds are omitted on hosts that do not support fractional time stamps.
+.Pp
+You can change the header's content with the
+.Op --label= Va label
+option; seeSee Section
+.Dq Alternate Names .
+.Pp
+Next come one or more hunks of differences; each hunk shows one area where
+the files differ. Unified format hunks look like this:
+.Pp
+.Bd -literal -offset indent
+@@ from-file-line-numbers to-file-line-numbers @@
+ line-from-either-file
+ line-from-either-file...
+.Ed
+.Pp
+If a hunk contains just one line, only its start line number appears. Otherwise
+its line numbers look like
+.Li  Va start, Va count .
+An empty hunk is considered to start at the line that follows the hunk.
+.Pp
+If a hunk and its context contain two or more lines, its line numbers look
+like
+.Li  Va start, Va count .
+Otherwise only its end line number appears. An empty hunk is considered to
+end at the line that precedes the hunk.
+.Pp
+The lines common to both files begin with a space character. The lines that
+actually differ between the two files have one of the following indicator
+characters in the left print column:
+.Pp
+.Bl -tag -width Ds
+.It  +
+A line was added here to the first file.
+.Pp
+.It  -
+A line was removed here from the first file.
+.El
+.Pp
+.Em  Showing Which Sections Differences Are in
+.Pp
+Sometimes you might want to know which part of the files each change falls
+in. If the files are source code, this could mean which function was changed.
+If the files are documents, it could mean which chapter or appendix was changed.
+GNU
+.Xr diff
+can show this by displaying the nearest section heading line that precedes
+the differing lines. Which lines are \(lqsection headings\(rq is determined by a regular
+expression.
+.Pp
+.No  Showing Lines That Match Regular Expressions
+.Pp
+To show in which sections differences occur for files that are not source
+code for C or similar languages, use the
+.Op -F Va regexp
+or
+.Op --show-function-line= Va regexp
+option.
+.Xr diff
+considers lines that match the
+.Xr grep
+-style regular expression
+.Va regexp
+to be the beginning of a section of the file. Here are suggested regular expressions
+for some common languages:
+.Pp
+.Bl -tag -width Ds
+.It  ^[[:alpha:]$_]
+C, C++, Prolog
+.It  ^(
+Lisp
+.It  ^@node
+Texinfo
+.El
+.Pp
+This option does not automatically select an output format; in order to use
+it, you must select the context format (see Section
+.Dq Context Format )
+or unified format (see Section
+.Dq Unified Format ) .
+In other output formats it has no effect.
+.Pp
+The
+.Op -F
+or
+.Op --show-function-line
+option finds the nearest unchanged line that precedes each hunk of differences
+and matches the given regular expression. Then it adds that line to the end
+of the line of asterisks in the context format, or to the
+.Li @@
+line in unified format. If no matching line exists, this option leaves the
+output for that hunk unchanged. If that line is more than 40 characters long,
+it outputs only the first 40 characters. You can specify more than one regular
+expression for such lines;
+.Xr diff
+tries to match each line against each regular expression, starting with the
+last one given. This means that you can use
+.Op -p
+and
+.Op -F
+together, if you wish.
+.Pp
+.No  Showing C Function Headings
+.Pp
+To show in which functions differences occur for C and similar languages,
+you can use the
+.Op -p
+or
+.Op --show-c-function
+option. This option automatically defaults to the context output format (see Section
+.Dq Context Format ) ,
+with the default number of lines of context. You can override that number
+with
+.Op -C Va lines
+elsewhere in the command line. You can override both the format and the number
+with
+.Op -U Va lines
+elsewhere in the command line.
+.Pp
+The
+.Op -p
+or
+.Op --show-c-function
+option is equivalent to
+.Op -F '^[[:alpha:]$_]'
+if the unified format is specified, otherwise
+.Op -c -F '^[[:alpha:]$_]'
+(see Section
+.Dq Specified Headings ) .
+GNU
+.Xr diff
+provides this option for the sake of convenience.
+.Pp
+.Em  Showing Alternate File Names
+.Pp
+If you are comparing two files that have meaningless or uninformative names,
+you might want
+.Xr diff
+to show alternate names in the header of the context and unified output formats.
+To do this, use the
+.Op --label= Va label
+option. The first time you give this option, its argument replaces the name
+and date of the first file in the header; the second time, its argument replaces
+the name and date of the second file. If you give this option more than twice,
+.Xr diff
+reports an error. The
+.Op --label
+option does not affect the file names in the
+.Xr pr
+header when the
+.Op -l
+or
+.Op --paginate
+option is used (see Section
+.Dq Pagination ) .
+.Pp
+Here are the first two lines of the output from
+.Li diff -C 2 --label=original --label=modified lao tzu :
+.Pp
+.Bd -literal -offset indent
+*** original
+--- modified
+.Ed
+.Pp
+.Ss  Showing Differences Side by Side
+.Xr diff
+can produce a side by side difference listing of two files. The files are
+listed in two columns with a gutter between them. The gutter contains one
+of the following markers:
+.Pp
+.Bl -tag -width Ds
+.It  white space
+The corresponding lines are in common. That is, either the lines are identical,
+or the difference is ignored because of one of the
+.Op --ignore
+options (see Section
+.Dq White Space ) .
+.Pp
+.It  Li |
+The corresponding lines differ, and they are either both complete or both
+incomplete.
+.Pp
+.It  Li <
+The files differ and only the first file contains the line.
+.Pp
+.It  Li >
+The files differ and only the second file contains the line.
+.Pp
+.It  Li (
+Only the first file contains the line, but the difference is ignored.
+.Pp
+.It  Li )
+Only the second file contains the line, but the difference is ignored.
+.Pp
+.It  Li \e
+The corresponding lines differ, and only the first line is incomplete.
+.Pp
+.It  Li /
+The corresponding lines differ, and only the second line is incomplete.
+.El
+.Pp
+Normally, an output line is incomplete if and only if the lines that it contains
+are incomplete;See Section
+.Dq Incomplete Lines .
+However, when an output line represents two differing lines, one might be
+incomplete while the other is not. In this case, the output line is complete,
+but its the gutter is marked
+.Li \e
+if the first line is incomplete,
+.Li /
+if the second line is.
+.Pp
+Side by side format is sometimes easiest to read, but it has limitations.
+It generates much wider output than usual, and truncates lines that are too
+long to fit. Also, it relies on lining up output more heavily than usual,
+so its output looks particularly bad if you use varying width fonts, nonstandard
+tab stops, or nonprinting characters.
+.Pp
+You can use the
+.Xr sdiff
+command to interactively merge side by side differences.See Section
+.Dq Interactive Merging ,
+for more information on merging files.
+.Pp
+.Em  Controlling Side by Side Format
+.Pp
+The
+.Op -y
+or
+.Op --side-by-side
+option selects side by side format. Because side by side output lines contain
+two input lines, the output is wider than usual: normally 130 print columns,
+which can fit onto a traditional printer line. You can set the width of the
+output with the
+.Op -W Va columns
+or
+.Op --width= Va columns
+option. The output is split into two halves of equal width, separated by a
+small gutter to mark differences; the right half is aligned to a tab stop
+so that tabs line up. Input lines that are too long to fit in half of an output
+line are truncated for output.
+.Pp
+The
+.Op --left-column
+option prints only the left column of two common lines. The
+.Op --suppress-common-lines
+option suppresses common lines entirely.
+.Pp
+.Em  An Example of Side by Side Format
+.Pp
+Here is the output of the command
+.Li diff -y -W 72 lao tzu
+(see Section
+.Dq Sample diff Input ,
+for the complete contents of the two files).
+.Pp
+.Bd -literal -offset indent
+The Way that can be told of is n   <
+The name that can be named is no   <
+The Nameless is the origin of He        The Nameless is the origin of He
+The Named is the mother of all t   |    The named is the mother of all t
+                                   >
+Therefore let there always be no        Therefore let there always be no
+  so we may see their subtlety,           so we may see their subtlety,
+And let there always be being,          And let there always be being,
+  so we may see their outcome.            so we may see their outcome.
+The two are the same,                   The two are the same,
+But after they are produced,            But after they are produced,
+  they have different names.              they have different names.
+                                   >    They both may be called deep and
+                                   >    Deeper and more profound,
+                                   >    The door of all subtleties!
+.Ed
+.Pp
+.Ss  Showing Differences Without Context
+The \(lqnormal\(rq
+.Xr diff
+output format shows each hunk of differences without any surrounding context.
+Sometimes such output is the clearest way to see how lines have changed, without
+the clutter of nearby unchanged lines (although you can get similar results
+with the context or unified formats by using 0 lines of context). However,
+this format is no longer widely used for sending out patches; for that purpose,
+the context format (see Section
+.Dq Context Format )
+and the unified format (see Section
+.Dq Unified Format )
+are superior. Normal format is the default for compatibility with older versions
+of
+.Xr diff
+and the POSIX standard. Use the
+.Op --normal
+option to select this output format explicitly.
+.Pp
+.Em  An Example of Normal Format
+.Pp
+Here is the output of the command
+.Li diff lao tzu
+(see Section
+.Dq Sample diff Input ,
+for the complete contents of the two files). Notice that it shows only the
+lines that are different between the two files.
+.Pp
+.Bd -literal -offset indent
+1,2d0
+< The Way that can be told of is not the eternal Way;
+< The name that can be named is not the eternal name.
+4c2,3
+< The Named is the mother of all things.
+---
+> The named is the mother of all things.
+> 
+11a11,13
+> They both may be called deep and profound.
+> Deeper and more profound,
+> The door of all subtleties!
+.Ed
+.Pp
+.Em  Detailed Description of Normal Format
+.Pp
+The normal output format consists of one or more hunks of differences; each
+hunk shows one area where the files differ. Normal format hunks look like
+this:
+.Pp
+.Bd -literal -offset indent
+change-command
+< from-file-line
+< from-file-line...
+---
+> to-file-line
+> to-file-line...
+.Ed
+.Pp
+There are three types of change commands. Each consists of a line number or
+comma-separated range of lines in the first file, a single character indicating
+the kind of change to make, and a line number or comma-separated range of
+lines in the second file. All line numbers are the original line numbers in
+each file. The types of change commands are:
+.Pp
+.Bl -tag -width Ds
+.It  Va la Va r
+Add the lines in range
+.Va r
+of the second file after line
+.Va l
+of the first file. For example,
+.Li 8a12,15
+means append lines 12--15 of file 2 after line 8 of file 1; or, if changing
+file 2 into file 1, delete lines 12--15 of file 2.
+.Pp
+.It  Va fc Va t
+Replace the lines in range
+.Va f
+of the first file with lines in range
+.Va t
+of the second file. This is like a combined add and delete, but more compact.
+For example,
+.Li 5,7c8,10
+means change lines 5--7 of file 1 to read as lines 8--10 of file 2; or, if
+changing file 2 into file 1, change lines 8--10 of file 2 to read as lines
+5--7 of file 1.
+.Pp
+.It  Va rd Va l
+Delete the lines in range
+.Va r
+from the first file; line
+.Va l
+is where they would have appeared in the second file had they not been deleted.
+For example,
+.Li 5,7d3
+means delete lines 5--7 of file 1; or, if changing file 2 into file 1, append
+lines 5--7 of file 1 after line 3 of file 2.
+.El
+.Pp
+.Ss  Making Edit Scripts
+Several output modes produce command scripts for editing
+.Va from-file
+to produce
+.Va to-file .
+.Pp
+.Em  Xr ed Scripts
+.Pp
+.Xr diff
+can produce commands that direct the
+.Xr ed
+text editor to change the first file into the second file. Long ago, this
+was the only output mode that was suitable for editing one file into another
+automatically; today, with
+.Xr patch ,
+it is almost obsolete. Use the
+.Op -e
+or
+.Op --ed
+option to select this output format.
+.Pp
+Like the normal format (see Section
+.Dq Normal ) ,
+this output format does not show any context; unlike the normal format, it
+does not include the information necessary to apply the diff in reverse (to
+produce the first file if all you have is the second file and the diff).
+.Pp
+If the file
+.Pa d
+contains the output of
+.Li diff -e old new ,
+then the command
+.Li (cat d && echo w) | ed - old
+edits
+.Pa old
+to make it a copy of
+.Pa new .
+More generally, if
+.Pa d1 ,
+.Pa d2 ,
+\&...,
+.Pa dN
+contain the outputs of
+.Li diff -e old new1 ,
+.Li diff -e new1 new2 ,
+\&...,
+.Li diff -e newN-1 newN ,
+respectively, then the command
+.Li (cat d1 d2 ... dN && echo w) | ed - old
+edits
+.Pa old
+to make it a copy of
+.Pa newN .
+.Pp
+.No  Example Xr ed Script
+.Pp
+Here is the output of
+.Li diff -e lao tzu
+(see Section
+.Dq Sample diff Input ,
+for the complete contents of the two files):
+.Pp
+.Bd -literal -offset indent
+11a
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+\&.
+4c
+The named is the mother of all things.
+
+\&.
+1,2d
+.Ed
+.Pp
+.No  Detailed Description of Xr ed Format
+.Pp
+The
+.Xr ed
+output format consists of one or more hunks of differences. The changes closest
+to the ends of the files come first so that commands that change the number
+of lines do not affect how
+.Xr ed
+interprets line numbers in succeeding commands.
+.Xr ed
+format hunks look like this:
+.Pp
+.Bd -literal -offset indent
+change-command
+to-file-line
+to-file-line...
+\&.
+.Ed
+.Pp
+Because
+.Xr ed
+uses a single period on a line to indicate the end of input, GNU
+.Xr diff
+protects lines of changes that contain a single period on a line by writing
+two periods instead, then writing a subsequent
+.Xr ed
+command to change the two periods into one. The
+.Xr ed
+format cannot represent an incomplete line, so if the second file ends in
+a changed incomplete line,
+.Xr diff
+reports an error and then pretends that a newline was appended.
+.Pp
+There are three types of change commands. Each consists of a line number or
+comma-separated range of lines in the first file and a single character indicating
+the kind of change to make. All line numbers are the original line numbers
+in the file. The types of change commands are:
+.Pp
+.Bl -tag -width Ds
+.It  Va la
+Add text from the second file after line
+.Va l
+in the first file. For example,
+.Li 8a
+means to add the following lines after line 8 of file 1.
+.Pp
+.It  Va rc
+Replace the lines in range
+.Va r
+in the first file with the following lines. Like a combined add and delete,
+but more compact. For example,
+.Li 5,7c
+means change lines 5--7 of file 1 to read as the text file 2.
+.Pp
+.It  Va rd
+Delete the lines in range
+.Va r
+from the first file. For example,
+.Li 5,7d
+means delete lines 5--7 of file 1.
+.El
+.Pp
+.Em  Forward Xr ed Scripts
+.Pp
+.Xr diff
+can produce output that is like an
+.Xr ed
+script, but with hunks in forward (front to back) order. The format of the
+commands is also changed slightly: command characters precede the lines they
+modify, spaces separate line numbers in ranges, and no attempt is made to
+disambiguate hunk lines consisting of a single period. Like
+.Xr ed
+format, forward
+.Xr ed
+format cannot represent incomplete lines.
+.Pp
+Forward
+.Xr ed
+format is not very useful, because neither
+.Xr ed
+nor
+.Xr patch
+can apply diffs in this format. It exists mainly for compatibility with older
+versions of
+.Xr diff .
+Use the
+.Op -f
+or
+.Op --forward-ed
+option to select it.
+.Pp
+.Em  RCS Scripts
+.Pp
+The RCS output format is designed specifically for use by the Revision Control
+System, which is a set of free programs used for organizing different versions
+and systems of files. Use the
+.Op -n
+or
+.Op --rcs
+option to select this output format. It is like the forward
+.Xr ed
+format (see Section
+.Dq Forward ed ) ,
+but it can represent arbitrary changes to the contents of a file because it
+avoids the forward
+.Xr ed
+format's problems with lines consisting of a single period and with incomplete
+lines. Instead of ending text sections with a line consisting of a single
+period, each command specifies the number of lines it affects; a combination
+of the
+.Li a
+and
+.Li d
+commands are used instead of
+.Li c .
+Also, if the second file ends in a changed incomplete line, then the output
+also ends in an incomplete line.
+.Pp
+Here is the output of
+.Li diff -n lao tzu
+(see Section
+.Dq Sample diff Input ,
+for the complete contents of the two files):
+.Pp
+.Bd -literal -offset indent
+d1 2
+d4 1
+a4 2
+The named is the mother of all things.
+
+a11 3
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+.Ed
+.Pp
+.Ss  Merging Files with If-then-else
+You can use
+.Xr diff
+to merge two files of C source code. The output of
+.Xr diff
+in this format contains all the lines of both files. Lines common to both
+files are output just once; the differing parts are separated by the C preprocessor
+directives
+.Li #ifdef Va name
+or
+.Li #ifndef Va name ,
+.Li #else ,
+and
+.Li #endif .
+When compiling the output, you select which version to use by either defining
+or leaving undefined the macro
+.Va name .
+.Pp
+To merge two files, use
+.Xr diff
+with the
+.Op -D Va name
+or
+.Op --ifdef= Va name
+option. The argument
+.Va name
+is the C preprocessor identifier to use in the
+.Li #ifdef
+and
+.Li #ifndef
+directives.
+.Pp
+For example, if you change an instance of
+.Li wait (&s)
+to
+.Li waitpid (-1, &s, 0)
+and then merge the old and new files with the
+.Op --ifdef=HAVE_WAITPID
+option, then the affected part of your code might look like this:
+.Pp
+.Bd -literal -offset indent
+    do {
+#ifndef HAVE_WAITPID
+        if ((w = wait (&s)) < 0  &&  errno != EINTR)
+#else /* HAVE_WAITPID */
+        if ((w = waitpid (-1, &s, 0)) < 0  &&  errno != EINTR)
+#endif /* HAVE_WAITPID */
+            return w;
+    } while (w != child);
+.Ed
+.Pp
+You can specify formats for languages other than C by using line group formats
+and line formats, as described in the next sections.
+.Pp
+.Em  Line Group Formats
+.Pp
+Line group formats let you specify formats suitable for many applications
+that allow if-then-else input, including programming languages and text formatting
+languages. A line group format specifies the output format for a contiguous
+group of similar lines.
+.Pp
+For example, the following command compares the TeX files
+.Pa old
+and
+.Pa new ,
+and outputs a merged file in which old regions are surrounded by
+.Li \ebegin{em}
+-
+.Li \eend{em}
+lines, and new regions are surrounded by
+.Li \ebegin{bf}
+-
+.Li \eend{bf}
+lines.
+.Pp
+.Bd -literal -offset indent
+diff \e
+   --old-group-format='\ebegin{em}
+%<\eend{em}
+\&' \e
+   --new-group-format='\ebegin{bf}
+%>\eend{bf}
+\&' \e
+   old new
+.Ed
+.Pp
+The following command is equivalent to the above example, but it is a little
+more verbose, because it spells out the default line group formats.
+.Pp
+.Bd -literal -offset indent
+diff \e
+   --old-group-format='\ebegin{em}
+%<\eend{em}
+\&' \e
+   --new-group-format='\ebegin{bf}
+%>\eend{bf}
+\&' \e
+   --unchanged-group-format='%=' \e
+   --changed-group-format='\ebegin{em}
+%<\eend{em}
+\ebegin{bf}
+%>\eend{bf}
+\&' \e
+   old new
+.Ed
+.Pp
+Here is a more advanced example, which outputs a diff listing with headers
+containing line numbers in a \(lqplain English\(rq style.
+.Pp
+.Bd -literal -offset indent
+diff \e
+   --unchanged-group-format=\(rq \e
+   --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
+%<' \e
+   --new-group-format='-------- %dN line%(N=1?:s) added after %de:
+%>' \e
+   --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
+%<-------- to:
+%>' \e
+   old new
+.Ed
+.Pp
+To specify a line group format, use
+.Xr diff
+with one of the options listed below. You can specify up to four line group
+formats, one for each kind of line group. You should quote
+.Va format ,
+because it typically contains shell metacharacters.
+.Pp
+.Bl -tag -width Ds
+.It  --old-group-format= Va format
+These line groups are hunks containing only lines from the first file. The
+default old group format is the same as the changed group format if it is
+specified; otherwise it is a format that outputs the line group as-is.
+.Pp
+.It  --new-group-format= Va format
+These line groups are hunks containing only lines from the second file. The
+default new group format is same as the changed group format if it is specified;
+otherwise it is a format that outputs the line group as-is.
+.Pp
+.It  --changed-group-format= Va format
+These line groups are hunks containing lines from both files. The default
+changed group format is the concatenation of the old and new group formats.
+.Pp
+.It  --unchanged-group-format= Va format
+These line groups contain lines common to both files. The default unchanged
+group format is a format that outputs the line group as-is.
+.El
+.Pp
+In a line group format, ordinary characters represent themselves; conversion
+specifications start with
+.Li %
+and have one of the following forms.
+.Pp
+.Bl -tag -width Ds
+.It  %<
+stands for the lines from the first file, including the trailing newline.
+Each line is formatted according to the old line format (see Section
+.Dq Line Formats ) .
+.Pp
+.It  %>
+stands for the lines from the second file, including the trailing newline.
+Each line is formatted according to the new line format.
+.Pp
+.It  %=
+stands for the lines common to both files, including the trailing newline.
+Each line is formatted according to the unchanged line format.
+.Pp
+.It  %%
+stands for
+.Li % .
+.Pp
+.It  %c' Va C'
+where
+.Va C
+is a single character, stands for
+.Va C .
+.Va C
+may not be a backslash or an apostrophe. For example,
+.Li %c':'
+stands for a colon, even inside the then-part of an if-then-else format, which
+a colon would normally terminate.
+.Pp
+.It  %c'\e Va O'
+where
+.Va O
+is a string of 1, 2, or 3 octal digits, stands for the character with octal
+code
+.Va O .
+For example,
+.Li %c'\e0'
+stands for a null character.
+.Pp
+.It  Va F Va n
+where
+.Va F
+is a
+.Li printf
+conversion specification and
+.Va n
+is one of the following letters, stands for
+.Va n
+\&'s value formatted with
+.Va F .
+.Pp
+.Bl -tag -width Ds
+.It  e
+The line number of the line just before the group in the old file.
+.Pp
+.It  f
+The line number of the first line in the group in the old file; equals
+.Va e
++ 1.
+.Pp
+.It  l
+The line number of the last line in the group in the old file.
+.Pp
+.It  m
+The line number of the line just after the group in the old file; equals
+.Va l
++ 1.
+.Pp
+.It  n
+The number of lines in the group in the old file; equals
+.Va l
+-
+.Va f
++ 1.
+.Pp
+.It  E, F, L, M, N
+Likewise, for lines in the new file.
+.Pp
+.El
+The
+.Li printf
+conversion specification can be
+.Li %d ,
+.Li %o ,
+.Li %x ,
+or
+.Li %X ,
+specifying decimal, octal, lower case hexadecimal, or upper case hexadecimal
+output respectively. After the
+.Li %
+the following options can appear in sequence: a series of zero or more flags;
+an integer specifying the minimum field width; and a period followed by an
+optional integer specifying the minimum number of digits. The flags are
+.Li -
+for left-justification,
+.Li '
+for separating the digit into groups as specified by the
+.Ev LC_NUMERIC
+locale category, and
+.Li 0
+for padding with zeros instead of spaces. For example,
+.Li %5dN
+prints the number of new lines in the group in a field of width 5 characters,
+using the
+.Li printf
+format
+.Li "%5d" .
+.Pp
+.It  ( Va A= Va B? Va T: Va E)
+If
+.Va A
+equals
+.Va B
+then
+.Va T
+else
+.Va E .
+.Va A
+and
+.Va B
+are each either a decimal constant or a single letter interpreted as above.
+This format spec is equivalent to
+.Va T
+if
+.Va A
+\&'s value equals
+.Va B
+\&'s; otherwise it is equivalent to
+.Va E .
+.Pp
+For example,
+.Li %(N=0?no:%dN) line%(N=1?:s)
+is equivalent to
+.Li no lines
+if
+.Va N
+(the number of lines in the group in the new file) is 0, to
+.Li 1 line
+if
+.Va N
+is 1, and to
+.Li %dN lines
+otherwise.
+.El
+.Pp
+.Em  Line Formats
+.Pp
+Line formats control how each line taken from an input file is output as part
+of a line group in if-then-else format.
+.Pp
+For example, the following command outputs text with a one-character change
+indicator to the left of the text. The first character of output is
+.Li -
+for deleted lines,
+.Li |
+for added lines, and a space for unchanged lines. The formats contain newline
+characters where newlines are desired on output.
+.Pp
+.Bd -literal -offset indent
+diff \e
+   --old-line-format='-%l
+\&' \e
+   --new-line-format='|%l
+\&' \e
+   --unchanged-line-format=' %l
+\&' \e
+   old new
+.Ed
+.Pp
+To specify a line format, use one of the following options. You should quote
+.Va format ,
+since it often contains shell metacharacters.
+.Pp
+.Bl -tag -width Ds
+.It  --old-line-format= Va format
+formats lines just from the first file.
+.Pp
+.It  --new-line-format= Va format
+formats lines just from the second file.
+.Pp
+.It  --unchanged-line-format= Va format
+formats lines common to both files.
+.Pp
+.It  --line-format= Va format
+formats all lines; in effect, it sets all three above options simultaneously.
+.El
+.Pp
+In a line format, ordinary characters represent themselves; conversion specifications
+start with
+.Li %
+and have one of the following forms.
+.Pp
+.Bl -tag -width Ds
+.It  %l
+stands for the contents of the line, not counting its trailing newline (if
+any). This format ignores whether the line is incomplete;See Section
+.Dq Incomplete Lines .
+.Pp
+.It  %L
+stands for the contents of the line, including its trailing newline (if any).
+If a line is incomplete, this format preserves its incompleteness.
+.Pp
+.It  %%
+stands for
+.Li % .
+.Pp
+.It  %c' Va C'
+where
+.Va C
+is a single character, stands for
+.Va C .
+.Va C
+may not be a backslash or an apostrophe. For example,
+.Li %c':'
+stands for a colon.
+.Pp
+.It  %c'\e Va O'
+where
+.Va O
+is a string of 1, 2, or 3 octal digits, stands for the character with octal
+code
+.Va O .
+For example,
+.Li %c'\e0'
+stands for a null character.
+.Pp
+.It  Va Fn
+where
+.Va F
+is a
+.Li printf
+conversion specification, stands for the line number formatted with
+.Va F .
+For example,
+.Li %.5dn
+prints the line number using the
+.Li printf
+format
+.Li "%.5d" .
+See Section.Dq Line Group Formats ,
+for more about printf conversion specifications.
+.Pp
+.El
+The default line format is
+.Li %l
+followed by a newline character.
+.Pp
+If the input contains tab characters and it is important that they line up
+on output, you should ensure that
+.Li %l
+or
+.Li %L
+in a line format is just after a tab stop (e.g. by preceding
+.Li %l
+or
+.Li %L
+with a tab character), or you should use the
+.Op -t
+or
+.Op --expand-tabs
+option.
+.Pp
+Taken together, the line and line group formats let you specify many different
+formats. For example, the following command uses a format similar to normal
+.Xr diff
+format. You can tailor this command to get fine control over
+.Xr diff
+output.
+.Pp
+.Bd -literal -offset indent
+diff \e
+   --old-line-format='< %l
+\&' \e
+   --new-line-format='> %l
+\&' \e
+   --old-group-format='%df%(f=l?:,%dl)d%dE
+%<' \e
+   --new-group-format='%dea%dF%(F=L?:,%dL)
+%>' \e
+   --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
+%<---
+%>' \e
+   --unchanged-group-format=\(rq \e
+   old new
+.Ed
+.Pp
+.Em  An Example of If-then-else Format
+.Pp
+Here is the output of
+.Li diff -DTWO lao tzu
+(see Section
+.Dq Sample diff Input ,
+for the complete contents of the two files):
+.Pp
+.Bd -literal -offset indent
+#ifndef TWO
+The Way that can be told of is not the eternal Way;
+The name that can be named is not the eternal name.
+#endif /* ! TWO */
+The Nameless is the origin of Heaven and Earth;
+#ifndef TWO
+The Named is the mother of all things.
+#else /* TWO */
+The named is the mother of all things.
+
+#endif /* TWO */
+Therefore let there always be non-being,
+  so we may see their subtlety,
+And let there always be being,
+  so we may see their outcome.
+The two are the same,
+But after they are produced,
+  they have different names.
+#ifdef TWO
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+#endif /* TWO */
+.Ed
+.Pp
+.Em  Detailed Description of If-then-else Format
+.Pp
+For lines common to both files,
+.Xr diff
+uses the unchanged line group format. For each hunk of differences in the
+merged output format, if the hunk contains only lines from the first file,
+.Xr diff
+uses the old line group format; if the hunk contains only lines from the second
+file,
+.Xr diff
+uses the new group format; otherwise,
+.Xr diff
+uses the changed group format.
+.Pp
+The old, new, and unchanged line formats specify the output format of lines
+from the first file, lines from the second file, and lines common to both
+files, respectively.
+.Pp
+The option
+.Op --ifdef= Va name
+is equivalent to the following sequence of options using shell syntax:
+.Pp
+.Bd -literal -offset indent
+--old-group-format='#ifndef name
+%<#endif /* ! name */
+\&' \e
+--new-group-format='#ifdef name
+%>#endif /* name */
+\&' \e
+--unchanged-group-format='%=' \e
+--changed-group-format='#ifndef name
+%<#else /* name */
+%>#endif /* name */
+\&'
+.Ed
+.Pp
+You should carefully check the
+.Xr diff
+output for proper nesting. For example, when using the
+.Op -D Va name
+or
+.Op --ifdef= Va name
+option, you should check that if the differing lines contain any of the C
+preprocessor directives
+.Li #ifdef ,
+.Li #ifndef ,
+.Li #else ,
+.Li #elif ,
+or
+.Li #endif ,
+they are nested properly and match. If they don't, you must make corrections
+manually. It is a good idea to carefully check the resulting code anyway to
+make sure that it really does what you want it to; depending on how the input
+files were produced, the output might contain duplicate or otherwise incorrect
+code.
+.Pp
+The
+.Xr patch
+.Op -D Va name
+option behaves like the
+.Xr diff
+.Op -D Va name
+option, except it operates on a file and a diff to produce a merged file;See Section
+.Dq patch Options .
+.Pp
+.Sh  Incomplete Lines
+When an input file ends in a non-newline character, its last line is called
+an
+.Em incomplete line
+because its last character is not a newline. All other lines are called
+.Em full lines
+and end in a newline character. Incomplete lines do not match full lines unless
+differences in white space are ignored (see Section
+.Dq White Space ) .
+.Pp
+An incomplete line is normally distinguished on output from a full line by
+a following line that starts with
+.Li \e .
+However, the RCS format (see Section
+.Dq RCS )
+outputs the incomplete line as-is, without any trailing newline or following
+line. The side by side format normally represents incomplete lines as-is,
+but in some cases uses a
+.Li \e
+or
+.Li /
+gutter marker;See Section
+.Dq Side by Side .
+The if-then-else line format preserves a line's incompleteness with
+.Li %L ,
+and discards the newline with
+.Li %l
+;See Section
+.Dq Line Formats .
+Finally, with the
+.Xr ed
+and forward
+.Xr ed
+output formats (see Section
+.Dq Output Formats )
+.Xr diff
+cannot represent an incomplete line, so it pretends there was a newline and
+reports an error.
+.Pp
+For example, suppose
+.Pa F
+and
+.Pa G
+are one-byte files that contain just
+.Li f
+and
+.Li g ,
+respectively. Then
+.Li diff F G
+outputs
+.Pp
+.Bd -literal -offset indent
+1c1
+< f
+\e No newline at end of file
+---
+> g
+\e No newline at end of file
+.Ed
+.Pp
+(The exact message may differ in non-English locales.)
+.Li diff -n F G
+outputs the following without a trailing newline:
+.Pp
+.Bd -literal -offset indent
+d1 1
+a1 1
+g
+.Ed
+.Pp
+.Li diff -e F G
+reports two errors and outputs the following:
+.Pp
+.Bd -literal -offset indent
+1c
+g
+\&.
+.Ed
+.Pp
+.Sh  Comparing Directories
+You can use
+.Xr diff
+to compare some or all of the files in two directory trees. When both file
+name arguments to
+.Xr diff
+are directories, it compares each file that is contained in both directories,
+examining file names in alphabetical order as specified by the
+.Ev LC_COLLATE
+locale category. Normally
+.Xr diff
+is silent about pairs of files that contain no differences, but if you use
+the
+.Op -s
+or
+.Op --report-identical-files
+option, it reports pairs of identical files. Normally
+.Xr diff
+reports subdirectories common to both directories without comparing subdirectories'
+files, but if you use the
+.Op -r
+or
+.Op --recursive
+option, it compares every corresponding pair of files in the directory trees,
+as many levels deep as they go.
+.Pp
+For file names that are in only one of the directories,
+.Xr diff
+normally does not show the contents of the file that exists; it reports only
+that the file exists in that directory and not in the other. You can make
+.Xr diff
+act as though the file existed but was empty in the other directory, so that
+it outputs the entire contents of the file that actually exists. (It is output
+as either an insertion or a deletion, depending on whether it is in the first
+or the second directory given.) To do this, use the
+.Op -N
+or
+.Op --new-file
+option.
+.Pp
+If the older directory contains one or more large files that are not in the
+newer directory, you can make the patch smaller by using the
+.Op --unidirectional-new-file
+option instead of
+.Op -N .
+This option is like
+.Op -N
+except that it only inserts the contents of files that appear in the second
+directory but not the first (that is, files that were added). At the top of
+the patch, write instructions for the user applying the patch to remove the
+files that were deleted before applying the patch.See Section
+.Dq Making Patches ,
+for more discussion of making patches for distribution.
+.Pp
+To ignore some files while comparing directories, use the
+.Op -x Va pattern
+or
+.Op --exclude= Va pattern
+option. This option ignores any files or subdirectories whose base names match
+the shell pattern
+.Va pattern .
+Unlike in the shell, a period at the start of the base of a file name matches
+a wildcard at the start of a pattern. You should enclose
+.Va pattern
+in quotes so that the shell does not expand it. For example, the option
+.Op -x '*.[ao]'
+ignores any file whose name ends with
+.Li .a
+or
+.Li .o .
+.Pp
+This option accumulates if you specify it more than once. For example, using
+the options
+.Op -x 'RCS' -x '*,v'
+ignores any file or subdirectory whose base name is
+.Li RCS
+or ends with
+.Li ,v .
+.Pp
+If you need to give this option many times, you can instead put the patterns
+in a file, one pattern per line, and use the
+.Op -X Va file
+or
+.Op --exclude-from= Va file
+option. Trailing white space and empty lines are ignored in the pattern file.
+.Pp
+If you have been comparing two directories and stopped partway through, later
+you might want to continue where you left off. You can do this by using the
+.Op -S Va file
+or
+.Op --starting-file= Va file
+option. This compares only the file
+.Va file
+and all alphabetically later files in the topmost directory level.
+.Pp
+If two directories differ only in that file names are lower case in one directory
+and upper case in the upper,
+.Xr diff
+normally reports many differences because it compares file names in a case
+sensitive way. With the
+.Op --ignore-file-name-case
+option,
+.Xr diff
+ignores case differences in file names, so that for example the contents of
+the file
+.Pa Tao
+in one directory are compared to the contents of the file
+.Pa TAO
+in the other. The
+.Op --no-ignore-file-name-case
+option cancels the effect of the
+.Op --ignore-file-name-case
+option, reverting to the default behavior.
+.Pp
+If an
+.Op -x Va pattern
+or
+.Op --exclude= Va pattern
+option, or an
+.Op -X Va file
+or
+.Op --exclude-from= Va file
+option, is specified while the
+.Op --ignore-file-name-case
+option is in effect, case is ignored when excluding file names matching the
+specified patterns.
+.Pp
+.Sh  Making Xr diff Output Prettier
+.Xr diff
+provides several ways to adjust the appearance of its output. These adjustments
+can be applied to any output format.
+.Pp
+.Ss  Preserving Tab Stop Alignment
+The lines of text in some of the
+.Xr diff
+output formats are preceded by one or two characters that indicate whether
+the text is inserted, deleted, or changed. The addition of those characters
+can cause tabs to move to the next tab stop, throwing off the alignment of
+columns in the line. GNU
+.Xr diff
+provides two ways to make tab-aligned columns line up correctly.
+.Pp
+The first way is to have
+.Xr diff
+convert all tabs into the correct number of spaces before outputting them;
+select this method with the
+.Op -t
+or
+.Op --expand-tabs
+option. To use this form of output with
+.Xr patch ,
+you must give
+.Xr patch
+the
+.Op -l
+or
+.Op --ignore-white-space
+option (see Section
+.Dq Changed White Space ,
+for more information).
+.Xr diff
+normally assumes that tab stops are set every 8 print columns, but this can
+be altered by the
+.Op --tabsize= Va columns
+option.
+.Pp
+The other method for making tabs line up correctly is to add a tab character
+instead of a space after the indicator character at the beginning of the line.
+This ensures that all following tab characters are in the same position relative
+to tab stops that they were in the original files, so that the output is aligned
+correctly. Its disadvantage is that it can make long lines too long to fit
+on one line of the screen or the paper. It also does not work with the unified
+output format, which does not have a space character after the change type
+indicator character. Select this method with the
+.Op -T
+or
+.Op --initial-tab
+option.
+.Pp
+.Ss  Paginating Xr diff Output
+It can be convenient to have long output page-numbered and time-stamped. The
+.Op -l
+or
+.Op --paginate
+option does this by sending the
+.Xr diff
+output through the
+.Xr pr
+program. Here is what the page header might look like for
+.Li diff -lc lao tzu :
+.Pp
+.Bd -literal -offset indent
+2002-02-22 14:20                 diff -lc lao tzu                 Page 1
+.Ed
+.Pp
+.Sh  Xr diff Performance Tradeoffs
+GNU
+.Xr diff
+runs quite efficiently; however, in some circumstances you can cause it to
+run faster or produce a more compact set of changes.
+.Pp
+One way to improve
+.Xr diff
+performance is to use hard or symbolic links to files instead of copies. This
+improves performance because
+.Xr diff
+normally does not need to read two hard or symbolic links to the same file,
+since their contents must be identical. For example, suppose you copy a large
+directory hierarchy, make a few changes to the copy, and then often use
+.Li diff -r
+to compare the original to the copy. If the original files are read-only,
+you can greatly improve performance by creating the copy using hard or symbolic
+links (e.g., with GNU
+.Li cp -lR
+or
+.Li cp -sR ) .
+Before editing a file in the copy for the first time, you should break the
+link and replace it with a regular copy.
+.Pp
+You can also affect the performance of GNU
+.Xr diff
+by giving it options that change the way it compares files. Performance has
+more than one dimension. These options improve one aspect of performance at
+the cost of another, or they improve performance in some cases while hurting
+it in others.
+.Pp
+The way that GNU
+.Xr diff
+determines which lines have changed always comes up with a near-minimal set
+of differences. Usually it is good enough for practical purposes. If the
+.Xr diff
+output is large, you might want
+.Xr diff
+to use a modified algorithm that sometimes produces a smaller set of differences.
+The
+.Op -d
+or
+.Op --minimal
+option does this; however, it can also cause
+.Xr diff
+to run more slowly than usual, so it is not the default behavior.
+.Pp
+When the files you are comparing are large and have small groups of changes
+scattered throughout them, you can use the
+.Op --speed-large-files
+option to make a different modification to the algorithm that
+.Xr diff
+uses. If the input files have a constant small density of changes, this option
+speeds up the comparisons without changing the output. If not,
+.Xr diff
+might produce a larger set of differences; however, the output will still
+be correct.
+.Pp
+Normally
+.Xr diff
+discards the prefix and suffix that is common to both files before it attempts
+to find a minimal set of differences. This makes
+.Xr diff
+run faster, but occasionally it may produce non-minimal output. The
+.Op --horizon-lines= Va lines
+option prevents
+.Xr diff
+from discarding the last
+.Va lines
+lines of the prefix and the first
+.Va lines
+lines of the suffix. This gives
+.Xr diff
+further opportunities to find a minimal output.
+.Pp
+Suppose a run of changed lines includes a sequence of lines at one end and
+there is an identical sequence of lines just outside the other end. The
+.Xr diff
+command is free to choose which identical sequence is included in the hunk.
+In this case,
+.Xr diff
+normally shifts the hunk's boundaries when this merges adjacent hunks, or
+shifts a hunk's lines towards the end of the file. Merging hunks can make
+the output look nicer in some cases.
+.Pp
+.Sh  Comparing Three Files
+Use the program
+.Xr diff3
+to compare three files and show any differences among them. (
+.Xr diff3
+can also merge files; see diff3 Merging).
+.Pp
+The \(lqnormal\(rq
+.Xr diff3
+output format shows each hunk of differences without surrounding context.
+Hunks are labeled depending on whether they are two-way or three-way, and
+lines are annotated by their location in the input files.
+.Pp
+See Section.Dq Invoking diff3 ,
+for more information on how to run
+.Xr diff3 .
+.Pp
+.Ss  A Third Sample Input File
+Here is a third sample file that will be used in examples to illustrate the
+output of
+.Xr diff3
+and how various options can change it. The first two files are the same that
+we used for
+.Xr diff
+(see Section
+.Dq Sample diff Input ) .
+This is the third sample file, called
+.Pa tao :
+.Pp
+.Bd -literal -offset indent
+The Way that can be told of is not the eternal Way;
+The name that can be named is not the eternal name.
+The Nameless is the origin of Heaven and Earth;
+The named is the mother of all things.
+
+Therefore let there always be non-being,
+  so we may see their subtlety,
+And let there always be being,
+  so we may see their result.
+The two are the same,
+But after they are produced,
+  they have different names.
+
+  -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+.Ed
+.Pp
+.Ss  An Example of Xr diff3 Normal Format
+Here is the output of the command
+.Li diff3 lao tzu tao
+(see Section
+.Dq Sample diff3 Input ,
+for the complete contents of the files). Notice that it shows only the lines
+that are different among the three files.
+.Pp
+.Bd -literal -offset indent
+====2
+1:1,2c
+3:1,2c
+  The Way that can be told of is not the eternal Way;
+  The name that can be named is not the eternal name.
+2:0a
+====1
+1:4c
+  The Named is the mother of all things.
+2:2,3c
+3:4,5c
+  The named is the mother of all things.
+  
+====3
+1:8c
+2:7c
+    so we may see their outcome.
+3:9c
+    so we may see their result.
+====
+1:11a
+2:11,13c
+  They both may be called deep and profound.
+  Deeper and more profound,
+  The door of all subtleties!
+3:13,14c
+  
+    -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+.Ed
+.Pp
+.Ss  Detailed Description of Xr diff3 Normal Format
+Each hunk begins with a line marked
+.Li ==== .
+Three-way hunks have plain
+.Li ====
+lines, and two-way hunks have
+.Li 1 ,
+.Li 2 ,
+or
+.Li 3
+appended to specify which of the three input files differ in that hunk. The
+hunks contain copies of two or three sets of input lines each preceded by
+one or two commands identifying where the lines came from.
+.Pp
+Normally, two spaces precede each copy of an input line to distinguish it
+from the commands. But with the
+.Op -T
+or
+.Op --initial-tab
+option,
+.Xr diff3
+uses a tab instead of two spaces; this lines up tabs correctly.See Section
+.Dq Tabs ,
+for more information.
+.Pp
+Commands take the following forms:
+.Pp
+.Bl -tag -width Ds
+.It  Va file: Va la
+This hunk appears after line
+.Va l
+of file
+.Va file ,
+and contains no lines in that file. To edit this file to yield the other files,
+one must append hunk lines taken from the other files. For example,
+.Li 1:11a
+means that the hunk follows line 11 in the first file and contains no lines
+from that file.
+.Pp
+.It  Va file: Va rc
+This hunk contains the lines in the range
+.Va r
+of file
+.Va file .
+The range
+.Va r
+is a comma-separated pair of line numbers, or just one number if the range
+is a singleton. To edit this file to yield the other files, one must change
+the specified lines to be the lines taken from the other files. For example,
+.Li 2:11,13c
+means that the hunk contains lines 11 through 13 from the second file.
+.El
+.Pp
+If the last line in a set of input lines is incomplete (see Section
+.Dq Incomplete Lines ) ,
+it is distinguished on output from a full line by a following line that starts
+with
+.Li \e .
+.Pp
+.Ss  Xr diff3 Hunks
+Groups of lines that differ in two or three of the input files are called
+.Em diff3 hunks ,
+by analogy with
+.Xr diff
+hunks (see Section
+.Dq Hunks ) .
+If all three input files differ in a
+.Xr diff3
+hunk, the hunk is called a
+.Em three-way hunk
+; if just two input files differ, it is a
+.Em two-way hunk .
+.Pp
+As with
+.Xr diff ,
+several solutions are possible. When comparing the files
+.Li A ,
+.Li B ,
+and
+.Li C ,
+.Xr diff3
+normally finds
+.Xr diff3
+hunks by merging the two-way hunks output by the two commands
+.Li diff A B
+and
+.Li diff A C .
+This does not necessarily minimize the size of the output, but exceptions
+should be rare.
+.Pp
+For example, suppose
+.Pa F
+contains the three lines
+.Li a ,
+.Li b ,
+.Li f ,
+.Pa G
+contains the lines
+.Li g ,
+.Li b ,
+.Li g ,
+and
+.Pa H
+contains the lines
+.Li a ,
+.Li b ,
+.Li h .
+.Li diff3 F G H
+might output the following:
+.Pp
+.Bd -literal -offset indent
+====2
+1:1c
+3:1c
+  a
+2:1c
+  g
+====
+1:3c
+  f
+2:3c
+  g
+3:3c
+  h
+.Ed
+.Pp
+because it found a two-way hunk containing
+.Li a
+in the first and third files and
+.Li g
+in the second file, then the single line
+.Li b
+common to all three files, then a three-way hunk containing the last line
+of each file.
+.Pp
+.Sh  Merging From a Common Ancestor
+When two people have made changes to copies of the same file,
+.Xr diff3
+can produce a merged output that contains both sets of changes together with
+warnings about conflicts.
+.Pp
+One might imagine programs with names like
+.Xr diff4
+and
+.Xr diff5
+to compare more than three files simultaneously, but in practice the need
+rarely arises. You can use
+.Xr diff3
+to merge three or more sets of changes to a file by merging two change sets
+at a time.
+.Pp
+.Xr diff3
+can incorporate changes from two modified versions into a common preceding
+version. This lets you merge the sets of changes represented by the two newer
+files. Specify the common ancestor version as the second argument and the
+two newer versions as the first and third arguments, like this:
+.Pp
+.Bd -literal -offset indent
+diff3 mine older yours
+.Ed
+.Pp
+You can remember the order of the arguments by noting that they are in alphabetical
+order.
+.Pp
+You can think of this as subtracting
+.Va older
+from
+.Va yours
+and adding the result to
+.Va mine ,
+or as merging into
+.Va mine
+the changes that would turn
+.Va older
+into
+.Va yours .
+This merging is well-defined as long as
+.Va mine
+and
+.Va older
+match in the neighborhood of each such change. This fails to be true when
+all three input files differ or when only
+.Va older
+differs; we call this a
+.Em conflict .
+When all three input files differ, we call the conflict an
+.Em overlap .
+.Pp
+.Xr diff3
+gives you several ways to handle overlaps and conflicts. You can omit overlaps
+or conflicts, or select only overlaps, or mark conflicts with special
+.Li <<<<<<<
+and
+.Li >>>>>>>
+lines.
+.Pp
+.Xr diff3
+can output the merge results as an
+.Xr ed
+script that that can be applied to the first file to yield the merged output.
+However, it is usually better to have
+.Xr diff3
+generate the merged output directly; this bypasses some problems with
+.Xr ed .
+.Pp
+.Ss  Selecting Which Changes to Incorporate
+You can select all unmerged changes from
+.Va older
+to
+.Va yours
+for merging into
+.Va mine
+with the
+.Op -e
+or
+.Op --ed
+option. You can select only the nonoverlapping unmerged changes with
+.Op -3
+or
+.Op --easy-only ,
+and you can select only the overlapping changes with
+.Op -x
+or
+.Op --overlap-only .
+.Pp
+The
+.Op -e ,
+.Op -3
+and
+.Op -x
+options select only
+.Em unmerged changes ,
+i.e. changes where
+.Va mine
+and
+.Va yours
+differ; they ignore changes from
+.Va older
+to
+.Va yours
+where
+.Va mine
+and
+.Va yours
+are identical, because they assume that such changes have already been merged.
+If this assumption is not a safe one, you can use the
+.Op -A
+or
+.Op --show-all
+option (see Section
+.Dq Marking Conflicts ) .
+.Pp
+Here is the output of the command
+.Xr diff3
+with each of these three options (see Section
+.Dq Sample diff3 Input ,
+for the complete contents of the files). Notice that
+.Op -e
+outputs the union of the disjoint sets of changes output by
+.Op -3
+and
+.Op -x .
+.Pp
+Output of
+.Li diff3 -e lao tzu tao :
+.Bd -literal -offset indent
+11a
+
+  -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+\&.
+8c
+  so we may see their result.
+\&.
+.Ed
+.Pp
+Output of
+.Li diff3 -3 lao tzu tao :
+.Bd -literal -offset indent
+8c
+  so we may see their result.
+\&.
+.Ed
+.Pp
+Output of
+.Li diff3 -x lao tzu tao :
+.Bd -literal -offset indent
+11a
+
+  -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+\&.
+.Ed
+.Pp
+.Ss  Marking Conflicts
+.Xr diff3
+can mark conflicts in the merged output by bracketing them with special marker
+lines. A conflict that comes from two files
+.Va A
+and
+.Va B
+is marked as follows:
+.Pp
+.Bd -literal -offset indent
+<<<<<<< A
+lines from A
+=======
+lines from B
+>>>>>>> B
+.Ed
+.Pp
+A conflict that comes from three files
+.Va A ,
+.Va B
+and
+.Va C
+is marked as follows:
+.Pp
+.Bd -literal -offset indent
+<<<<<<< A
+lines from A
+||||||| B
+lines from B
+=======
+lines from C
+>>>>>>> C
+.Ed
+.Pp
+The
+.Op -A
+or
+.Op --show-all
+option acts like the
+.Op -e
+option, except that it brackets conflicts, and it outputs all changes from
+.Va older
+to
+.Va yours ,
+not just the unmerged changes. Thus, given the sample input files (see Section
+.Dq Sample diff3 Input ) ,
+.Li diff3 -A lao tzu tao
+puts brackets around the conflict where only
+.Pa tzu
+differs:
+.Pp
+.Bd -literal -offset indent
+<<<<<<< tzu
+=======
+The Way that can be told of is not the eternal Way;
+The name that can be named is not the eternal name.
+>>>>>>> tao
+.Ed
+.Pp
+And it outputs the three-way conflict as follows:
+.Pp
+.Bd -literal -offset indent
+<<<<<<< lao
+||||||| tzu
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+=======
+
+  -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+>>>>>>> tao
+.Ed
+.Pp
+The
+.Op -E
+or
+.Op --show-overlap
+option outputs less information than the
+.Op -A
+or
+.Op --show-all
+option, because it outputs only unmerged changes, and it never outputs the
+contents of the second file. Thus the
+.Op -E
+option acts like the
+.Op -e
+option, except that it brackets the first and third files from three-way overlapping
+changes. Similarly,
+.Op -X
+acts like
+.Op -x ,
+except it brackets all its (necessarily overlapping) changes. For example,
+for the three-way overlapping change above, the
+.Op -E
+and
+.Op -X
+options output the following:
+.Pp
+.Bd -literal -offset indent
+<<<<<<< lao
+=======
+
+  -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+>>>>>>> tao
+.Ed
+.Pp
+If you are comparing files that have meaningless or uninformative names, you
+can use the
+.Op --label= Va label
+option to show alternate names in the
+.Li <<<<<<< ,
+.Li |||||||
+and
+.Li >>>>>>>
+brackets. This option can be given up to three times, once for each input
+file. Thus
+.Li diff3 -A --label X --label Y --label Z A B C
+acts like
+.Li diff3 -A A B C ,
+except that the output looks like it came from files named
+.Li X ,
+.Li Y
+and
+.Li Z
+rather than from files named
+.Li A ,
+.Li B
+and
+.Li C .
+.Pp
+.Ss  Generating the Merged Output Directly
+With the
+.Op -m
+or
+.Op --merge
+option,
+.Xr diff3
+outputs the merged file directly. This is more efficient than using
+.Xr ed
+to generate it, and works even with non-text files that
+.Xr ed
+would reject. If you specify
+.Op -m
+without an
+.Xr ed
+script option,
+.Op -A
+is assumed.
+.Pp
+For example, the command
+.Li diff3 -m lao tzu tao
+(see Section
+.Dq Sample diff3 Input
+for a copy of the input files) would output the following:
+.Pp
+.Bd -literal -offset indent
+<<<<<<< tzu
+=======
+The Way that can be told of is not the eternal Way;
+The name that can be named is not the eternal name.
+>>>>>>> tao
+The Nameless is the origin of Heaven and Earth;
+The Named is the mother of all things.
+Therefore let there always be non-being,
+  so we may see their subtlety,
+And let there always be being,
+  so we may see their result.
+The two are the same,
+But after they are produced,
+  they have different names.
+<<<<<<< lao
+||||||| tzu
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+=======
+
+  -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+>>>>>>> tao
+.Ed
+.Pp
+.Ss  How Xr diff3 Merges Incomplete Lines
+With
+.Op -m ,
+incomplete lines (see Section
+.Dq Incomplete Lines )
+are simply copied to the output as they are found; if the merged output ends
+in an conflict and one of the input files ends in an incomplete line, succeeding
+.Li ||||||| ,
+.Li =======
+or
+.Li >>>>>>>
+brackets appear somewhere other than the start of a line because they are
+appended to the incomplete line.
+.Pp
+Without
+.Op -m ,
+if an
+.Xr ed
+script option is specified and an incomplete line is found,
+.Xr diff3
+generates a warning and acts as if a newline had been present.
+.Pp
+.Ss  Saving the Changed File
+Traditional Unix
+.Xr diff3
+generates an
+.Xr ed
+script without the trailing
+.Li w
+and
+.Li q
+commands that save the changes. System V
+.Xr diff3
+generates these extra commands. GNU
+.Xr diff3
+normally behaves like traditional Unix
+.Xr diff3 ,
+but with the
+.Op -i
+option it behaves like System V
+.Xr diff3
+and appends the
+.Li w
+and
+.Li q
+commands.
+.Pp
+The
+.Op -i
+option requires one of the
+.Xr ed
+script options
+.Op -AeExX3 ,
+and is incompatible with the merged output option
+.Op -m .
+.Pp
+.Sh  Interactive Merging with Xr sdiff
+With
+.Xr sdiff ,
+you can merge two files interactively based on a side-by-side
+.Op -y
+format comparison (see Section
+.Dq Side by Side ) .
+Use
+.Op -o Va file
+or
+.Op --output= Va file
+to specify where to put the merged text.See Section
+.Dq Invoking sdiff ,
+for more details on the options to
+.Xr sdiff .
+.Pp
+Another way to merge files interactively is to use the Emacs Lisp package
+.Xr emerge .
+See Section.Dq emerge ,
+for more information.
+.Pp
+.Ss  Specifying Xr diff Options to Xr sdiff
+The following
+.Xr sdiff
+options have the same meaning as for
+.Xr diff .
+See Section.Dq diff Options ,
+for the use of these options.
+.Pp
+.Bd -literal -offset indent
+-a -b -d -i -t -v
+-B -E -I regexp
+
+--expand-tabs
+--ignore-blank-lines  --ignore-case
+--ignore-matching-lines=regexp  --ignore-space-change
+--ignore-tab-expansion
+--left-column  --minimal  --speed-large-files
+--strip-trailing-cr  --suppress-common-lines
+--tabsize=columns  --text  --version  --width=columns
+.Ed
+.Pp
+For historical reasons,
+.Xr sdiff
+has alternate names for some options. The
+.Op -l
+option is equivalent to the
+.Op --left-column
+option, and similarly
+.Op -s
+is equivalent to
+.Op --suppress-common-lines .
+The meaning of the
+.Xr sdiff
+.Op -w
+and
+.Op -W
+options is interchanged from that of
+.Xr diff :
+with
+.Xr sdiff ,
+.Op -w Va columns
+is equivalent to
+.Op --width= Va columns ,
+and
+.Op -W
+is equivalent to
+.Op --ignore-all-space .
+.Xr sdiff
+without the
+.Op -o
+option is equivalent to
+.Xr diff
+with the
+.Op -y
+or
+.Op --side-by-side
+option (see Section
+.Dq Side by Side ) .
+.Pp
+.Ss  Merge Commands
+Groups of common lines, with a blank gutter, are copied from the first file
+to the output. After each group of differing lines,
+.Xr sdiff
+prompts with
+.Li %
+and pauses, waiting for one of the following commands. Follow each command
+with RET.
+.Pp
+.Bl -tag -width Ds
+.It  e
+Discard both versions. Invoke a text editor on an empty temporary file, then
+copy the resulting file to the output.
+.Pp
+.It  eb
+Concatenate the two versions, edit the result in a temporary file, then copy
+the edited result to the output.
+.Pp
+.It  ed
+Like
+.Li eb ,
+except precede each version with a header that shows what file and lines the
+version came from.
+.Pp
+.It  el
+.It  e1
+Edit a copy of the left version, then copy the result to the output.
+.Pp
+.It  er
+.It  e2
+Edit a copy of the right version, then copy the result to the output.
+.Pp
+.It  l
+.It  1
+Copy the left version to the output.
+.Pp
+.It  q
+Quit.
+.Pp
+.It  r
+.It  2
+Copy the right version to the output.
+.Pp
+.It  s
+Silently copy common lines.
+.Pp
+.It  v
+Verbosely copy common lines. This is the default.
+.El
+.Pp
+The text editor invoked is specified by the
+.Ev EDITOR
+environment variable if it is set. The default is system-dependent.
+.Pp
+.Sh  Merging with Xr patch
+.Xr patch
+takes comparison output produced by
+.Xr diff
+and applies the differences to a copy of the original file, producing a patched
+version. With
+.Xr patch ,
+you can distribute just the changes to a set of files instead of distributing
+the entire file set; your correspondents can apply
+.Xr patch
+to update their copy of the files with your changes.
+.Xr patch
+automatically determines the diff format, skips any leading or trailing headers,
+and uses the headers to determine which file to patch. This lets your correspondents
+feed a mail message containing a difference listing directly to
+.Xr patch .
+.Pp
+.Xr patch
+detects and warns about common problems like forward patches. It saves any
+patches that it could not apply. It can also maintain a
+.Li patchlevel.h
+file to ensure that your correspondents apply diffs in the proper order.
+.Pp
+.Xr patch
+accepts a series of diffs in its standard input, usually separated by headers
+that specify which file to patch. It applies
+.Xr diff
+hunks (see Section
+.Dq Hunks )
+one by one. If a hunk does not exactly match the original file,
+.Xr patch
+uses heuristics to try to patch the file as well as it can. If no approximate
+match can be found,
+.Xr patch
+rejects the hunk and skips to the next hunk.
+.Xr patch
+normally replaces each file
+.Va f
+with its new version, putting reject hunks (if any) into
+.Li  Va f.rej .
+.Pp
+See Section.Dq Invoking patch ,
+for detailed information on the options to
+.Xr patch .
+.Pp
+.Ss  Selecting the Xr patch Input Format
+.Xr patch
+normally determines which
+.Xr diff
+format the patch file uses by examining its contents. For patch files that
+contain particularly confusing leading text, you might need to use one of
+the following options to force
+.Xr patch
+to interpret the patch file as a certain format of diff. The output formats
+listed here are the only ones that
+.Xr patch
+can understand.
+.Pp
+.Bl -tag -width Ds
+.It  -c
+.It  --context
+context diff.
+.Pp
+.It  -e
+.It  --ed
+.Xr ed
+script.
+.Pp
+.It  -n
+.It  --normal
+normal diff.
+.Pp
+.It  -u
+.It  --unified
+unified diff.
+.El
+.Pp
+.Ss  Revision Control
+If a nonexistent input file is under a revision control system supported by
+.Xr patch ,
+.Xr patch
+normally asks the user whether to get (or check out) the file from the revision
+control system. Patch currently supports RCS, ClearCase and SCCS. Under RCS
+and SCCS,
+.Xr patch
+also asks when the input file is read-only and matches the default version
+in the revision control system.
+.Pp
+The
+.Op -g Va num
+or
+.Op --get= Va num
+option affects access to files under supported revision control systems. If
+.Va num
+is positive,
+.Xr patch
+gets the file without asking the user; if zero,
+.Xr patch
+neither asks the user nor gets the file; and if negative,
+.Xr patch
+asks the user before getting the file. The default value of
+.Va num
+is given by the value of the
+.Ev PATCH_GET
+environment variable if it is set; if not, the default value is zero if
+.Xr patch
+is conforming to POSIX, negative otherwise.See Section
+.Dq patch and POSIX .
+.Pp
+The choice of revision control system is unaffected by the
+.Ev VERSION_CONTROL
+environment variable (see Section
+.Dq Backup Names ) .
+.Pp
+.Ss  Applying Imperfect Patches
+.Xr patch
+tries to skip any leading text in the patch file, apply the diff, and then
+skip any trailing text. Thus you can feed a mail message directly to
+.Xr patch ,
+and it should work. If the entire diff is indented by a constant amount of
+white space,
+.Xr patch
+automatically ignores the indentation. If a context diff contains trailing
+carriage return on each line,
+.Xr patch
+automatically ignores the carriage return. If a context diff has been encapsulated
+by prepending
+.Li -
+to lines beginning with
+.Li -
+as per
+.Lk ftp://ftp.isi.edu/in-notes/rfc934.txt ,
+.Xr patch
+automatically unencapsulates the input.
+.Pp
+However, certain other types of imperfect input require user intervention
+or testing.
+.Pp
+.Em  Applying Patches with Changed White Space
+.Pp
+Sometimes mailers, editors, or other programs change spaces into tabs, or
+vice versa. If this happens to a patch file or an input file, the files might
+look the same, but
+.Xr patch
+will not be able to match them properly. If this problem occurs, use the
+.Op -l
+or
+.Op --ignore-white-space
+option, which makes
+.Xr patch
+compare blank characters (i.e. spaces and tabs) loosely so that any nonempty
+sequence of blanks in the patch file matches any nonempty sequence of blanks
+in the input files. Non-blank characters must still match exactly. Each line
+of the context must still match a line in the input file.
+.Pp
+.Em  Applying Reversed Patches
+.Pp
+Sometimes people run
+.Xr diff
+with the new file first instead of second. This creates a diff that is \(lqreversed\(rq.
+To apply such patches, give
+.Xr patch
+the
+.Op -R
+or
+.Op --reverse
+option.
+.Xr patch
+then attempts to swap each hunk around before applying it. Rejects come out
+in the swapped format.
+.Pp
+Often
+.Xr patch
+can guess that the patch is reversed. If the first hunk of a patch fails,
+.Xr patch
+reverses the hunk to see if it can apply it that way. If it can,
+.Xr patch
+asks you if you want to have the
+.Op -R
+option set; if it can't,
+.Xr patch
+continues to apply the patch normally. This method cannot detect a reversed
+patch if it is a normal diff and the first command is an append (which should
+have been a delete) since appends always succeed, because a null context matches
+anywhere. But most patches add or change lines rather than delete them, so
+most reversed normal diffs begin with a delete, which fails, and
+.Xr patch
+notices.
+.Pp
+If you apply a patch that you have already applied,
+.Xr patch
+thinks it is a reversed patch and offers to un-apply the patch. This could
+be construed as a feature. If you did this inadvertently and you don't want
+to un-apply the patch, just answer
+.Li n
+to this offer and to the subsequent \(lqapply anyway\(rq question---or type
+.Li C-c
+to kill the
+.Xr patch
+process.
+.Pp
+.Em  Helping Xr patch Find Inexact Matches
+.Pp
+For context diffs, and to a lesser extent normal diffs,
+.Xr patch
+can detect when the line numbers mentioned in the patch are incorrect, and
+it attempts to find the correct place to apply each hunk of the patch. As
+a first guess, it takes the line number mentioned in the hunk, plus or minus
+any offset used in applying the previous hunk. If that is not the correct
+place,
+.Xr patch
+scans both forward and backward for a set of lines matching the context given
+in the hunk.
+.Pp
+First
+.Xr patch
+looks for a place where all lines of the context match. If it cannot find
+such a place, and it is reading a context or unified diff, and the maximum
+fuzz factor is set to 1 or more, then
+.Xr patch
+makes another scan, ignoring the first and last line of context. If that fails,
+and the maximum fuzz factor is set to 2 or more, it makes another scan, ignoring
+the first two and last two lines of context are ignored. It continues similarly
+if the maximum fuzz factor is larger.
+.Pp
+The
+.Op -F Va lines
+or
+.Op --fuzz= Va lines
+option sets the maximum fuzz factor to
+.Va lines .
+This option only applies to context and unified diffs; it ignores up to
+.Va lines
+lines while looking for the place to install a hunk. Note that a larger fuzz
+factor increases the odds of making a faulty patch. The default fuzz factor
+is 2; there is no point to setting it to more than the number of lines of
+context in the diff, ordinarily 3.
+.Pp
+If
+.Xr patch
+cannot find a place to install a hunk of the patch, it writes the hunk out
+to a reject file (see Section
+.Dq Reject Names ,
+for information on how reject files are named). It writes out rejected hunks
+in context format no matter what form the input patch is in. If the input
+is a normal or
+.Xr ed
+diff, many of the contexts are simply null. The line numbers on the hunks
+in the reject file may be different from those in the patch file: they show
+the approximate location where
+.Xr patch
+thinks the failed hunks belong in the new file rather than in the old one.
+.Pp
+If the
+.Op --verbose
+option is given, then as it completes each hunk
+.Xr patch
+tells you whether the hunk succeeded or failed, and if it failed, on which
+line (in the new file)
+.Xr patch
+thinks the hunk should go. If this is different from the line number specified
+in the diff, it tells you the offset. A single large offset
+.Em may
+indicate that
+.Xr patch
+installed a hunk in the wrong place.
+.Xr patch
+also tells you if it used a fuzz factor to make the match, in which case you
+should also be slightly suspicious.
+.Pp
+.Xr patch
+cannot tell if the line numbers are off in an
+.Xr ed
+script, and can only detect wrong line numbers in a normal diff when it finds
+a change or delete command. It may have the same problem with a context diff
+using a fuzz factor equal to or greater than the number of lines of context
+shown in the diff (typically 3). In these cases, you should probably look
+at a context diff between your original and patched input files to see if
+the changes make sense. Compiling without errors is a pretty good indication
+that the patch worked, but not a guarantee.
+.Pp
+A patch against an empty file applies to a nonexistent file, and vice versa.See Section
+.Dq Creating and Removing .
+.Pp
+.Xr patch
+usually produces the correct results, even when it must make many guesses.
+However, the results are guaranteed only when the patch is applied to an exact
+copy of the file that the patch was generated from.
+.Pp
+.Em  Predicting what Xr patch will do
+.Pp
+It may not be obvious in advance what
+.Xr patch
+will do with a complicated or poorly formatted patch. If you are concerned
+that the input might cause
+.Xr patch
+to modify the wrong files, you can use the
+.Op --dry-run
+option, which causes
+.Xr patch
+to print the results of applying patches without actually changing any files.
+You can then inspect the diagnostics generated by the dry run to see whether
+.Xr patch
+will modify the files that you expect. If the patch does not do what you want,
+you can modify the patch (or the other options to
+.Xr patch )
+and try another dry run. Once you are satisfied with the proposed patch you
+can apply it by invoking
+.Xr patch
+as before, but this time without the
+.Op --dry-run
+option.
+.Pp
+.Ss  Creating and Removing Files
+Sometimes when comparing two directories, a file may exist in one directory
+but not the other. If you give
+.Xr diff
+the
+.Op -N
+or
+.Op --new-file
+option, or if you supply an old or new file that is named
+.Pa /dev/null
+or is empty and is dated the Epoch (1970-01-01 00:00:00 UTC),
+.Xr diff
+outputs a patch that adds or deletes the contents of this file. When given
+such a patch,
+.Xr patch
+normally creates a new file or removes the old file. However, when conforming
+to POSIX (see Section
+.Dq patch and POSIX ) ,
+.Xr patch
+does not remove the old file, but leaves it empty. The
+.Op -E
+or
+.Op --remove-empty-files
+option causes
+.Xr patch
+to remove output files that are empty after applying a patch, even if the
+patch does not appear to be one that removed the file.
+.Pp
+If the patch appears to create a file that already exists,
+.Xr patch
+asks for confirmation before applying the patch.
+.Pp
+.Ss  Updating Time Stamps on Patched Files
+When
+.Xr patch
+updates a file, it normally sets the file's last-modified time stamp to the
+current time of day. If you are using
+.Xr patch
+to track a software distribution, this can cause
+.Xr make
+to incorrectly conclude that a patched file is out of date. For example, if
+.Pa syntax.c
+depends on
+.Pa syntax.y ,
+and
+.Xr patch
+updates
+.Pa syntax.c
+and then
+.Pa syntax.y ,
+then
+.Pa syntax.c
+will normally appear to be out of date with respect to
+.Pa syntax.y
+even though its contents are actually up to date.
+.Pp
+The
+.Op -Z
+or
+.Op --set-utc
+option causes
+.Xr patch
+to set a patched file's modification and access times to the time stamps given
+in context diff headers. If the context diff headers do not specify a time
+zone, they are assumed to use Coordinated Universal Time (UTC, often known
+as GMT).
+.Pp
+The
+.Op -T
+or
+.Op --set-time
+option acts like
+.Op -Z
+or
+.Op --set-utc ,
+except that it assumes that the context diff headers' time stamps use local
+time instead of UTC. This option is not recommended, because patches using
+local time cannot easily be used by people in other time zones, and because
+local time stamps are ambiguous when local clocks move backwards during daylight-saving
+time adjustments. If the context diff headers specify a time zone, this option
+is equivalent to
+.Op -Z
+or
+.Op --set-utc .
+.Pp
+.Xr patch
+normally refrains from setting a file's time stamps if the file's original
+last-modified time stamp does not match the time given in the diff header,
+of if the file's contents do not exactly match the patch. However, if the
+.Op -f
+or
+.Op --force
+option is given, the file's time stamps are set regardless.
+.Pp
+Due to the limitations of the current
+.Xr diff
+format,
+.Xr patch
+cannot update the times of files whose contents have not changed. Also, if
+you set file time stamps to values other than the current time of day, you
+should also remove (e.g., with
+.Li make clean )
+all files that depend on the patched files, so that later invocations of
+.Xr make
+do not get confused by the patched files' times.
+.Pp
+.Ss  Multiple Patches in a File
+If the patch file contains more than one patch, and if you do not specify
+an input file on the command line,
+.Xr patch
+tries to apply each patch as if they came from separate patch files. This
+means that it determines the name of the file to patch for each patch, and
+that it examines the leading text before each patch for file names and prerequisite
+revision level (see Section
+.Dq Making Patches ,
+for more on that topic).
+.Pp
+.Xr patch
+uses the following rules to intuit a file name from the leading text before
+a patch. First,
+.Xr patch
+takes an ordered list of candidate file names as follows:
+.Pp
+.Bl -bullet
+.It
+If the header is that of a context diff,
+.Xr patch
+takes the old and new file names in the header. A name is ignored if it does
+not have enough slashes to satisfy the
+.Op -p Va num
+or
+.Op --strip= Va num
+option. The name
+.Pa /dev/null
+is also ignored.
+.Pp
+.It
+If there is an
+.Li Index:
+line in the leading garbage and if either the old and new names are both absent
+or if
+.Xr patch
+is conforming to POSIX,
+.Xr patch
+takes the name in the
+.Li Index:
+line.
+.Pp
+.It
+For the purpose of the following rules, the candidate file names are considered
+to be in the order (old, new, index), regardless of the order that they appear
+in the header.
+.El
+.Pp
+Then
+.Xr patch
+selects a file name from the candidate list as follows:
+.Pp
+.Bl -bullet
+.It
+If some of the named files exist,
+.Xr patch
+selects the first name if conforming to POSIX, and the best name otherwise.
+.Pp
+.It
+If
+.Xr patch
+is not ignoring RCS, ClearCase, and SCCS (see Section
+.Dq Revision Control ) ,
+and no named files exist but an RCS, ClearCase, or SCCS master is found,
+.Xr patch
+selects the first named file with an RCS, ClearCase, or SCCS master.
+.Pp
+.It
+If no named files exist, no RCS, ClearCase, or SCCS master was found, some
+names are given,
+.Xr patch
+is not conforming to POSIX, and the patch appears to create a file,
+.Xr patch
+selects the best name requiring the creation of the fewest directories.
+.Pp
+.It
+If no file name results from the above heuristics, you are asked for the name
+of the file to patch, and
+.Xr patch
+selects that name.
+.El
+.Pp
+To determine the
+.Em best
+of a nonempty list of file names,
+.Xr patch
+first takes all the names with the fewest path name components; of those,
+it then takes all the names with the shortest basename; of those, it then
+takes all the shortest names; finally, it takes the first remaining name.
+.Pp
+See Section.Dq patch and POSIX ,
+to see whether
+.Xr patch
+is conforming to POSIX.
+.Pp
+.Ss  Applying Patches in Other Directories
+The
+.Op -d Va directory
+or
+.Op --directory= Va directory
+option to
+.Xr patch
+makes directory
+.Va directory
+the current directory for interpreting both file names in the patch file,
+and file names given as arguments to other options (such as
+.Op -B
+and
+.Op -o ) .
+For example, while in a mail reading program, you can patch a file in the
+.Pa /usr/src/emacs
+directory directly from a message containing the patch like this:
+.Pp
+.Bd -literal -offset indent
+| patch -d /usr/src/emacs
+.Ed
+.Pp
+Sometimes the file names given in a patch contain leading directories, but
+you keep your files in a directory different from the one given in the patch.
+In those cases, you can use the
+.Op -p Va number
+or
+.Op --strip= Va number
+option to set the file name strip count to
+.Va number .
+The strip count tells
+.Xr patch
+how many slashes, along with the directory names between them, to strip from
+the front of file names. A sequence of one or more adjacent slashes is counted
+as a single slash. By default,
+.Xr patch
+strips off all leading directories, leaving just the base file names.
+.Pp
+For example, suppose the file name in the patch file is
+.Pa /gnu/src/emacs/etc/NEWS .
+Using
+.Op -p0
+gives the entire file name unmodified,
+.Op -p1
+gives
+.Pa gnu/src/emacs/etc/NEWS
+(no leading slash),
+.Op -p4
+gives
+.Pa etc/NEWS ,
+and not specifying
+.Op -p
+at all gives
+.Pa NEWS .
+.Pp
+.Xr patch
+looks for each file (after any slashes have been stripped) in the current
+directory, or if you used the
+.Op -d Va directory
+option, in that directory.
+.Pp
+.Ss  Backup Files
+Normally,
+.Xr patch
+creates a backup file if the patch does not exactly match the original input
+file, because in that case the original data might not be recovered if you
+undo the patch with
+.Li patch -R
+(see Section
+.Dq Reversed Patches ) .
+However, when conforming to POSIX,
+.Xr patch
+does not create backup files by default.See Section
+.Dq patch and POSIX .
+.Pp
+The
+.Op -b
+or
+.Op --backup
+option causes
+.Xr patch
+to make a backup file regardless of whether the patch matches the original
+input. The
+.Op --backup-if-mismatch
+option causes
+.Xr patch
+to create backup files for mismatches files; this is the default when not
+conforming to POSIX. The
+.Op --no-backup-if-mismatch
+option causes
+.Xr patch
+to not create backup files, even for mismatched patches; this is the default
+when conforming to POSIX.
+.Pp
+When backing up a file that does not exist, an empty, unreadable backup file
+is created as a placeholder to represent the nonexistent file.
+.Pp
+.Ss  Backup File Names
+Normally,
+.Xr patch
+renames an original input file into a backup file by appending to its name
+the extension
+.Li .orig ,
+or
+.Li ~
+if using
+.Li .orig
+would make the backup file name too long. The
+.Op -z Va backup-suffix
+or
+.Op --suffix= Va backup-suffix
+option causes
+.Xr patch
+to use
+.Va backup-suffix
+as the backup extension instead.
+.Pp
+Alternately, you can specify the extension for backup files with the
+.Ev SIMPLE_BACKUP_SUFFIX
+environment variable, which the options override.
+.Pp
+.Xr patch
+can also create numbered backup files the way GNU Emacs does. With this method,
+instead of having a single backup of each file,
+.Xr patch
+makes a new backup file name each time it patches a file. For example, the
+backups of a file named
+.Pa sink
+would be called, successively,
+.Pa sink.~1~ ,
+.Pa sink.~2~ ,
+.Pa sink.~3~ ,
+etc.
+.Pp
+The
+.Op -V Va backup-style
+or
+.Op --version-control= Va backup-style
+option takes as an argument a method for creating backup file names. You can
+alternately control the type of backups that
+.Xr patch
+makes with the
+.Ev PATCH_VERSION_CONTROL
+environment variable, which the
+.Op -V
+option overrides. If
+.Ev PATCH_VERSION_CONTROL
+is not set, the
+.Ev VERSION_CONTROL
+environment variable is used instead. Please note that these options and variables
+control backup file names; they do not affect the choice of revision control
+system (see Section
+.Dq Revision Control ) .
+.Pp
+The values of these environment variables and the argument to the
+.Op -V
+option are like the GNU Emacs
+.Li version-control
+variable (see Section
+.Dq Backup Names ,
+for more information on backup versions in Emacs). They also recognize synonyms
+that are more descriptive. The valid values are listed below; unique abbreviations
+are acceptable.
+.Pp
+.Bl -tag -width Ds
+.It  t
+.It  numbered
+Always make numbered backups.
+.Pp
+.It  nil
+.It  existing
+Make numbered backups of files that already have them, simple backups of the
+others. This is the default.
+.Pp
+.It  never
+.It  simple
+Always make simple backups.
+.El
+.Pp
+You can also tell
+.Xr patch
+to prepend a prefix, such as a directory name, to produce backup file names.
+The
+.Op -B Va prefix
+or
+.Op --prefix= Va prefix
+option makes backup files by prepending
+.Va prefix
+to them. The
+.Op -Y Va prefix
+or
+.Op --basename-prefix= Va prefix
+prepends
+.Va prefix
+to the last file name component of backup file names instead; for example,
+.Op -Y ~
+causes the backup name for
+.Pa dir/file.c
+to be
+.Pa dir/~file.c .
+If you use either of these prefix options, the suffix-based options are ignored.
+.Pp
+If you specify the output file with the
+.Op -o
+option, that file is the one that is backed up, not the input file.
+.Pp
+Options that affect the names of backup files do not affect whether backups
+are made. For example, if you specify the
+.Op --no-backup-if-mismatch
+option, none of the options described in this section have any affect, because
+no backups are made.
+.Pp
+.Ss  Reject File Names
+The names for reject files (files containing patches that
+.Xr patch
+could not find a place to apply) are normally the name of the output file
+with
+.Li .rej
+appended (or
+.Li #
+if using
+.Li .rej
+would make the backup file name too long).
+.Pp
+Alternatively, you can tell
+.Xr patch
+to place all of the rejected patches in a single file. The
+.Op -r Va reject-file
+or
+.Op --reject-file= Va reject-file
+option uses
+.Va reject-file
+as the reject file name.
+.Pp
+.Ss  Messages and Questions from Xr patch
+.Xr patch
+can produce a variety of messages, especially if it has trouble decoding its
+input. In a few situations where it's not sure how to proceed,
+.Xr patch
+normally prompts you for more information from the keyboard. There are options
+to produce more or fewer messages, to have it not ask for keyboard input,
+and to affect the way that file names are quoted in messages.
+.Pp
+.Xr patch
+exits with status 0 if all hunks are applied successfully, 1 if some hunks
+cannot be applied, and 2 if there is more serious trouble. When applying a
+set of patches in a loop, you should check the exit status, so you don't apply
+a later patch to a partially patched file.
+.Pp
+.Em  Controlling the Verbosity of Xr patch
+.Pp
+You can cause
+.Xr patch
+to produce more messages by using the
+.Op --verbose
+option. For example, when you give this option, the message
+.Li Hmm...
+indicates that
+.Xr patch
+is reading text in the patch file, attempting to determine whether there is
+a patch in that text, and if so, what kind of patch it is.
+.Pp
+You can inhibit all terminal output from
+.Xr patch ,
+unless an error occurs, by using the
+.Op -s ,
+.Op --quiet ,
+or
+.Op --silent
+option.
+.Pp
+.Em  Inhibiting Keyboard Input
+.Pp
+There are two ways you can prevent
+.Xr patch
+from asking you any questions. The
+.Op -f
+or
+.Op --force
+option assumes that you know what you are doing. It causes
+.Xr patch
+to do the following:
+.Pp
+.Bl -bullet
+.It
+Skip patches that do not contain file names in their headers.
+.Pp
+.It
+Patch files even though they have the wrong version for the
+.Li Prereq:
+line in the patch;
+.Pp
+.It
+Assume that patches are not reversed even if they look like they are.
+.El
+.Pp
+The
+.Op -t
+or
+.Op --batch
+option is similar to
+.Op -f ,
+in that it suppresses questions, but it makes somewhat different assumptions:
+.Pp
+.Bl -bullet
+.It
+Skip patches that do not contain file names in their headers (the same as
+.Op -f ) .
+.Pp
+.It
+Skip patches for which the file has the wrong version for the
+.Li Prereq:
+line in the patch;
+.Pp
+.It
+Assume that patches are reversed if they look like they are.
+.El
+.Pp
+.Em  Xr patch Quoting Style
+.Pp
+When
+.Xr patch
+outputs a file name in a diagnostic message, it can format the name in any
+of several ways. This can be useful to output file names unambiguously, even
+if they contain punctuation or special characters like newlines. The
+.Op --quoting-style= Va word
+option controls how names are output. The
+.Va word
+should be one of the following:
+.Pp
+.Bl -tag -width Ds
+.It  literal
+Output names as-is.
+.It  shell
+Quote names for the shell if they contain shell metacharacters or would cause
+ambiguous output.
+.It  shell-always
+Quote names for the shell, even if they would normally not require quoting.
+.It  c
+Quote names as for a C language string.
+.It  escape
+Quote as with
+.Li c
+except omit the surrounding double-quote characters.
+.El
+.Pp
+You can specify the default value of the
+.Op --quoting-style
+option with the environment variable
+.Ev QUOTING_STYLE .
+If that environment variable is not set, the default value is
+.Li shell ,
+but this default may change in a future version of
+.Xr patch .
+.Pp
+.Ss  Xr patch and the POSIX Standard
+If you specify the
+.Op --posix
+option, or set the
+.Ev POSIXLY_CORRECT
+environment variable,
+.Xr patch
+conforms more strictly to the POSIX standard, as follows:
+.Pp
+.Bl -bullet
+.It
+Take the first existing file from the list (old, new, index) when intuiting
+file names from diff headers.See Section
+.Dq Multiple Patches .
+.Pp
+.It
+Do not remove files that are removed by a diff.See Section
+.Dq Creating and Removing .
+.Pp
+.It
+Do not ask whether to get files from RCS, ClearCase, or SCCS.See Section
+.Dq Revision Control .
+.Pp
+.It
+Require that all options precede the files in the command line.
+.Pp
+.It
+Do not backup files, even when there is a mismatch.See Section
+.Dq Backups .
+.Pp
+.El
+.Ss  GNU Xr patch and Traditional Xr patch
+The current version of GNU
+.Xr patch
+normally follows the POSIX standard.See Section
+.Dq patch and POSIX ,
+for the few exceptions to this general rule.
+.Pp
+Unfortunately, POSIX redefined the behavior of
+.Xr patch
+in several important ways. You should be aware of the following differences
+if you must interoperate with traditional
+.Xr patch ,
+or with GNU
+.Xr patch
+version 2.1 and earlier.
+.Pp
+.Bl -bullet
+.It
+In traditional
+.Xr patch ,
+the
+.Op -p
+option's operand was optional, and a bare
+.Op -p
+was equivalent to
+.Op -p0 .
+The
+.Op -p
+option now requires an operand, and
+.Op -p 0
+is now equivalent to
+.Op -p0 .
+For maximum compatibility, use options like
+.Op -p0
+and
+.Op -p1 .
+.Pp
+Also, traditional
+.Xr patch
+simply counted slashes when stripping path prefixes;
+.Xr patch
+now counts pathname components. That is, a sequence of one or more adjacent
+slashes now counts as a single slash. For maximum portability, avoid sending
+patches containing
+.Pa //
+in file names.
+.Pp
+.It
+In traditional
+.Xr patch ,
+backups were enabled by default. This behavior is now enabled with the
+.Op -b
+or
+.Op --backup
+option.
+.Pp
+Conversely, in POSIX
+.Xr patch ,
+backups are never made, even when there is a mismatch. In GNU
+.Xr patch ,
+this behavior is enabled with the
+.Op --no-backup-if-mismatch
+option, or by conforming to POSIX.
+.Pp
+The
+.Op -b  Va suffix
+option of traditional
+.Xr patch
+is equivalent to the
+.Li -b -z  Va suffix
+options of GNU
+.Xr patch .
+.Pp
+.It
+Traditional
+.Xr patch
+used a complicated (and incompletely documented) method to intuit the name
+of the file to be patched from the patch header. This method did not conform
+to POSIX, and had a few gotchas. Now
+.Xr patch
+uses a different, equally complicated (but better documented) method that
+is optionally POSIX-conforming; we hope it has fewer gotchas. The two methods
+are compatible if the file names in the context diff header and the
+.Li Index:
+line are all identical after prefix-stripping. Your patch is normally compatible
+if each header's file names all contain the same number of slashes.
+.Pp
+.It
+When traditional
+.Xr patch
+asked the user a question, it sent the question to standard error and looked
+for an answer from the first file in the following list that was a terminal:
+standard error, standard output,
+.Pa /dev/tty ,
+and standard input. Now
+.Xr patch
+sends questions to standard output and gets answers from
+.Pa /dev/tty .
+Defaults for some answers have been changed so that
+.Xr patch
+never goes into an infinite loop when using default answers.
+.Pp
+.It
+Traditional
+.Xr patch
+exited with a status value that counted the number of bad hunks, or with status
+1 if there was real trouble. Now
+.Xr patch
+exits with status 1 if some hunks failed, or with 2 if there was real trouble.
+.Pp
+.It
+Limit yourself to the following options when sending instructions meant to
+be executed by anyone running GNU
+.Xr patch ,
+traditional
+.Xr patch ,
+or a
+.Xr patch
+that conforms to POSIX. Spaces are significant in the following list, and
+operands are required.
+.Pp
+.Bd -literal -offset indent
+-c
+-d dir
+-D define
+-e
+-l
+-n
+-N
+-o outfile
+-pnum
+-R
+-r rejectfile
+.Ed
+.Pp
+.El
+.Sh  Tips for Making and Using Patches
+Use some common sense when making and using patches. For example, when sending
+bug fixes to a program's maintainer, send several small patches, one per independent
+subject, instead of one large, harder-to-digest patch that covers all the
+subjects.
+.Pp
+Here are some other things you should keep in mind if you are going to distribute
+patches for updating a software package.
+.Pp
+.Ss  Tips for Patch Producers
+To create a patch that changes an older version of a package into a newer
+version, first make a copy of the older and newer versions in adjacent subdirectories.
+It is common to do that by unpacking
+.Xr tar
+archives of the two versions.
+.Pp
+To generate the patch, use the command
+.Li diff -Naur Va old Va new
+where
+.Va old
+and
+.Va new
+identify the old and new directories. The names
+.Va old
+and
+.Va new
+should not contain any slashes. The
+.Op -N
+option lets the patch create and remove files;
+.Op -a
+lets the patch update non-text files;
+.Op -u
+generates useful time stamps and enough context; and
+.Op -r
+lets the patch update subdirectories. Here is an example command, using Bourne
+shell syntax:
+.Pp
+.Bd -literal -offset indent
+diff -Naur gcc-3.0.3 gcc-3.0.4
+.Ed
+.Pp
+Tell your recipients how to apply the patches. This should include which working
+directory to use, and which
+.Xr patch
+options to use; the option
+.Li -p1
+is recommended. Test your procedure by pretending to be a recipient and applying
+your patches to a copy of the original files.
+.Pp
+See Section.Dq Avoiding Common Mistakes ,
+for how to avoid common mistakes when generating a patch.
+.Pp
+.Ss  Tips for Patch Consumers
+A patch producer should tell recipients how to apply the patches, so the first
+rule of thumb for a patch consumer is to follow the instructions supplied
+with the patch.
+.Pp
+GNU
+.Xr diff
+can analyze files with arbitrarily long lines and files that end in incomplete
+lines. However, older versions of
+.Xr patch
+cannot patch such files. If you are having trouble applying such patches,
+try upgrading to a recent version of GNU
+.Xr patch .
+.Pp
+.Ss  Avoiding Common Mistakes
+When producing a patch for multiple files, apply
+.Xr diff
+to directories whose names do not have slashes. This reduces confusion when
+the patch consumer specifies the
+.Op -p Va number
+option, since this option can have surprising results when the old and new
+file names have different numbers of slashes. For example, do not send a patch
+with a header that looks like this:
+.Pp
+.Bd -literal -offset indent
+diff -Naur v2.0.29/prog/README prog/README
+--- v2.0.29/prog/README	2002-03-10 23:30:39.942229878 -0800
++++ prog/README	2002-03-17 20:49:32.442260588 -0800
+.Ed
+.Pp
+because the two file names have different numbers of slashes, and different
+versions of
+.Xr patch
+interpret the file names differently. To avoid confusion, send output that
+looks like this instead:
+.Pp
+.Bd -literal -offset indent
+diff -Naur v2.0.29/prog/README v2.0.30/prog/README
+--- v2.0.29/prog/README	2002-03-10 23:30:39.942229878 -0800
++++ v2.0.30/prog/README	2002-03-17 20:49:32.442260588 -0800
+.Ed
+.Pp
+Make sure you have specified the file names correctly, either in a context
+diff header or with an
+.Li Index:
+line. Take care to not send out reversed patches, since these make people
+wonder whether they have already applied the patch.
+.Pp
+Avoid sending patches that compare backup file names like
+.Pa README.orig
+or
+.Pa README~ ,
+since this might confuse
+.Xr patch
+into patching a backup file instead of the real file. Instead, send patches
+that compare the same base file names in different directories, e.g.
+.Pa old/README
+and
+.Pa new/README .
+.Pp
+To save people from partially applying a patch before other patches that should
+have gone before it, you can make the first patch in the patch file update
+a file with a name like
+.Pa patchlevel.h
+or
+.Pa version.c ,
+which contains a patch level or version number. If the input file contains
+the wrong version number,
+.Xr patch
+will complain immediately.
+.Pp
+An even clearer way to prevent this problem is to put a
+.Li Prereq:
+line before the patch. If the leading text in the patch file contains a line
+that starts with
+.Li Prereq: ,
+.Xr patch
+takes the next word from that line (normally a version number) and checks
+whether the next input file contains that word, preceded and followed by either
+white space or a newline. If not,
+.Xr patch
+prompts you for confirmation before proceeding. This makes it difficult to
+accidentally apply patches in the wrong order.
+.Pp
+.Ss  Generating Smaller Patches
+The simplest way to generate a patch is to use
+.Li diff -Naur
+(see Section
+.Dq Tips for Patch Producers ) ,
+but you might be able to reduce the size of the patch by renaming or removing
+some files before making the patch. If the older version of the package contains
+any files that the newer version does not, or if any files have been renamed
+between the two versions, make a list of
+.Xr rm
+and
+.Xr mv
+commands for the user to execute in the old version directory before applying
+the patch. Then run those commands yourself in the scratch directory.
+.Pp
+If there are any files that you don't need to include in the patch because
+they can easily be rebuilt from other files (for example,
+.Pa TAGS
+and output from
+.Xr yacc
+and
+.Xr makeinfo ) ,
+exclude them from the patch by giving
+.Xr diff
+the
+.Op -x Va pattern
+option (see Section
+.Dq Comparing Directories ) .
+If you want your patch to modify a derived file because your recipients lack
+tools to build it, make sure that the patch for the derived file follows any
+patches for files that it depends on, so that the recipients' time stamps
+will not confuse
+.Xr make .
+.Pp
+Now you can create the patch using
+.Li diff -Naur .
+Make sure to specify the scratch directory first and the newer directory second.
+.Pp
+Add to the top of the patch a note telling the user any
+.Xr rm
+and
+.Xr mv
+commands to run before applying the patch. Then you can remove the scratch
+directory.
+.Pp
+You can also shrink the patch size by using fewer lines of context, but bear
+in mind that
+.Xr patch
+typically needs at least two lines for proper operation when patches do not
+exactly match the input files.
+.Pp
+.Sh  Invoking Xr cmp
+The
+.Xr cmp
+command compares two files, and if they differ, tells the first byte and line
+number where they differ or reports that one file is a prefix of the other.
+Bytes and lines are numbered starting with 1. The arguments of
+.Xr cmp
+are as follows:
+.Pp
+.Bd -literal -offset indent
+cmp options... from-file [to-file [from-skip [to-skip]]]
+.Ed
+.Pp
+The file name
+.Pa -
+is always the standard input.
+.Xr cmp
+also uses the standard input if one file name is omitted. The
+.Va from-skip
+and
+.Va to-skip
+operands specify how many bytes to ignore at the start of each file; they
+are equivalent to the
+.Op --ignore-initial= Va from-skip: Va to-skip
+option.
+.Pp
+By default,
+.Xr cmp
+outputs nothing if the two files have the same contents. If one file is a
+prefix of the other,
+.Xr cmp
+prints to standard error a message of the following form:
+.Pp
+.Bd -literal -offset indent
+cmp: EOF on shorter-file
+.Ed
+.Pp
+Otherwise,
+.Xr cmp
+prints to standard output a message of the following form:
+.Pp
+.Bd -literal -offset indent
+from-file to-file differ: char byte-number, line line-number
+.Ed
+.Pp
+The message formats can differ outside the POSIX locale. Also, POSIX allows
+the EOF message to be followed by a blank and some additional information.
+.Pp
+An exit status of 0 means no differences were found, 1 means some differences
+were found, and 2 means trouble.
+.Pp
+.Ss  Options to Xr cmp
+Below is a summary of all of the options that GNU
+.Xr cmp
+accepts. Most options have two equivalent names, one of which is a single
+letter preceded by
+.Li - ,
+and the other of which is a long name preceded by
+.Li -- .
+Multiple single letter options (unless they take an argument) can be combined
+into a single command line word:
+.Op -bl
+is equivalent to
+.Op -b -l .
+.Pp
+.Bl -tag -width Ds
+.It  -b
+.It  --print-bytes
+Print the differing bytes. Display control bytes as a
+.Li ^
+followed by a letter of the alphabet and precede bytes that have the high
+bit set with
+.Li M-
+(which stands for \(lqmeta\(rq).
+.Pp
+.It  --help
+Output a summary of usage and then exit.
+.Pp
+.It  -i Va skip
+.It  --ignore-initial= Va skip
+Ignore any differences in the first
+.Va skip
+bytes of the input files. Treat files with fewer than
+.Va skip
+bytes as if they are empty. If
+.Va skip
+is of the form
+.Op  Va from-skip: Va to-skip ,
+skip the first
+.Va from-skip
+bytes of the first input file and the first
+.Va to-skip
+bytes of the second.
+.Pp
+.It  -l
+.It  --verbose
+Output the (decimal) byte numbers and (octal) values of all differing bytes,
+instead of the default standard output.
+.Pp
+.It  -n Va count
+.It  --bytes= Va count
+Compare at most
+.Va count
+input bytes.
+.Pp
+.It  -s
+.It  --quiet
+.It  --silent
+Do not print anything; only return an exit status indicating whether the files
+differ.
+.Pp
+.It  -v
+.It  --version
+Output version information and then exit.
+.El
+.Pp
+In the above table, operands that are byte counts are normally decimal, but
+may be preceded by
+.Li 0
+for octal and
+.Li 0x
+for hexadecimal.
+.Pp
+A byte count can be followed by a suffix to specify a multiple of that count;
+in this case an omitted integer is understood to be 1. A bare size letter,
+or one followed by
+.Li iB ,
+specifies a multiple using powers of 1024. A size letter followed by
+.Li B
+specifies powers of 1000 instead. For example,
+.Op -n 4M
+and
+.Op -n 4MiB
+are equivalent to
+.Op -n 4194304 ,
+whereas
+.Op -n 4MB
+is equivalent to
+.Op -n 4000000 .
+This notation is upward compatible with the
+.Lk http://www.bipm.fr/enus/3_SI/si-prefixes.html
+for decimal multiples and with the
+.Lk http://physics.nist.gov/cuu/Units/binary.html .
+.Pp
+The following suffixes are defined. Large sizes like
+.Li 1Y
+may be rejected by your computer due to limitations of its arithmetic.
+.Pp
+.Bl -tag -width Ds
+.It  kB
+kilobyte: 10^3 = 1000.
+.It  k
+.It  K
+.It  KiB
+kibibyte: 2^10 = 1024.
+.Li K
+is special: the SI prefix is
+.Li k
+and the IEC 60027-2 prefix is
+.Li Ki ,
+but tradition and POSIX use
+.Li k
+to mean
+.Li KiB .
+.It  MB
+megabyte: 10^6 = 1,000,000.
+.It  M
+.It  MiB
+mebibyte: 2^20 = 1,048,576.
+.It  GB
+gigabyte: 10^9 = 1,000,000,000.
+.It  G
+.It  GiB
+gibibyte: 2^30 = 1,073,741,824.
+.It  TB
+terabyte: 10^12 = 1,000,000,000,000.
+.It  T
+.It  TiB
+tebibyte: 2^40 = 1,099,511,627,776.
+.It  PB
+petabyte: 10^15 = 1,000,000,000,000,000.
+.It  P
+.It  PiB
+pebibyte: 2^50 = 1,125,899,906,842,624.
+.It  EB
+exabyte: 10^18 = 1,000,000,000,000,000,000.
+.It  E
+.It  EiB
+exbibyte: 2^60 = 1,152,921,504,606,846,976.
+.It  ZB
+zettabyte: 10^21 = 1,000,000,000,000,000,000,000
+.It  Z
+.It  ZiB
+2^70 = 1,180,591,620,717,411,303,424. (
+.Li Zi
+is a GNU extension to IEC 60027-2.)
+.It  YB
+yottabyte: 10^24 = 1,000,000,000,000,000,000,000,000.
+.It  Y
+.It  YiB
+2^80 = 1,208,925,819,614,629,174,706,176. (
+.Li Yi
+is a GNU extension to IEC 60027-2.)
+.El
+.Pp
+.Sh  Invoking Xr diff
+The format for running the
+.Xr diff
+command is:
+.Pp
+.Bd -literal -offset indent
+diff options... files...
+.Ed
+.Pp
+In the simplest case, two file names
+.Va from-file
+and
+.Va to-file
+are given, and
+.Xr diff
+compares the contents of
+.Va from-file
+and
+.Va to-file .
+A file name of
+.Pa -
+stands for text read from the standard input. As a special case,
+.Li diff - -
+compares a copy of standard input to itself.
+.Pp
+If one file is a directory and the other is not,
+.Xr diff
+compares the file in the directory whose name is that of the non-directory.
+The non-directory file must not be
+.Pa - .
+.Pp
+If two file names are given and both are directories,
+.Xr diff
+compares corresponding files in both directories, in alphabetical order; this
+comparison is not recursive unless the
+.Op -r
+or
+.Op --recursive
+option is given.
+.Xr diff
+never compares the actual contents of a directory as if it were a file. The
+file that is fully specified may not be standard input, because standard input
+is nameless and the notion of \(lqfile with the same name\(rq does not apply.
+.Pp
+If the
+.Op --from-file= Va file
+option is given, the number of file names is arbitrary, and
+.Va file
+is compared to each named file. Similarly, if the
+.Op --to-file= Va file
+option is given, each named file is compared to
+.Va file .
+.Pp
+.Xr diff
+options begin with
+.Li - ,
+so normally file names may not begin with
+.Li - .
+However,
+.Op --
+as an argument by itself treats the remaining arguments as file names even
+if they begin with
+.Li - .
+.Pp
+An exit status of 0 means no differences were found, 1 means some differences
+were found, and 2 means trouble. Normally, differing binary files count as
+trouble, but this can be altered by using the
+.Op -a
+or
+.Op --text
+option, or the
+.Op -q
+or
+.Op --brief
+option.
+.Pp
+.Ss  Options to Xr diff
+Below is a summary of all of the options that GNU
+.Xr diff
+accepts. Most options have two equivalent names, one of which is a single
+letter preceded by
+.Li - ,
+and the other of which is a long name preceded by
+.Li -- .
+Multiple single letter options (unless they take an argument) can be combined
+into a single command line word:
+.Op -ac
+is equivalent to
+.Op -a -c .
+Long named options can be abbreviated to any unique prefix of their name.
+Brackets ([ and ]) indicate that an option takes an optional argument.
+.Pp
+.Bl -tag -width Ds
+.It  -a
+.It  --text
+Treat all files as text and compare them line-by-line, even if they do not
+seem to be text.See Section
+.Dq Binary .
+.Pp
+.It  -b
+.It  --ignore-space-change
+Ignore changes in amount of white space.See Section
+.Dq White Space .
+.Pp
+.It  -B
+.It  --ignore-blank-lines
+Ignore changes that just insert or delete blank lines.See Section
+.Dq Blank Lines .
+.Pp
+.It  --binary
+Read and write data in binary mode.See Section
+.Dq Binary .
+.Pp
+.It  -c
+Use the context output format, showing three lines of context.See Section
+.Dq Context Format .
+.Pp
+.It  -C Va lines
+.It  --context[= Va lines]
+Use the context output format, showing
+.Va lines
+(an integer) lines of context, or three if
+.Va lines
+is not given.See Section
+.Dq Context Format .
+For proper operation,
+.Xr patch
+typically needs at least two lines of context.
+.Pp
+On older systems,
+.Xr diff
+supports an obsolete option
+.Op - Va lines
+that has effect when combined with
+.Op -c
+or
+.Op -p .
+POSIX 1003.1-2001 (see Section
+.Dq Standards conformance )
+does not allow this; use
+.Op -C Va lines
+instead.
+.Pp
+.It  --changed-group-format= Va format
+Use
+.Va format
+to output a line group containing differing lines from both files in if-then-else
+format.See Section
+.Dq Line Group Formats .
+.Pp
+.It  -d
+.It  --minimal
+Change the algorithm perhaps find a smaller set of changes. This makes
+.Xr diff
+slower (sometimes much slower).See Section
+.Dq diff Performance .
+.Pp
+.It  -D Va name
+.It  --ifdef= Va name
+Make merged
+.Li #ifdef
+format output, conditional on the preprocessor macro
+.Va name .
+See Section.Dq If-then-else .
+.Pp
+.It  -e
+.It  --ed
+Make output that is a valid
+.Xr ed
+script.See Section
+.Dq ed Scripts .
+.Pp
+.It  -E
+.It  --ignore-tab-expansion
+Ignore changes due to tab expansion.See Section
+.Dq White Space .
+.Pp
+.It  -f
+.It  --forward-ed
+Make output that looks vaguely like an
+.Xr ed
+script but has changes in the order they appear in the file.See Section
+.Dq Forward ed .
+.Pp
+.It  -F Va regexp
+.It  --show-function-line= Va regexp
+In context and unified format, for each hunk of differences, show some of
+the last preceding line that matches
+.Va regexp .
+See Section.Dq Specified Headings .
+.Pp
+.It  --from-file= Va file
+Compare
+.Va file
+to each operand;
+.Va file
+may be a directory.
+.Pp
+.It  --help
+Output a summary of usage and then exit.
+.Pp
+.It  --horizon-lines= Va lines
+Do not discard the last
+.Va lines
+lines of the common prefix and the first
+.Va lines
+lines of the common suffix.See Section
+.Dq diff Performance .
+.Pp
+.It  -i
+.It  --ignore-case
+Ignore changes in case; consider upper- and lower-case letters equivalent.See Section
+.Dq Case Folding .
+.Pp
+.It  -I Va regexp
+.It  --ignore-matching-lines= Va regexp
+Ignore changes that just insert or delete lines that match
+.Va regexp .
+See Section.Dq Specified Lines .
+.Pp
+.It  --ignore-file-name-case
+Ignore case when comparing file names during recursive comparison.See Section
+.Dq Comparing Directories .
+.Pp
+.It  -l
+.It  --paginate
+Pass the output through
+.Xr pr
+to paginate it.See Section
+.Dq Pagination .
+.Pp
+.It  --label= Va label
+Use
+.Va label
+instead of the file name in the context format (see Section
+.Dq Context Format )
+and unified format (see Section
+.Dq Unified Format )
+headers.See Section
+.Dq RCS .
+.Pp
+.It  --left-column
+Print only the left column of two common lines in side by side format.See Section
+.Dq Side by Side Format .
+.Pp
+.It  --line-format= Va format
+Use
+.Va format
+to output all input lines in if-then-else format.See Section
+.Dq Line Formats .
+.Pp
+.It  -n
+.It  --rcs
+Output RCS-format diffs; like
+.Op -f
+except that each command specifies the number of lines affected.See Section
+.Dq RCS .
+.Pp
+.It  -N
+.It  --new-file
+In directory comparison, if a file is found in only one directory, treat it
+as present but empty in the other directory.See Section
+.Dq Comparing Directories .
+.Pp
+.It  --new-group-format= Va format
+Use
+.Va format
+to output a group of lines taken from just the second file in if-then-else
+format.See Section
+.Dq Line Group Formats .
+.Pp
+.It  --new-line-format= Va format
+Use
+.Va format
+to output a line taken from just the second file in if-then-else format.See Section
+.Dq Line Formats .
+.Pp
+.It  --old-group-format= Va format
+Use
+.Va format
+to output a group of lines taken from just the first file in if-then-else
+format.See Section
+.Dq Line Group Formats .
+.Pp
+.It  --old-line-format= Va format
+Use
+.Va format
+to output a line taken from just the first file in if-then-else format.See Section
+.Dq Line Formats .
+.Pp
+.It  -p
+.It  --show-c-function
+Show which C function each change is in.See Section
+.Dq C Function Headings .
+.Pp
+.It  -q
+.It  --brief
+Report only whether the files differ, not the details of the differences.See Section
+.Dq Brief .
+.Pp
+.It  -r
+.It  --recursive
+When comparing directories, recursively compare any subdirectories found.See Section
+.Dq Comparing Directories .
+.Pp
+.It  -s
+.It  --report-identical-files
+Report when two files are the same.See Section
+.Dq Comparing Directories .
+.Pp
+.It  -S Va file
+.It  --starting-file= Va file
+When comparing directories, start with the file
+.Va file .
+This is used for resuming an aborted comparison.See Section
+.Dq Comparing Directories .
+.Pp
+.It  --speed-large-files
+Use heuristics to speed handling of large files that have numerous scattered
+small changes.See Section
+.Dq diff Performance .
+.Pp
+.It  --strip-trailing-cr
+Strip any trailing carriage return at the end of an input line.See Section
+.Dq Binary .
+.Pp
+.It  --suppress-common-lines
+Do not print common lines in side by side format.See Section
+.Dq Side by Side Format .
+.Pp
+.It  -t
+.It  --expand-tabs
+Expand tabs to spaces in the output, to preserve the alignment of tabs in
+the input files.See Section
+.Dq Tabs .
+.Pp
+.It  -T
+.It  --initial-tab
+Output a tab rather than a space before the text of a line in normal or context
+format. This causes the alignment of tabs in the line to look normal.See Section
+.Dq Tabs .
+.Pp
+.It  --tabsize= Va columns
+Assume that tab stops are set every
+.Va columns
+(default 8) print columns.See Section
+.Dq Tabs .
+.Pp
+.It  --to-file= Va file
+Compare each operand to
+.Va file
+;
+.Va file
+may be a directory.
+.Pp
+.It  -u
+Use the unified output format, showing three lines of context.See Section
+.Dq Unified Format .
+.Pp
+.It  --unchanged-group-format= Va format
+Use
+.Va format
+to output a group of common lines taken from both files in if-then-else format.See Section
+.Dq Line Group Formats .
+.Pp
+.It  --unchanged-line-format= Va format
+Use
+.Va format
+to output a line common to both files in if-then-else format.See Section
+.Dq Line Formats .
+.Pp
+.It  --unidirectional-new-file
+When comparing directories, if a file appears only in the second directory
+of the two, treat it as present but empty in the other.See Section
+.Dq Comparing Directories .
+.Pp
+.It  -U Va lines
+.It  --unified[= Va lines]
+Use the unified output format, showing
+.Va lines
+(an integer) lines of context, or three if
+.Va lines
+is not given.See Section
+.Dq Unified Format .
+For proper operation,
+.Xr patch
+typically needs at least two lines of context.
+.Pp
+On older systems,
+.Xr diff
+supports an obsolete option
+.Op - Va lines
+that has effect when combined with
+.Op -u .
+POSIX 1003.1-2001 (see Section
+.Dq Standards conformance )
+does not allow this; use
+.Op -U Va lines
+instead.
+.Pp
+.It  -v
+.It  --version
+Output version information and then exit.
+.Pp
+.It  -w
+.It  --ignore-all-space
+Ignore white space when comparing lines.See Section
+.Dq White Space .
+.Pp
+.It  -W Va columns
+.It  --width= Va columns
+Output at most
+.Va columns
+(default 130) print columns per line in side by side format.See Section
+.Dq Side by Side Format .
+.Pp
+.It  -x Va pattern
+.It  --exclude= Va pattern
+When comparing directories, ignore files and subdirectories whose basenames
+match
+.Va pattern .
+See Section.Dq Comparing Directories .
+.Pp
+.It  -X Va file
+.It  --exclude-from= Va file
+When comparing directories, ignore files and subdirectories whose basenames
+match any pattern contained in
+.Va file .
+See Section.Dq Comparing Directories .
+.Pp
+.It  -y
+.It  --side-by-side
+Use the side by side output format.See Section
+.Dq Side by Side Format .
+.El
+.Pp
+.Sh  Invoking Xr diff3
+The
+.Xr diff3
+command compares three files and outputs descriptions of their differences.
+Its arguments are as follows:
+.Pp
+.Bd -literal -offset indent
+diff3 options... mine older yours
+.Ed
+.Pp
+The files to compare are
+.Va mine ,
+.Va older ,
+and
+.Va yours .
+At most one of these three file names may be
+.Pa - ,
+which tells
+.Xr diff3
+to read the standard input for that file.
+.Pp
+An exit status of 0 means
+.Xr diff3
+was successful, 1 means some conflicts were found, and 2 means trouble.
+.Pp
+.Ss  Options to Xr diff3
+Below is a summary of all of the options that GNU
+.Xr diff3
+accepts. Multiple single letter options (unless they take an argument) can
+be combined into a single command line argument.
+.Pp
+.Bl -tag -width Ds
+.It  -a
+.It  --text
+Treat all files as text and compare them line-by-line, even if they do not
+appear to be text.See Section
+.Dq Binary .
+.Pp
+.It  -A
+.It  --show-all
+Incorporate all unmerged changes from
+.Va older
+to
+.Va yours
+into
+.Va mine ,
+surrounding conflicts with bracket lines.See Section
+.Dq Marking Conflicts .
+.Pp
+.It  --diff-program= Va program
+Use the compatible comparison program
+.Va program
+to compare files instead of
+.Xr diff .
+.Pp
+.It  -e
+.It  --ed
+Generate an
+.Xr ed
+script that incorporates all the changes from
+.Va older
+to
+.Va yours
+into
+.Va mine .
+See Section.Dq Which Changes .
+.Pp
+.It  -E
+.It  --show-overlap
+Like
+.Op -e ,
+except bracket lines from overlapping changes' first and third files.See Section
+.Dq Marking Conflicts .
+With
+.Op -E ,
+an overlapping change looks like this:
+.Pp
+.Bd -literal -offset indent
+<<<<<<< mine
+lines from mine
+=======
+lines from yours
+>>>>>>> yours
+.Ed
+.Pp
+.It  --help
+Output a summary of usage and then exit.
+.Pp
+.It  -i
+Generate
+.Li w
+and
+.Li q
+commands at the end of the
+.Xr ed
+script for System V compatibility. This option must be combined with one of
+the
+.Op -AeExX3
+options, and may not be combined with
+.Op -m .
+See Section.Dq Saving the Changed File .
+.Pp
+.It  --label= Va label
+Use the label
+.Va label
+for the brackets output by the
+.Op -A ,
+.Op -E
+and
+.Op -X
+options. This option may be given up to three times, one for each input file.
+The default labels are the names of the input files. Thus
+.Li diff3 --label X --label Y --label Z -m A B C
+acts like
+.Li diff3 -m A B C ,
+except that the output looks like it came from files named
+.Li X ,
+.Li Y
+and
+.Li Z
+rather than from files named
+.Li A ,
+.Li B
+and
+.Li C .
+See Section.Dq Marking Conflicts .
+.Pp
+.It  -m
+.It  --merge
+Apply the edit script to the first file and send the result to standard output.
+Unlike piping the output from
+.Xr diff3
+to
+.Xr ed ,
+this works even for binary files and incomplete lines.
+.Op -A
+is assumed if no edit script option is specified.See Section
+.Dq Bypassing ed .
+.Pp
+.It  --strip-trailing-cr
+Strip any trailing carriage return at the end of an input line.See Section
+.Dq Binary .
+.Pp
+.It  -T
+.It  --initial-tab
+Output a tab rather than two spaces before the text of a line in normal format.
+This causes the alignment of tabs in the line to look normal.See Section
+.Dq Tabs .
+.Pp
+.It  -v
+.It  --version
+Output version information and then exit.
+.Pp
+.It  -x
+.It  --overlap-only
+Like
+.Op -e ,
+except output only the overlapping changes.See Section
+.Dq Which Changes .
+.Pp
+.It  -X
+Like
+.Op -E ,
+except output only the overlapping changes. In other words, like
+.Op -x ,
+except bracket changes as in
+.Op -E .
+See Section.Dq Marking Conflicts .
+.Pp
+.It  -3
+.It  --easy-only
+Like
+.Op -e ,
+except output only the nonoverlapping changes.See Section
+.Dq Which Changes .
+.El
+.Pp
+.Sh  Invoking Xr patch
+Normally
+.Xr patch
+is invoked like this:
+.Pp
+.Bd -literal -offset indent
+patch <patchfile
+.Ed
+.Pp
+The full format for invoking
+.Xr patch
+is:
+.Pp
+.Bd -literal -offset indent
+patch options... [origfile [patchfile]]
+.Ed
+.Pp
+You can also specify where to read the patch from with the
+.Op -i Va patchfile
+or
+.Op --input= Va patchfile
+option. If you do not specify
+.Va patchfile ,
+or if
+.Va patchfile
+is
+.Pa - ,
+.Xr patch
+reads the patch (that is, the
+.Xr diff
+output) from the standard input.
+.Pp
+If you do not specify an input file on the command line,
+.Xr patch
+tries to intuit from the
+.Em leading text
+(any text in the patch that comes before the
+.Xr diff
+output) which file to edit.See Section
+.Dq Multiple Patches .
+.Pp
+By default,
+.Xr patch
+replaces the original input file with the patched version, possibly after
+renaming the original file into a backup file (see Section
+.Dq Backup Names ,
+for a description of how
+.Xr patch
+names backup files). You can also specify where to put the output with the
+.Op -o Va file
+or
+.Op --output= Va file
+option; however, do not use this option if
+.Va file
+is one of the input files.
+.Pp
+.Ss  Options to Xr patch
+Here is a summary of all of the options that GNU
+.Xr patch
+accepts.See Section
+.Dq patch and Tradition ,
+for which of these options are safe to use in older versions of
+.Xr patch .
+.Pp
+Multiple single-letter options that do not take an argument can be combined
+into a single command line argument with only one dash.
+.Pp
+.Bl -tag -width Ds
+.It  -b
+.It  --backup
+Back up the original contents of each file, even if backups would normally
+not be made.See Section
+.Dq Backups .
+.Pp
+.It  -B Va prefix
+.It  --prefix= Va prefix
+Prepend
+.Va prefix
+to backup file names.See Section
+.Dq Backup Names .
+.Pp
+.It  --backup-if-mismatch
+Back up the original contents of each file if the patch does not exactly match
+the file. This is the default behavior when not conforming to POSIX.See Section
+.Dq Backups .
+.Pp
+.It  --binary
+Read and write all files in binary mode, except for standard output and
+.Pa /dev/tty .
+This option has no effect on POSIX-conforming systems like GNU/Linux. On systems
+where this option makes a difference, the patch should be generated by
+.Li diff -a --binary .
+See Section.Dq Binary .
+.Pp
+.It  -c
+.It  --context
+Interpret the patch file as a context diff.See Section
+.Dq patch Input .
+.Pp
+.It  -d Va directory
+.It  --directory= Va directory
+Make directory
+.Va directory
+the current directory for interpreting both file names in the patch file,
+and file names given as arguments to other options.See Section
+.Dq patch Directories .
+.Pp
+.It  -D Va name
+.It  --ifdef= Va name
+Make merged if-then-else output using
+.Va name .
+See Section.Dq If-then-else .
+.Pp
+.It  --dry-run
+Print the results of applying the patches without actually changing any files.See Section
+.Dq Dry Runs .
+.Pp
+.It  -e
+.It  --ed
+Interpret the patch file as an
+.Xr ed
+script.See Section
+.Dq patch Input .
+.Pp
+.It  -E
+.It  --remove-empty-files
+Remove output files that are empty after the patches have been applied.See Section
+.Dq Creating and Removing .
+.Pp
+.It  -f
+.It  --force
+Assume that the user knows exactly what he or she is doing, and do not ask
+any questions.See Section
+.Dq patch Messages .
+.Pp
+.It  -F Va lines
+.It  --fuzz= Va lines
+Set the maximum fuzz factor to
+.Va lines .
+See Section.Dq Inexact .
+.Pp
+.It  -g Va num
+.It  --get= Va num
+If
+.Va num
+is positive, get input files from a revision control system as necessary;
+if zero, do not get the files; if negative, ask the user whether to get the
+files.See Section
+.Dq Revision Control .
+.Pp
+.It  --help
+Output a summary of usage and then exit.
+.Pp
+.It  -i Va patchfile
+.It  --input= Va patchfile
+Read the patch from
+.Va patchfile
+rather than from standard input.See Section
+.Dq patch Options .
+.Pp
+.It  -l
+.It  --ignore-white-space
+Let any sequence of blanks (spaces or tabs) in the patch file match any sequence
+of blanks in the input file.See Section
+.Dq Changed White Space .
+.Pp
+.It  -n
+.It  --normal
+Interpret the patch file as a normal diff.See Section
+.Dq patch Input .
+.Pp
+.It  -N
+.It  --forward
+Ignore patches that
+.Xr patch
+thinks are reversed or already applied. See also
+.Op -R .
+See Section.Dq Reversed Patches .
+.Pp
+.It  --no-backup-if-mismatch
+Do not back up the original contents of files. This is the default behavior
+when conforming to POSIX.See Section
+.Dq Backups .
+.Pp
+.It  -o Va file
+.It  --output= Va file
+Use
+.Va file
+as the output file name.See Section
+.Dq patch Options .
+.Pp
+.It  -p Va number
+.It  --strip= Va number
+Set the file name strip count to
+.Va number .
+See Section.Dq patch Directories .
+.Pp
+.It  --posix
+Conform to POSIX, as if the
+.Ev POSIXLY_CORRECT
+environment variable had been set.See Section
+.Dq patch and POSIX .
+.Pp
+.It  --quoting-style= Va word
+Use style
+.Va word
+to quote names in diagnostics, as if the
+.Ev QUOTING_STYLE
+environment variable had been set to
+.Va word .
+See Section.Dq patch Quoting Style .
+.Pp
+.It  -r Va reject-file
+.It  --reject-file= Va reject-file
+Use
+.Va reject-file
+as the reject file name.See Section
+.Dq Reject Names .
+.Pp
+.It  -R
+.It  --reverse
+Assume that this patch was created with the old and new files swapped.See Section
+.Dq Reversed Patches .
+.Pp
+.It  -s
+.It  --quiet
+.It  --silent
+Work silently unless an error occurs.See Section
+.Dq patch Messages .
+.Pp
+.It  -t
+.It  --batch
+Do not ask any questions.See Section
+.Dq patch Messages .
+.Pp
+.It  -T
+.It  --set-time
+Set the modification and access times of patched files from time stamps given
+in context diff headers, assuming that the context diff headers use local
+time.See Section
+.Dq Patching Time Stamps .
+.Pp
+.It  -u
+.It  --unified
+Interpret the patch file as a unified diff.See Section
+.Dq patch Input .
+.Pp
+.It  -v
+.It  --version
+Output version information and then exit.
+.Pp
+.It  -V Va backup-style
+.It  --version=control= Va backup-style
+Select the naming convention for backup file names.See Section
+.Dq Backup Names .
+.Pp
+.It  --verbose
+Print more diagnostics than usual.See Section
+.Dq patch Messages .
+.Pp
+.It  -x Va number
+.It  --debug= Va number
+Set internal debugging flags. Of interest only to
+.Xr patch
+patchers.
+.Pp
+.It  -Y Va prefix
+.It  --basename-prefix= Va prefix
+Prepend
+.Va prefix
+to base names of backup files.See Section
+.Dq Backup Names .
+.Pp
+.It  -z Va suffix
+.It  --suffix= Va suffix
+Use
+.Va suffix
+as the backup extension instead of
+.Li .orig
+or
+.Li ~ .
+See Section.Dq Backup Names .
+.Pp
+.It  -Z
+.It  --set-utc
+Set the modification and access times of patched files from time stamps given
+in context diff headers, assuming that the context diff headers use UTC.See Section
+.Dq Patching Time Stamps .
+.Pp
+.El
+.Sh  Invoking Xr sdiff
+The
+.Xr sdiff
+command merges two files and interactively outputs the results. Its arguments
+are as follows:
+.Pp
+.Bd -literal -offset indent
+sdiff -o outfile options... from-file to-file
+.Ed
+.Pp
+This merges
+.Va from-file
+with
+.Va to-file ,
+with output to
+.Va outfile .
+If
+.Va from-file
+is a directory and
+.Va to-file
+is not,
+.Xr sdiff
+compares the file in
+.Va from-file
+whose file name is that of
+.Va to-file ,
+and vice versa.
+.Va from-file
+and
+.Va to-file
+may not both be directories.
+.Pp
+.Xr sdiff
+options begin with
+.Li - ,
+so normally
+.Va from-file
+and
+.Va to-file
+may not begin with
+.Li - .
+However,
+.Op --
+as an argument by itself treats the remaining arguments as file names even
+if they begin with
+.Li - .
+You may not use
+.Pa -
+as an input file.
+.Pp
+.Xr sdiff
+without
+.Op -o
+(or
+.Op --output )
+produces a side-by-side difference. This usage is obsolete; use the
+.Op -y
+or
+.Op --side-by-side
+option of
+.Xr diff
+instead.
+.Pp
+An exit status of 0 means no differences were found, 1 means some differences
+were found, and 2 means trouble.
+.Pp
+.Ss  Options to Xr sdiff
+Below is a summary of all of the options that GNU
+.Xr sdiff
+accepts. Each option has two equivalent names, one of which is a single letter
+preceded by
+.Li - ,
+and the other of which is a long name preceded by
+.Li -- .
+Multiple single letter options (unless they take an argument) can be combined
+into a single command line argument. Long named options can be abbreviated
+to any unique prefix of their name.
+.Pp
+.Bl -tag -width Ds
+.It  -a
+.It  --text
+Treat all files as text and compare them line-by-line, even if they do not
+appear to be text.See Section
+.Dq Binary .
+.Pp
+.It  -b
+.It  --ignore-space-change
+Ignore changes in amount of white space.See Section
+.Dq White Space .
+.Pp
+.It  -B
+.It  --ignore-blank-lines
+Ignore changes that just insert or delete blank lines.See Section
+.Dq Blank Lines .
+.Pp
+.It  -d
+.It  --minimal
+Change the algorithm to perhaps find a smaller set of changes. This makes
+.Xr sdiff
+slower (sometimes much slower).See Section
+.Dq diff Performance .
+.Pp
+.It  --diff-program= Va program
+Use the compatible comparison program
+.Va program
+to compare files instead of
+.Xr diff .
+.Pp
+.It  -E
+.It  --ignore-tab-expansion
+Ignore changes due to tab expansion.See Section
+.Dq White Space .
+.Pp
+.It  --help
+Output a summary of usage and then exit.
+.Pp
+.It  -i
+.It  --ignore-case
+Ignore changes in case; consider upper- and lower-case to be the same.See Section
+.Dq Case Folding .
+.Pp
+.It  -I Va regexp
+.It  --ignore-matching-lines= Va regexp
+Ignore changes that just insert or delete lines that match
+.Va regexp .
+See Section.Dq Specified Lines .
+.Pp
+.It  -l
+.It  --left-column
+Print only the left column of two common lines.See Section
+.Dq Side by Side Format .
+.Pp
+.It  -o Va file
+.It  --output= Va file
+Put merged output into
+.Va file .
+This option is required for merging.
+.Pp
+.It  -s
+.It  --suppress-common-lines
+Do not print common lines.See Section
+.Dq Side by Side Format .
+.Pp
+.It  --speed-large-files
+Use heuristics to speed handling of large files that have numerous scattered
+small changes.See Section
+.Dq diff Performance .
+.Pp
+.It  --strip-trailing-cr
+Strip any trailing carriage return at the end of an input line.See Section
+.Dq Binary .
+.Pp
+.It  -t
+.It  --expand-tabs
+Expand tabs to spaces in the output, to preserve the alignment of tabs in
+the input files.See Section
+.Dq Tabs .
+.Pp
+.It  --tabsize= Va columns
+Assume that tab stops are set every
+.Va columns
+(default 8) print columns.See Section
+.Dq Tabs .
+.Pp
+.It  -v
+.It  --version
+Output version information and then exit.
+.Pp
+.It  -w Va columns
+.It  --width= Va columns
+Output at most
+.Va columns
+(default 130) print columns per line.See Section
+.Dq Side by Side Format .
+Note that for historical reasons, this option is
+.Op -W
+in
+.Xr diff ,
+.Op -w
+in
+.Xr sdiff .
+.Pp
+.It  -W
+.It  --ignore-all-space
+Ignore white space when comparing lines.See Section
+.Dq White Space .
+Note that for historical reasons, this option is
+.Op -w
+in
+.Xr diff ,
+.Op -W
+in
+.Xr sdiff .
+.El
+.Pp
+.Sh  Standards conformance
+In a few cases, the GNU utilities' default behavior is incompatible with the
+POSIX standard. To suppress these incompatibilities, define the
+.Ev POSIXLY_CORRECT
+environment variable. Unless you are checking for POSIX conformance, you probably
+do not need to define
+.Ev POSIXLY_CORRECT .
+.Pp
+Normally options and operands can appear in any order, and programs act as
+if all the options appear before any operands. For example,
+.Li diff lao tzu -C 2
+acts like
+.Li diff -C 2 lao tzu ,
+since
+.Li 2
+is an option-argument of
+.Op -C .
+However, if the
+.Ev POSIXLY_CORRECT
+environment variable is set, options must appear before operands, unless otherwise
+specified for a particular command.
+.Pp
+Newer versions of POSIX are occasionally incompatible with older versions.
+For example, older versions of POSIX allowed the command
+.Li diff -c -10
+to have the same meaning as
+.Li diff -C 10 ,
+but POSIX 1003.1-2001
+.Li diff
+no longer allows digit-string options like
+.Op -10 .
+.Pp
+The GNU utilities normally conform to the version of POSIX that is standard
+for your system. To cause them to conform to a different version of POSIX,
+define the
+.Ev _POSIX2_VERSION
+environment variable to a value of the form
+.Va yyyymm
+specifying the year and month the standard was adopted. Two values are currently
+supported for
+.Ev _POSIX2_VERSION :
+.Li 199209
+stands for POSIX 1003.2-1992, and
+.Li 200112
+stands for POSIX 1003.1-2001. For example, if you are running older software
+that assumes an older version of POSIX and uses
+.Li diff -c -10 ,
+you can work around the compatibility problems by setting
+.Li _POSIX2_VERSION=199209
+in your environment.
+.Pp
+.Sh  Future Projects
+Here are some ideas for improving GNU
+.Xr diff
+and
+.Xr patch .
+The GNU project has identified some improvements as potential programming
+projects for volunteers. You can also help by reporting any bugs that you
+find.
+.Pp
+If you are a programmer and would like to contribute something to the GNU
+project, please consider volunteering for one of these projects. If you are
+seriously contemplating work, please write to
+.Mt gvc@gnu.org
+to coordinate with other volunteers.
+.Pp
+.Ss  Suggested Projects for Improving GNU Xr diff and Xr patch
+One should be able to use GNU
+.Xr diff
+to generate a patch from any pair of directory trees, and given the patch
+and a copy of one such tree, use
+.Xr patch
+to generate a faithful copy of the other. Unfortunately, some changes to directory
+trees cannot be expressed using current patch formats; also,
+.Xr patch
+does not handle some of the existing formats. These shortcomings motivate
+the following suggested projects.
+.Pp
+.Em  Handling Multibyte and Varying-Width Characters
+.Pp
+.Xr diff ,
+.Xr diff3
+and
+.Xr sdiff
+treat each line of input as a string of unibyte characters. This can mishandle
+multibyte characters in some cases. For example, when asked to ignore spaces,
+.Xr diff
+does not properly ignore a multibyte space character.
+.Pp
+Also,
+.Xr diff
+currently assumes that each byte is one column wide, and this assumption is
+incorrect in some locales, e.g., locales that use UTF-8 encoding. This causes
+problems with the
+.Op -y
+or
+.Op --side-by-side
+option of
+.Xr diff .
+.Pp
+These problems need to be fixed without unduly affecting the performance of
+the utilities in unibyte environments.
+.Pp
+The IBM GNU/Linux Technology Center Internationalization Team has proposed
+.Lk http://oss.software.ibm.com/developer/opensource/linux/patches/i18n/diffutils-2.7.2-i18n-0.1.patch.gz .
+Unfortunately, these patches are incomplete and are to an older version of
+.Xr diff ,
+so more work needs to be done in this area.
+.Pp
+.Em  Handling Changes to the Directory Structure
+.Pp
+.Xr diff
+and
+.Xr patch
+do not handle some changes to directory structure. For example, suppose one
+directory tree contains a directory named
+.Li D
+with some subsidiary files, and another contains a file with the same name
+.Li D .
+.Li diff -r
+does not output enough information for
+.Xr patch
+to transform the directory subtree into the file.
+.Pp
+There should be a way to specify that a file has been removed without having
+to include its entire contents in the patch file. There should also be a way
+to tell
+.Xr patch
+that a file was renamed, even if there is no way for
+.Xr diff
+to generate such information. There should be a way to tell
+.Xr patch
+that a file's time stamp has changed, even if its contents have not changed.
+.Pp
+These problems can be fixed by extending the
+.Xr diff
+output format to represent changes in directory structure, and extending
+.Xr patch
+to understand these extensions.
+.Pp
+.Em  Files that are Neither Directories Nor Regular Files
+.Pp
+Some files are neither directories nor regular files: they are unusual files
+like symbolic links, device special files, named pipes, and sockets. Currently,
+.Xr diff
+treats symbolic links as if they were the pointed-to files, except that a
+recursive
+.Xr diff
+reports an error if it detects infinite loops of symbolic links (e.g., symbolic
+links to
+.Pa .. ) .
+.Xr diff
+treats other special files like regular files if they are specified at the
+top level, but simply reports their presence when comparing directories. This
+means that
+.Xr patch
+cannot represent changes to such files. For example, if you change which file
+a symbolic link points to,
+.Xr diff
+outputs the difference between the two files, instead of the change to the
+symbolic link.
+.Pp
+.Xr diff
+should optionally report changes to special files specially, and
+.Xr patch
+should be extended to understand these extensions.
+.Pp
+.Em  File Names that Contain Unusual Characters
+.Pp
+When a file name contains an unusual character like a newline or white space,
+.Li diff -r
+generates a patch that
+.Xr patch
+cannot parse. The problem is with format of
+.Xr diff
+output, not just with
+.Xr patch ,
+because with odd enough file names one can cause
+.Xr diff
+to generate a patch that is syntactically correct but patches the wrong files.
+The format of
+.Xr diff
+output should be extended to handle all possible file names.
+.Pp
+.Em  Outputting Diffs in Time Stamp Order
+.Pp
+Applying
+.Xr patch
+to a multiple-file diff can result in files whose time stamps are out of order.
+GNU
+.Xr patch
+has options to restore the time stamps of the updated files (see Section
+.Dq Patching Time Stamps ) ,
+but sometimes it is useful to generate a patch that works even if the recipient
+does not have GNU patch, or does not use these options. One way to do this
+would be to implement a
+.Xr diff
+option to output diffs in time stamp order.
+.Pp
+.Em  Ignoring Certain Changes
+.Pp
+It would be nice to have a feature for specifying two strings, one in
+.Va from-file
+and one in
+.Va to-file ,
+which should be considered to match. Thus, if the two strings are
+.Li foo
+and
+.Li bar ,
+then if two lines differ only in that
+.Li foo
+in file 1 corresponds to
+.Li bar
+in file 2, the lines are treated as identical.
+.Pp
+It is not clear how general this feature can or should be, or what syntax
+should be used for it.
+.Pp
+A partial substitute is to filter one or both files before comparing, e.g.:
+.Pp
+.Bd -literal -offset indent
+sed 's/foo/bar/g' file1 | diff - file2
+.Ed
+.Pp
+However, this outputs the filtered text, not the original.
+.Pp
+.Em  Improving Performance
+.Pp
+When comparing two large directory structures, one of which was originally
+copied from the other with time stamps preserved (e.g., with
+.Li cp -pR ) ,
+it would greatly improve performance if an option told
+.Xr diff
+to assume that two files with the same size and time stamps have the same
+content.See Section
+.Dq diff Performance .
+.Pp
+.Ss  Reporting Bugs
+If you think you have found a bug in GNU
+.Xr cmp ,
+.Xr diff ,
+.Xr diff3 ,
+or
+.Xr sdiff ,
+please report it by electronic mail to the
+.Lk http://mail.gnu.org/mailman/listinfo/bug-gnu-utils
+.Mt bug-gnu-utils@gnu.org .
+Please send bug reports for GNU
+.Xr patch
+to
+.Mt bug-patch@gnu.org .
+Send as precise a description of the problem as you can, including the output
+of the
+.Op --version
+option and sample input files that produce the bug, if applicable. If you
+have a nontrivial fix for the bug, please send it as well. If you have a patch,
+please send it too. It may simplify the maintainer's job if the patch is relative
+to a recent test release, which you can find in the directory
+.Lk ftp://alpha.gnu.org/gnu/diffutils/ .
+.Pp
+.Sh  Copying This Manual
+.Ss  GNU Free Documentation License
+.Bd -filled -offset indent
+Copyright \(co 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place,
+Suite 330, Boston, MA 02111-1307, USA
+.Pp
+Everyone is permitted to copy and distribute verbatim copies of this license
+document, but changing it is not allowed.
+.Ed
+.Pp
+.Bl -enum
+.It
+PREAMBLE
+.Pp
+The purpose of this License is to make a manual, textbook, or other functional
+and useful document
+.Em free
+in the sense of freedom: to assure everyone the effective freedom to copy
+and redistribute it, with or without modifying it, either commercially or
+noncommercially. Secondarily, this License preserves for the author and publisher
+a way to get credit for their work, while not being considered responsible
+for modifications made by others.
+.Pp
+This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the
+document must themselves be free in the same sense. It complements the GNU
+General Public License, which is a copyleft license designed for free software.
+.Pp
+We have designed this License in order to use it for manuals for free software,
+because free software needs free documentation: a free program should come
+with manuals providing the same freedoms that the software does. But this
+License is not limited to software manuals; it can be used for any textual
+work, regardless of subject matter or whether it is published as a printed
+book. We recommend this License principally for works whose purpose is instruction
+or reference.
+.Pp
+.It
+APPLICABILITY AND DEFINITIONS
+.Pp
+This License applies to any manual or other work, in any medium, that contains
+a notice placed by the copyright holder saying it can be distributed under
+the terms of this License. Such a notice grants a world-wide, royalty-free
+license, unlimited in duration, to use that work under the conditions stated
+herein. The \(lqDocument\(rq, below, refers to any such manual or work. Any member
+of the public is a licensee, and is addressed as \(lqyou\(rq. You accept the license
+if you copy, modify or distribute the work in a way requiring permission under
+copyright law.
+.Pp
+A \(lqModified Version\(rq of the Document means any work containing the Document
+or a portion of it, either copied verbatim, or with modifications and/or translated
+into another language.
+.Pp
+A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document
+that deals exclusively with the relationship of the publishers or authors
+of the Document to the Document's overall subject (or to related matters)
+and contains nothing that could fall directly within that overall subject.
+(Thus, if the Document is in part a textbook of mathematics, a Secondary Section
+may not explain any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal, commercial,
+philosophical, ethical or political position regarding them.
+.Pp
+The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated,
+as being those of Invariant Sections, in the notice that says that the Document
+is released under this License. If a section does not fit the above definition
+of Secondary then it is not allowed to be designated as Invariant. The Document
+may contain zero Invariant Sections. If the Document does not identify any
+Invariant Sections then there are none.
+.Pp
+The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover
+Texts or Back-Cover Texts, in the notice that says that the Document is released
+under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover
+Text may be at most 25 words.
+.Pp
+A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented
+in a format whose specification is available to the general public, that is
+suitable for revising the document straightforwardly with generic text editors
+or (for images composed of pixels) generic paint programs or (for drawings)
+some widely available drawing editor, and that is suitable for input to text
+formatters or for automatic translation to a variety of formats suitable for
+input to text formatters. A copy made in an otherwise Transparent file format
+whose markup, or absence of markup, has been arranged to thwart or discourage
+subsequent modification by readers is not Transparent. An image format is
+not Transparent if used for any substantial amount of text. A copy that is
+not \(lqTransparent\(rq is called \(lqOpaque\(rq.
+.Pp
+Examples of suitable formats for Transparent copies include plain ascii without
+markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly
+available DTD, and standard-conforming simple HTML, PostScript or PDF designed
+for human modification. Examples of transparent image formats include PNG,
+XCF and JPG. Opaque formats include proprietary formats that can be read and
+edited only by proprietary word processors, SGML or XML for which the DTD
+and/or processing tools are not generally available, and the machine-generated
+HTML, PostScript or PDF produced by some word processors for output purposes
+only.
+.Pp
+The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such
+following pages as are needed to hold, legibly, the material this License
+requires to appear in the title page. For works in formats which do not have
+any title page as such, \(lqTitle Page\(rq means the text near the most prominent
+appearance of the work's title, preceding the beginning of the body of the
+text.
+.Pp
+A section \(lqEntitled XYZ\(rq means a named subunit of the Document whose title either
+is precisely XYZ or contains XYZ in parentheses following text that translates
+XYZ in another language. (Here XYZ stands for a specific section name mentioned
+below, such as \(lqAcknowledgements\(rq, \(lqDedications\(rq, \(lqEndorsements\(rq, or \(lqHistory\(rq.) To
+\(lqPreserve the Title\(rq of such a section when you modify the Document means that
+it remains a section \(lqEntitled XYZ\(rq according to this definition.
+.Pp
+The Document may include Warranty Disclaimers next to the notice which states
+that this License applies to the Document. These Warranty Disclaimers are
+considered to be included by reference in this License, but only as regards
+disclaiming warranties: any other implication that these Warranty Disclaimers
+may have is void and has no effect on the meaning of this License.
+.Pp
+.It
+VERBATIM COPYING
+.Pp
+You may copy and distribute the Document in any medium, either commercially
+or noncommercially, provided that this License, the copyright notices, and
+the license notice saying this License applies to the Document are reproduced
+in all copies, and that you add no other conditions whatsoever to those of
+this License. You may not use technical measures to obstruct or control the
+reading or further copying of the copies you make or distribute. However,
+you may accept compensation in exchange for copies. If you distribute a large
+enough number of copies you must also follow the conditions in section 3.
+.Pp
+You may also lend copies, under the same conditions stated above, and you
+may publicly display copies.
+.Pp
+.It
+COPYING IN QUANTITY
+.Pp
+If you publish printed copies (or copies in media that commonly have printed
+covers) of the Document, numbering more than 100, and the Document's license
+notice requires Cover Texts, you must enclose the copies in covers that carry,
+clearly and legibly, all these Cover Texts: Front-Cover Texts on the front
+cover, and Back-Cover Texts on the back cover. Both covers must also clearly
+and legibly identify you as the publisher of these copies. The front cover
+must present the full title with all words of the title equally prominent
+and visible. You may add other material on the covers in addition. Copying
+with changes limited to the covers, as long as they preserve the title of
+the Document and satisfy these conditions, can be treated as verbatim copying
+in other respects.
+.Pp
+If the required texts for either cover are too voluminous to fit legibly,
+you should put the first ones listed (as many as fit reasonably) on the actual
+cover, and continue the rest onto adjacent pages.
+.Pp
+If you publish or distribute Opaque copies of the Document numbering more
+than 100, you must either include a machine-readable Transparent copy along
+with each Opaque copy, or state in or with each Opaque copy a computer-network
+location from which the general network-using public has access to download
+using public-standard network protocols a complete Transparent copy of the
+Document, free of added material. If you use the latter option, you must take
+reasonably prudent steps, when you begin distribution of Opaque copies in
+quantity, to ensure that this Transparent copy will remain thus accessible
+at the stated location until at least one year after the last time you distribute
+an Opaque copy (directly or through your agents or retailers) of that edition
+to the public.
+.Pp
+It is requested, but not required, that you contact the authors of the Document
+well before redistributing any large number of copies, to give them a chance
+to provide you with an updated version of the Document.
+.Pp
+.It
+MODIFICATIONS
+.Pp
+You may copy and distribute a Modified Version of the Document under the conditions
+of sections 2 and 3 above, provided that you release the Modified Version
+under precisely this License, with the Modified Version filling the role of
+the Document, thus licensing distribution and modification of the Modified
+Version to whoever possesses a copy of it. In addition, you must do these
+things in the Modified Version:
+.Pp
+.Bl -enum
+.It
+Use in the Title Page (and on the covers, if any) a title distinct from that
+of the Document, and from those of previous versions (which should, if there
+were any, be listed in the History section of the Document). You may use the
+same title as a previous version if the original publisher of that version
+gives permission.
+.Pp
+.It
+List on the Title Page, as authors, one or more persons or entities responsible
+for authorship of the modifications in the Modified Version, together with
+at least five of the principal authors of the Document (all of its principal
+authors, if it has fewer than five), unless they release you from this requirement.
+.Pp
+.It
+State on the Title page the name of the publisher of the Modified Version,
+as the publisher.
+.Pp
+.It
+Preserve all the copyright notices of the Document.
+.Pp
+.It
+Add an appropriate copyright notice for your modifications adjacent to the
+other copyright notices.
+.Pp
+.It
+Include, immediately after the copyright notices, a license notice giving
+the public permission to use the Modified Version under the terms of this
+License, in the form shown in the Addendum below.
+.Pp
+.It
+Preserve in that license notice the full lists of Invariant Sections and required
+Cover Texts given in the Document's license notice.
+.Pp
+.It
+Include an unaltered copy of this License.
+.Pp
+.It
+Preserve the section Entitled \(lqHistory\(rq, Preserve its Title, and add to it an
+item stating at least the title, year, new authors, and publisher of the Modified
+Version as given on the Title Page. If there is no section Entitled \(lqHistory\(rq
+in the Document, create one stating the title, year, authors, and publisher
+of the Document as given on its Title Page, then add an item describing the
+Modified Version as stated in the previous sentence.
+.Pp
+.It
+Preserve the network location, if any, given in the Document for public access
+to a Transparent copy of the Document, and likewise the network locations
+given in the Document for previous versions it was based on. These may be
+placed in the \(lqHistory\(rq section. You may omit a network location for a work
+that was published at least four years before the Document itself, or if the
+original publisher of the version it refers to gives permission.
+.Pp
+.It
+For any section Entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, Preserve the Title
+of the section, and preserve in the section all the substance and tone of
+each of the contributor acknowledgements and/or dedications given therein.
+.Pp
+.It
+Preserve all the Invariant Sections of the Document, unaltered in their text
+and in their titles. Section numbers or the equivalent are not considered
+part of the section titles.
+.Pp
+.It
+Delete any section Entitled \(lqEndorsements\(rq. Such a section may not be included
+in the Modified Version.
+.Pp
+.It
+Do not retitle any existing section to be Entitled \(lqEndorsements\(rq or to conflict
+in title with any Invariant Section.
+.Pp
+.It
+Preserve any Warranty Disclaimers.
+.El
+.Pp
+If the Modified Version includes new front-matter sections or appendices that
+qualify as Secondary Sections and contain no material copied from the Document,
+you may at your option designate some or all of these sections as invariant.
+To do this, add their titles to the list of Invariant Sections in the Modified
+Version's license notice. These titles must be distinct from any other section
+titles.
+.Pp
+You may add a section Entitled \(lqEndorsements\(rq, provided it contains nothing
+but endorsements of your Modified Version by various parties---for example,
+statements of peer review or that the text has been approved by an organization
+as the authoritative definition of a standard.
+.Pp
+You may add a passage of up to five words as a Front-Cover Text, and a passage
+of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts
+in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover
+Text may be added by (or through arrangements made by) any one entity. If
+the Document already includes a cover text for the same cover, previously
+added by you or by arrangement made by the same entity you are acting on behalf
+of, you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+.Pp
+The author(s) and publisher(s) of the Document do not by this License give
+permission to use their names for publicity for or to assert or imply endorsement
+of any Modified Version.
+.Pp
+.It
+COMBINING DOCUMENTS
+.Pp
+You may combine the Document with other documents released under this License,
+under the terms defined in section 4 above for modified versions, provided
+that you include in the combination all of the Invariant Sections of all of
+the original documents, unmodified, and list them all as Invariant Sections
+of your combined work in its license notice, and that you preserve all their
+Warranty Disclaimers.
+.Pp
+The combined work need only contain one copy of this License, and multiple
+identical Invariant Sections may be replaced with a single copy. If there
+are multiple Invariant Sections with the same name but different contents,
+make the title of each such section unique by adding at the end of it, in
+parentheses, the name of the original author or publisher of that section
+if known, or else a unique number. Make the same adjustment to the section
+titles in the list of Invariant Sections in the license notice of the combined
+work.
+.Pp
+In the combination, you must combine any sections Entitled \(lqHistory\(rq in the
+various original documents, forming one section Entitled \(lqHistory\(rq; likewise
+combine any sections Entitled \(lqAcknowledgements\(rq, and any sections Entitled
+\(lqDedications\(rq. You must delete all sections Entitled \(lqEndorsements.\(rq
+.Pp
+.It
+COLLECTIONS OF DOCUMENTS
+.Pp
+You may make a collection consisting of the Document and other documents released
+under this License, and replace the individual copies of this License in the
+various documents with a single copy that is included in the collection, provided
+that you follow the rules of this License for verbatim copying of each of
+the documents in all other respects.
+.Pp
+You may extract a single document from such a collection, and distribute it
+individually under this License, provided you insert a copy of this License
+into the extracted document, and follow this License in all other respects
+regarding verbatim copying of that document.
+.Pp
+.It
+AGGREGATION WITH INDEPENDENT WORKS
+.Pp
+A compilation of the Document or its derivatives with other separate and independent
+documents or works, in or on a volume of a storage or distribution medium,
+is called an \(lqaggregate\(rq if the copyright resulting from the compilation is
+not used to limit the legal rights of the compilation's users beyond what
+the individual works permit. When the Document is included in an aggregate,
+this License does not apply to the other works in the aggregate which are
+not themselves derivative works of the Document.
+.Pp
+If the Cover Text requirement of section 3 is applicable to these copies of
+the Document, then if the Document is less than one half of the entire aggregate,
+the Document's Cover Texts may be placed on covers that bracket the Document
+within the aggregate, or the electronic equivalent of covers if the Document
+is in electronic form. Otherwise they must appear on printed covers that bracket
+the whole aggregate.
+.Pp
+.It
+TRANSLATION
+.Pp
+Translation is considered a kind of modification, so you may distribute translations
+of the Document under the terms of section 4. Replacing Invariant Sections
+with translations requires special permission from their copyright holders,
+but you may include translations of some or all Invariant Sections in addition
+to the original versions of these Invariant Sections. You may include a translation
+of this License, and all the license notices in the Document, and any Warranty
+Disclaimers, provided that you also include the original English version of
+this License and the original versions of those notices and disclaimers. In
+case of a disagreement between the translation and the original version of
+this License or a notice or disclaimer, the original version will prevail.
+.Pp
+If a section in the Document is Entitled \(lqAcknowledgements\(rq, \(lqDedications\(rq, or
+\(lqHistory\(rq, the requirement (section 4) to Preserve its Title (section 1) will
+typically require changing the actual title.
+.Pp
+.It
+TERMINATION
+.Pp
+You may not copy, modify, sublicense, or distribute the Document except as
+expressly provided for under this License. Any other attempt to copy, modify,
+sublicense or distribute the Document is void, and will automatically terminate
+your rights under this License. However, parties who have received copies,
+or rights, from you under this License will not have their licenses terminated
+so long as such parties remain in full compliance.
+.Pp
+.It
+FUTURE REVISIONS OF THIS LICENSE
+.Pp
+The Free Software Foundation may publish new, revised versions of the GNU
+Free Documentation License from time to time. Such new versions will be similar
+in spirit to the present version, but may differ in detail to address new
+problems or concerns. See
+.Lk http://www.gnu.org/copyleft/ .
+.Pp
+Each version of the License is given a distinguishing version number. If the
+Document specifies that a particular numbered version of this License \(lqor any
+later version\(rq applies to it, you have the option of following the terms and
+conditions either of that specified version or of any later version that has
+been published (not as a draft) by the Free Software Foundation. If the Document
+does not specify a version number of this License, you may choose any version
+ever published (not as a draft) by the Free Software Foundation.
+.El
+.Pp
+.Em  ADDENDUM: How to use this License for your documents
+.Pp
+To use this License in a document you have written, include a copy of the
+License in the document and put the following copyright and license notices
+just after the title page:
+.Pp
+.Bd -literal -offset indent
+
+  Copyright (C)  year  your name.
+  Permission is granted to copy, distribute and/or modify this document
+  under the terms of the GNU Free Documentation License, Version 1.2
+  or any later version published by the Free Software Foundation;
+  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+  Texts.  A copy of the license is included in the section entitled \(lqGNU
+  Free Documentation License\(rq.
+
+.Ed
+.Pp
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace
+the \(lqwith...Texts.\(rq line with this:
+.Pp
+.Bd -literal -offset indent
+
+    with the Invariant Sections being list their titles, with
+    the Front-Cover Texts being list, and with the Back-Cover Texts
+    being list.
+
+.Ed
+.Pp
+If you have Invariant Sections without Cover Texts, or some other combination
+of the three, merge those two alternatives to suit the situation.
+.Pp
+If your document contains nontrivial examples of program code, we recommend
+releasing these examples in parallel under your choice of free software license,
+such as the GNU General Public License, to permit their use in free software.
+.Pp
+.Sh  Translations of This Manual
+Nishio Futoshi of the GNUjdoc project has prepared a Japanese translation
+of this manual. Its most recent version can be found at
+.Lk http://openlab.ring.gr.jp/gnujdoc/cvsweb/cvsweb.cgi/gnujdoc/ .
+.Pp
+.Sh  Index