summaryrefslogtreecommitdiff
path: root/gnu/dist/diffutils/doc/diff.texi
diff options
context:
space:
mode:
Diffstat (limited to 'gnu/dist/diffutils/doc/diff.texi')
-rw-r--r--gnu/dist/diffutils/doc/diff.texi4557
1 files changed, 0 insertions, 4557 deletions
diff --git a/gnu/dist/diffutils/doc/diff.texi b/gnu/dist/diffutils/doc/diff.texi
deleted file mode 100644
index d4e952a4923..00000000000
--- a/gnu/dist/diffutils/doc/diff.texi
+++ /dev/null
@@ -1,4557 +0,0 @@
-\input texinfo @c -*-texinfo-*-
-@c $NetBSD: diff.texi,v 1.2 2003/01/26 00:48:01 wiz Exp $
-@comment $Id: diff.texi,v 1.2 2003/01/26 00:48:01 wiz Exp $
-@comment %**start of header
-@setfilename diff.info
-@include version.texi
-@settitle Comparing and Merging Files
-@syncodeindex vr cp
-@setchapternewpage odd
-@comment %**end of header
-@copying
-This manual is for GNU Diffutils
-(version @value{VERSION}, @value{UPDATED}),
-and documents the @sc{gnu} @command{diff}, @command{diff3},
-@command{sdiff}, and @command{cmp} commands for showing the
-differences between files and the @sc{gnu} @command{patch} command for
-using their output to update files.
-
-Copyright @copyright{} 1992, 1993, 1994, 1998, 2001, 2002 Free
-Software Foundation, Inc.
-
-@quotation
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
-and with the Back-Cover Texts as in (a) below. A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License.''
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
-@end quotation
-@end copying
-
-@c Debian install-info (up through at least version 1.9.20) uses only the
-@c first dircategory. Put this one first, as it is more useful in practice.
-@dircategory Individual utilities
-@direntry
-* cmp: (diff)Invoking cmp. Compare 2 files byte by byte.
-* diff: (diff)Invoking diff. Compare 2 files line by line.
-* diff3: (diff)Invoking diff3. Compare 3 files line by line.
-* patch: (diff)Invoking patch. Apply a patch to a file.
-* sdiff: (diff)Invoking sdiff. Merge 2 files side-by-side.
-@end direntry
-
-@dircategory GNU packages
-@direntry
-* Diff: (diff). Comparing and merging files.
-@end direntry
-
-@titlepage
-@title Comparing and Merging Files
-@subtitle for Diffutils @value{VERSION} and @code{patch} 2.5.4
-@subtitle @value{UPDATED}
-@author David MacKenzie, Paul Eggert, and Richard Stallman
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@shortcontents
-@contents
-
-@ifnottex
-@node Top
-@top Comparing and Merging Files
-
-@insertcopying
-@end ifnottex
-
-@menu
-* Overview:: Preliminary information.
-* Comparison:: What file comparison means.
-
-* Output Formats:: Formats for two-way difference reports.
-* Incomplete Lines:: Lines that lack trailing newlines.
-* Comparing Directories:: Comparing files and directories.
-* Adjusting Output:: Making @command{diff} output prettier.
-* diff Performance:: Making @command{diff} smarter or faster.
-
-* Comparing Three Files:: Formats for three-way difference reports.
-* diff3 Merging:: Merging from a common ancestor.
-
-* Interactive Merging:: Interactive merging with @command{sdiff}.
-
-* Merging with patch:: Using @command{patch} to change old files into new ones.
-* Making Patches:: Tips for making and using patch distributions.
-
-* Invoking cmp:: Compare two files byte by byte.
-* Invoking diff:: Compare two files line by line.
-* Invoking diff3:: Compare three files line by line.
-* Invoking patch:: Apply a diff file to an original.
-* Invoking sdiff:: Side-by-side merge of file differences.
-
-* Standards conformance:: Conformance to the @sc{posix} standard.
-* Projects:: If you've found a bug or other shortcoming.
-
-* Copying This Manual:: How to make copies of this manual.
-* Index:: Index.
-@end menu
-
-@node Overview
-@unnumbered Overview
-@cindex overview of @command{diff} and @command{patch}
-
-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.
-
-You can use the @command{diff} command to show differences between two
-files, or each corresponding file in two directories. @command{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 @dfn{diff} or @dfn{patch}. For files that are identical,
-@command{diff} normally produces no output; for binary (non-text) files,
-@command{diff} normally reports only that they are different.
-
-You can use the @command{cmp} command to show the byte and line numbers
-where two files differ. @command{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 @kbd{M-x
-compare-windows}. @xref{Other Window, , Other Window, emacs, The @sc{gnu}
-Emacs Manual}, for more information on that command.
-
-You can use the @command{diff3} command to show differences among three
-files. When two people have made independent changes to a common
-original, @command{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.
-
-You can use the @command{sdiff} command to merge two files interactively.
-
-You can use the set of differences produced by @command{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 @command{diff} output, you can use the
-@command{patch} program to update, or @dfn{patch}, a copy of the file. If you
-think of @command{diff} as subtracting one file from another to produce
-their difference, you can think of @command{patch} as adding the difference
-to one file to reproduce the other.
-
-This manual first concentrates on making diffs, and later shows how to
-use diffs to update files.
-
-@sc{gnu} @command{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
-in ``An O(ND) Difference Algorithm and its Variations'', Eugene W. Myers,
-@cite{Algorithmica} Vol.@: 1 No.@: 2, 1986, pp.@: 251--266; and in ``A File
-Comparison Program'', Webb Miller and Eugene W. Myers,
-@cite{Software---Practice and Experience} Vol.@: 15 No.@: 11, 1985,
-pp.@: 1025--1040.
-@c From: "Gene Myers" <gene@cs.arizona.edu>
-@c They are about the same basic algorithm; the Algorithmica
-@c paper gives a rigorous treatment and the sub-algorithm for
-@c delivering scripts and should be the primary reference, but
-@c both should be mentioned.
-The algorithm was independently discovered as described in
-``Algorithms for Approximate String Matching'',
-E. Ukkonen, @cite{Information and Control} Vol.@: 64, 1985, pp.@: 100--118.
-@c From: "Gene Myers" <gene@cs.arizona.edu>
-@c Date: Wed, 29 Sep 1993 08:27:55 MST
-@c Ukkonen should be given credit for also discovering the algorithm used
-@c in GNU diff.
-
-@sc{gnu} @command{diff3} was written by Randy Smith. @sc{gnu}
-@command{sdiff} was written by Thomas Lord. @sc{gnu} @command{cmp}
-was written by Torbjorn Granlund and David MacKenzie.
-
-@command{patch} was written mainly by Larry Wall and Paul Eggert;
-several @sc{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.
-
-@node Comparison
-@chapter What Comparison Means
-@cindex introduction
-
-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. @command{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.
-
-@sc{gnu} @command{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. @command{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.
-
-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. @command{cmp} reports the differences between two files
-byte by byte, instead of line by line. As a result, it is often
-more useful than @command{diff} for comparing binary files. For text
-files, @command{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.
-
-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, @command{diff} will report that a
-blank line has been added to the file, while @command{cmp} will report that
-almost every byte of the two files differs.
-
-@command{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.
-
-@menu
-* Hunks:: Groups of differing lines.
-* White Space:: Suppressing differences in white space.
-* Blank Lines:: Suppressing differences in blank lines.
-* Case Folding:: Suppressing differences in alphabetic case.
-* Specified Folding:: Suppressing differences that match regular expressions.
-* Brief:: Summarizing which files are different.
-* Binary:: Comparing binary files or forcing text comparisons.
-@end menu
-
-@node Hunks
-@section Hunks
-@cindex hunks
-
-When comparing two files, @command{diff} finds sequences of lines common to
-both files, interspersed with groups of differing lines called
-@dfn{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. @command{diff} tries to minimize
-the total hunk size by finding large sequences of common lines
-interspersed with small hunks of differing lines.
-
-For example, suppose the file @file{F} contains the three lines
-@samp{a}, @samp{b}, @samp{c}, and the file @file{G} contains the same
-three lines in reverse order @samp{c}, @samp{b}, @samp{a}. If
-@command{diff} finds the line @samp{c} as common, then the command
-@samp{diff F G} produces this output:
-
-@example
-1,2d0
-< a
-< b
-3a2,3
-> b
-> a
-@end example
-
-@noindent
-But if @command{diff} notices the common line @samp{b} instead, it produces
-this output:
-
-@example
-1c1
-< a
----
-> c
-3c3
-< c
----
-> a
-@end example
-
-@noindent
-It is also possible to find @samp{a} as the common line. @command{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
-@option{--minimal} option (@pxref{diff Performance}).
-
-@node White Space
-@section Suppressing Differences in Blank and Tab Spacing
-@cindex blank and tab difference suppression
-@cindex tab and blank difference suppression
-
-The @option{-E} and @option{--ignore-tab-expansion} options ignore 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. @command{diff}
-assumes that tab stops are set every 8 print columns.
-
-The @option{-b} and @option{--ignore-space-change} options are stronger.
-They ignore white space at line end, and consider all other sequences of
-one or more white space characters to be equivalent. With these
-options, @command{diff} considers the following two lines to be equivalent,
-where @samp{$} denotes the line end:
-
-@example
-Here lyeth muche rychnesse in lytell space. -- John Heywood$
-Here lyeth muche rychnesse in lytell space. -- John Heywood $
-@end example
-
-The @option{-w} and @option{--ignore-all-space} options are stronger still.
-They ignore difference even if one line has white space where
-the other line has none. @dfn{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 these options, @command{diff} considers the
-following two lines to be equivalent, where @samp{$} denotes the line
-end and @samp{^M} denotes a carriage return:
-
-@example
-Here lyeth muche rychnesse in lytell space.-- John Heywood$
- He relyeth much erychnes seinly tells pace. --John Heywood ^M$
-@end example
-
-@node Blank Lines
-@section Suppressing Differences in Blank Lines
-@cindex blank line difference suppression
-
-The @option{-B} and @option{--ignore-blank-lines} options ignore insertions
-or deletions of blank lines. These options affect only lines
-that are completely empty; they do not affect lines that look empty but
-contain space or tab characters. With these options, for example, a
-file containing
-@example
-1. A point is that which has no part.
-
-2. A line is breadthless length.
--- Euclid, The Elements, I
-@end example
-@noindent
-is considered identical to a file containing
-@example
-1. A point is that which has no part.
-2. A line is breadthless length.
-
-
--- Euclid, The Elements, I
-@end example
-
-@node Case Folding
-@section Suppressing Case Differences
-@cindex case difference suppression
-
-@sc{gnu} @command{diff} can treat lower case letters as equivalent to their
-upper case counterparts, so that, for example, it considers @samp{Funky
-Stuff}, @samp{funky STUFF}, and @samp{fUNKy stuFf} to all be the same.
-To request this, use the @option{-i} or @option{--ignore-case} option.
-
-@node Specified Folding
-@section Suppressing Lines Matching a Regular Expression
-@cindex regular expression suppression
-
-To ignore insertions and deletions of lines that match a
-@command{grep}-style regular expression, use the @option{-I
-@var{regexp}} or @option{--ignore-matching-lines=@var{regexp}} option.
-You should escape
-regular expressions that contain shell metacharacters to prevent the
-shell from expanding them. For example, @samp{diff -I '^[[:digit:]]'} ignores
-all changes to lines beginning with a digit.
-
-However, @option{-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, @command{diff} prints the complete set
-of changes in its vicinity, including the ignorable ones.
-
-You can specify more than one regular expression for lines to ignore by
-using more than one @option{-I} option. @command{diff} tries to match each
-line against each regular expression.
-
-@node Brief
-@section Summarizing Which Files Differ
-@cindex summarizing which files differ
-@cindex brief difference reports
-
-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, @command{diff} simply reports whether files differ. The @option{-q}
-and @option{--brief} options select this output format.
-
-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 @command{diff} can stop analyzing the files as soon as
-it knows that there are any differences.
-
-You can also get a brief indication of whether two files differ by using
-@command{cmp}. For files that are identical, @command{cmp} produces no
-output. When the files differ, by default, @command{cmp} outputs the byte
-and line number where the first difference occurs. You can use
-the @option{-s} option to suppress that information, so that @command{cmp}
-produces no output and reports whether the files differ using only its
-exit status (@pxref{Invoking cmp}).
-
-@c Fix this.
-Unlike @command{diff}, @command{cmp} cannot compare directories; it can only
-compare two files.
-
-@node Binary
-@section Binary Files and Forcing Text Comparisons
-@cindex binary file diff
-@cindex text versus binary diff
-
-If @command{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 (@pxref{Brief}), and
-reports only that the binary files are different. This is because line
-by line comparisons are usually not meaningful for binary files.
-
-@command{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, @command{diff} considers the file to be
-text; otherwise it considers the file to be binary.
-
-Sometimes you might want to force @command{diff} to consider files to be
-text. For example, you might be comparing text files that contain
-null characters; @command{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 @command{diff} to consider all
-files to be text files, and compare them line by line, by using the
-@option{-a} or @option{--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 @command{diff} output will consist of hunks
-showing differences between long lines of whatever characters the files
-contain.
-
-You can also force @command{diff} to consider all files to be binary files,
-and report only whether they differ (but not how). Use the
-@option{-q} or @option{--brief} option for this.
-
-Differing binary files are considered to cause trouble because the
-resulting @command{diff} output does not capture all the differences.
-This trouble causes @command{diff} to exit with status 2. However,
-this trouble cannot occur with the @option{--a} or @option{--text}
-option, or with the @option{-q} or @option{--brief} option, as these
-options both cause @command{diff} to treat binary files like text
-files.
-
-In operating systems that distinguish between text and binary files,
-@command{diff} normally reads and writes all data as text. Use the
-@option{--binary} option to force @command{diff} to read and write binary
-data instead. This option has no effect on a @sc{posix}-compliant system
-like @sc{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, @command{diff} normally ignores
-these carriage returns on input and generates them at the end of each
-output line, but with the @option{--binary} option @command{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 @sc{posix}-compliant systems.
-
-The @option{--strip-trailing-cr} causes @command{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.
-
-If you want to compare two files byte by byte, you can use the
-@command{cmp} program with the @option{-l} option to show the values
-of each differing byte in the two files. With @sc{gnu} @command{cmp},
-you can also use the @option{-b} option to show the @sc{ascii}
-representation of those bytes. @xref{Invoking cmp}, for more
-information.
-
-If @command{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. @command{diff3} uses the same test as
-@command{diff} to decide whether a file is binary. As with @command{diff}, if
-the input files contain a few non-text bytes but otherwise are like
-text files, you can force @command{diff3} to consider all files to be text
-files and compare them line by line by using the @option{-a} or
-@option{--text} options.
-
-@node Output Formats
-@chapter @command{diff} Output Formats
-@cindex output formats
-@cindex format of @command{diff} output
-
-@command{diff} has several mutually exclusive options for output format.
-The following sections describe each format, illustrating how
-@command{diff} reports the differences between two sample input files.
-
-@menu
-* Sample diff Input:: Sample @command{diff} input files for examples.
-* Normal:: Showing differences without surrounding text.
-* Context:: Showing differences with the surrounding text.
-* Side by Side:: Showing differences in two columns.
-* Scripts:: Generating scripts for other programs.
-* If-then-else:: Merging files with if-then-else.
-@end menu
-
-@node Sample diff Input
-@section Two Sample Input Files
-@cindex @command{diff} sample input
-@cindex sample input for @command{diff}
-
-Here are two sample files that we will use in numerous examples to
-illustrate the output of @command{diff} and how various options can change
-it.
-
-This is the file @file{lao}:
-
-@example
-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.
-@end example
-
-This is the file @file{tzu}:
-
-@example
-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!
-@end example
-
-In this example, the first hunk contains just the first two lines of
-@file{lao}, the second hunk contains the fourth line of @file{lao}
-opposing the second and third lines of @file{tzu}, and the last hunk
-contains just the last three lines of @file{tzu}.
-
-@node Normal
-@section Showing Differences Without Context
-@cindex normal output format
-@cindex @samp{<} output format
-
-The ``normal'' @command{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 (@pxref{Context Format}) and the unified format
-(@pxref{Unified Format}) are superior. Normal format is the default for
-compatibility with older versions of @command{diff} and the @sc{posix}
-standard. Use the @option{--normal} option to select this output
-format explicitly.
-
-@menu
-* Detailed Normal:: A detailed description of normal output format.
-* Example Normal:: Sample output in the normal format.
-@end menu
-
-@node Detailed Normal
-@subsection Detailed Description of Normal Format
-
-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:
-
-@example
-@var{change-command}
-< @var{from-file-line}
-< @var{from-file-line}@dots{}
----
-> @var{to-file-line}
-> @var{to-file-line}@dots{}
-@end example
-
-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:
-
-@table @samp
-@item @var{l}a@var{r}
-Add the lines in range @var{r} of the second file after line @var{l} of
-the first file. For example, @samp{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.
-
-@item @var{f}c@var{t}
-Replace the lines in range @var{f} of the first file with lines in range
-@var{t} of the second file. This is like a combined add and delete, but
-more compact. For example, @samp{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.
-
-@item @var{r}d@var{l}
-Delete the lines in range @var{r} from the first file; line @var{l} is where
-they would have appeared in the second file had they not been deleted.
-For example, @samp{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.
-@end table
-
-@node Example Normal
-@subsection An Example of Normal Format
-
-Here is the output of the command @samp{diff lao tzu}
-(@pxref{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.
-
-@example
-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!
-@end example
-
-@node Context
-@section Showing Differences in Their Context
-@cindex context output format
-@cindex @samp{!} output format
-
-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 @dfn{context}.
-
-@sc{gnu} @command{diff} provides two output formats that show context
-around the differing lines: @dfn{context format} and @dfn{unified
-format}. It can optionally show in which function or section of the
-file the differing lines are found.
-
-If you are distributing new versions of files to other people in the
-form of @command{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. @command{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, @command{patch} can adjust
-the line numbers accordingly and still apply the diff correctly.
-@xref{Imperfect}, for more information on using @command{patch} to apply
-imperfect diffs.
-
-@menu
-* Context Format:: An output format that shows surrounding lines.
-* Unified Format:: A more compact output format that shows context.
-* Sections:: Showing which sections of the files differences are in.
-* Alternate Names:: Showing alternate file names in context headers.
-@end menu
-
-@node Context Format
-@subsection Context Format
-
-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.
-
-To select this output format, use the @option{-C @var{lines}},
-@option{--context@r{[}=@var{lines}@r{]}}, or @option{-c} option. The
-argument @var{lines} that some of these options take is the number of
-lines of context to show. If you do not specify @var{lines}, it
-defaults to three. For proper operation, @command{patch} typically needs
-at least two lines of context.
-
-@menu
-* Detailed Context:: A detailed description of the context output format.
-* Example Context:: Sample output in context format.
-* Less Context:: Another sample with less context.
-@end menu
-
-@node Detailed Context
-@subsubsection Detailed Description of Context Format
-
-The context output format starts with a two-line header, which looks
-like this:
-
-@example
-*** @var{from-file} @var{from-file-modification-time}
---- @var{to-file} @var{to-file-modification time}
-@end example
-
-@noindent
-@vindex LC_TIME
-@cindex time stamp format, context diffs
-The time stamp normally looks like @samp{2002-02-21 23:30:39.942229878
--0800} to indicate the date, time with fractional seconds, and time
-zone in @uref{ftp://ftp.isi.edu/in-notes/rfc2822.txt, Internet RFC
-2822 format}. However, a traditional time stamp like @samp{Thu Feb 21
-23:30:39 2002} is used if the @env{LC_TIME} locale category is either
-@samp{C} or @samp{POSIX}.
-
-You can change the header's content with the
-@option{--label=@var{label}} option; see @ref{Alternate Names}.
-
-Next come one or more hunks of differences; each hunk shows one area
-where the files differ. Context format hunks look like this:
-
-@example
-***************
-*** @var{from-file-line-range} ****
- @var{from-file-line}
- @var{from-file-line}@dots{}
---- @var{to-file-line-range} ----
- @var{to-file-line}
- @var{to-file-line}@dots{}
-@end example
-
-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:
-
-@table @samp
-@item !
-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
-@samp{!} in the part of this hunk for the other file.
-
-@item +
-An ``inserted'' line in the second file that corresponds to nothing in
-the first file.
-
-@item -
-A ``deleted'' line in the first file that corresponds to nothing in the
-second file.
-@end table
-
-If all of the changes in a hunk are insertions, the lines of
-@var{from-file} are omitted. If all of the changes are deletions, the
-lines of @var{to-file} are omitted.
-
-@node Example Context
-@subsubsection An Example of Context Format
-
-Here is the output of @samp{diff -c lao tzu} (@pxref{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.
-
-@example
-*** 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!
-@end example
-
-@node Less Context
-@subsubsection An Example of Context Format with Less Context
-
-Here is the output of @samp{diff -C 1 lao tzu} (@pxref{Sample diff
-Input}, for the complete contents of the two files). Notice that at
-most one context line is reported here.
-
-@example
-*** 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!
-@end example
-
-@node Unified Format
-@subsection Unified Format
-@cindex unified output format
-@cindex @samp{+-} output format
-
-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 @option{-U @var{lines}},
-@option{--unified@r{[}=@var{lines}@r{]}}, or @option{-u}
-option. The argument @var{lines} is the number of lines of context to
-show. When it is not given, it defaults to three.
-
-At present, only @sc{gnu} @command{diff} can produce this format and
-only @sc{gnu} @command{patch} can automatically apply diffs in this
-format. For proper operation, @command{patch} typically needs at
-least three lines of context.
-
-@menu
-* Detailed Unified:: A detailed description of unified format.
-* Example Unified:: Sample output in unified format.
-@end menu
-
-@node Detailed Unified
-@subsubsection Detailed Description of Unified Format
-
-The unified output format starts with a two-line header, which looks
-like this:
-
-@example
---- @var{from-file} @var{from-file-modification-time}
-+++ @var{to-file} @var{to-file-modification-time}
-@end example
-
-@noindent
-@cindex time stamp format, unified diffs
-The time stamp looks like @samp{2002-02-21 23:30:39.942229878 -0800}
-to indicate the date, time with fractional seconds, and time zone.
-
-You can change the header's content with the
-@option{--label=@var{label}} option; see @xref{Alternate Names}.
-
-Next come one or more hunks of differences; each hunk shows one area
-where the files differ. Unified format hunks look like this:
-
-@example
-@@@@ @var{from-file-range} @var{to-file-range} @@@@
- @var{line-from-either-file}
- @var{line-from-either-file}@dots{}
-@end example
-
-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:
-
-@table @samp
-@item +
-A line was added here to the first file.
-
-@item -
-A line was removed here from the first file.
-@end table
-
-@node Example Unified
-@subsubsection An Example of Unified Format
-
-Here is the output of the command @samp{diff -u lao tzu}
-(@pxref{Sample diff Input}, for the complete contents of the two files):
-
-@example
---- 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!
-@end example
-
-@node Sections
-@subsection Showing Which Sections Differences Are in
-@cindex headings
-@cindex section headings
-
-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. @sc{gnu} @command{diff} can show this by displaying the
-nearest section heading line that precedes the differing lines. Which
-lines are ``section headings'' is determined by a regular expression.
-
-@menu
-* Specified Headings:: Showing headings that match regular expressions.
-* C Function Headings:: Showing headings of C functions.
-@end menu
-
-@node Specified Headings
-@subsubsection Showing Lines That Match Regular Expressions
-@cindex specified headings
-@cindex regular expression matching headings
-
-To show in which sections differences occur for files that are not
-source code for C or similar languages, use the @option{-F @var{regexp}}
-or @option{--show-function-line=@var{regexp}} option. @command{diff}
-considers lines that match the @command{grep}-style regular expression
-@var{regexp} to be the beginning
-of a section of the file. Here are suggested regular expressions for
-some common languages:
-
-@c Please add to this list, e.g. Fortran, Pascal, Perl, Python.
-@table @samp
-@item ^[[:alpha:]$_]
-C, C++, Prolog
-@item ^(
-Lisp
-@item ^@@node
-Texinfo
-@end table
-
-This option does not automatically select an output format; in order to
-use it, you must select the context format (@pxref{Context Format}) or
-unified format (@pxref{Unified Format}). In other output formats it
-has no effect.
-
-The @option{-F} and @option{--show-function-line} options find the nearest
-unchanged line that precedes each hunk of differences and matches the
-given regular expression. Then they add that line to the end of the
-line of asterisks in the context format, or to the @samp{@@@@} line in
-unified format. If no matching line exists, they leave the output for
-that hunk unchanged. If that line is more than 40 characters long, they
-output only the first 40 characters. You can specify more than one
-regular expression for such lines; @command{diff} tries to match each line
-against each regular expression, starting with the last one given. This
-means that you can use @option{-p} and @option{-F} together, if you wish.
-
-@node C Function Headings
-@subsubsection Showing C Function Headings
-@cindex C function headings
-@cindex function headings, C
-
-To show in which functions differences occur for C and similar
-languages, you can use the @option{-p} or @option{--show-c-function} option.
-This option automatically defaults to the context output format
-(@pxref{Context Format}), with the default number of lines of context.
-You can override that number with @option{-C @var{lines}} elsewhere in the
-command line. You can override both the format and the number with
-@option{-U @var{lines}} elsewhere in the command line.
-
-The @option{-p} and @option{--show-c-function} options are equivalent to
-@option{-F '^[[:alpha:]$_]'} if the unified format is specified, otherwise
-@option{-c -F '^[[:alpha:]$_]'} (@pxref{Specified Headings}). @sc{gnu}
-@command{diff} provides them for the sake of convenience.
-
-@node Alternate Names
-@subsection Showing Alternate File Names
-@cindex alternate file names
-@cindex file name alternates
-
-If you are comparing two files that have meaningless or uninformative
-names, you might want @command{diff} to show alternate names in the header
-of the context and unified output formats. To do this, use the
-@option{--label=@var{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, @command{diff} reports an error. The @option{--label} option does not
-affect the file names in the @command{pr} header when the @option{-l} or
-@option{--paginate} option is used (@pxref{Pagination}).
-
-Here are the first two lines of the output from @samp{diff -C 2
---label=original --label=modified lao tzu}:
-
-@example
-*** original
---- modified
-@end example
-
-@node Side by Side
-@section Showing Differences Side by Side
-@cindex side by side
-@cindex two-column output
-@cindex columnar output
-
-@command{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:
-
-@table @asis
-@item 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
-@option{--ignore} options (@pxref{White Space}).
-
-@item @samp{|}
-The corresponding lines differ, and they are either both complete
-or both incomplete.
-
-@item @samp{<}
-The files differ and only the first file contains the line.
-
-@item @samp{>}
-The files differ and only the second file contains the line.
-
-@item @samp{(}
-Only the first file contains the line, but the difference is ignored.
-
-@item @samp{)}
-Only the second file contains the line, but the difference is ignored.
-
-@item @samp{\}
-The corresponding lines differ, and only the first line is incomplete.
-
-@item @samp{/}
-The corresponding lines differ, and only the second line is incomplete.
-@end table
-
-Normally, an output line is incomplete if and only if the lines that it
-contains are incomplete; @xref{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 @samp{\} if the first line is incomplete,
-@samp{/} if the second line is.
-
-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.
-
-You can use the @command{sdiff} command to interactively merge side by side
-differences. @xref{Interactive Merging}, for more information on merging files.
-
-@menu
-* Side by Side Format:: Controlling side by side output format.
-* Example Side by Side:: Sample side by side output.
-@end menu
-
-@node Side by Side Format
-@subsection Controlling Side by Side Format
-@cindex side by side format
-
-The @option{-y} or @option{--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 @option{-W @var{columns}} or @option{--width=@var{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.
-
-The @option{--left-column} option prints only the left column of two
-common lines. The @option{--suppress-common-lines} option suppresses
-common lines entirely.
-
-@node Example Side by Side
-@subsection An Example of Side by Side Format
-
-Here is the output of the command @samp{diff -y -W 72 lao tzu}
-(@pxref{Sample diff Input}, for the complete contents of the two files).
-
-@example
-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!
-@end example
-
-@node Scripts
-@section Making Edit Scripts
-@cindex script output formats
-
-Several output modes produce command scripts for editing @var{from-file}
-to produce @var{to-file}.
-
-@menu
-* ed Scripts:: Using @command{diff} to produce commands for @command{ed}.
-* Forward ed:: Making forward @command{ed} scripts.
-* RCS:: A special @command{diff} output format used by @sc{rcs}.
-@end menu
-
-@node ed Scripts
-@subsection @command{ed} Scripts
-@cindex @command{ed} script output format
-
-@command{diff} can produce commands that direct the @command{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 @command{patch}, it is almost obsolete. Use the
-@option{-e} or @option{--ed} option to select this output format.
-
-Like the normal format (@pxref{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).
-
-If the file @file{d} contains the output of @samp{diff -e old new}, then
-the command @samp{(cat d && echo w) | ed - old} edits @file{old} to make
-it a copy of @file{new}. More generally, if @file{d1}, @file{d2},
-@dots{}, @file{dN} contain the outputs of @samp{diff -e old new1},
-@samp{diff -e new1 new2}, @dots{}, @samp{diff -e newN-1 newN},
-respectively, then the command @samp{(cat d1 d2 @dots{} dN && echo w) |
-ed - old} edits @file{old} to make it a copy of @file{newN}.
-
-@menu
-* Detailed ed:: A detailed description of @command{ed} format.
-* Example ed:: A sample @command{ed} script.
-@end menu
-
-@node Detailed ed
-@subsubsection Detailed Description of @command{ed} Format
-
-The @command{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
-@command{ed} interprets line numbers in succeeding commands. @command{ed}
-format hunks look like this:
-
-@example
-@var{change-command}
-@var{to-file-line}
-@var{to-file-line}@dots{}
-.
-@end example
-
-Because @command{ed} uses a single period on a line to indicate the end of
-input, @sc{gnu} @command{diff} protects lines of changes that contain a single
-period on a line by writing two periods instead, then writing a
-subsequent @command{ed} command to change the two periods into one. The
-@command{ed} format cannot represent an incomplete line, so if the second
-file ends in a changed incomplete line, @command{diff} reports an error and
-then pretends that a newline was appended.
-
-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:
-
-@table @samp
-@item @var{l}a
-Add text from the second file after line @var{l} in the first file. For
-example, @samp{8a} means to add the following lines after line 8 of file
-1.
-
-@item @var{r}c
-Replace the lines in range @var{r} in the first file with the following
-lines. Like a combined add and delete, but more compact. For example,
-@samp{5,7c} means change lines 5--7 of file 1 to read as the text file
-2.
-
-@item @var{r}d
-Delete the lines in range @var{r} from the first file. For example,
-@samp{5,7d} means delete lines 5--7 of file 1.
-@end table
-
-@node Example ed
-@subsubsection Example @command{ed} Script
-
-Here is the output of @samp{diff -e lao tzu} (@pxref{Sample
-diff Input}, for the complete contents of the two files):
-
-@example
-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
-@end example
-
-@node Forward ed
-@subsection Forward @command{ed} Scripts
-@cindex forward @command{ed} script output format
-
-@command{diff} can produce output that is like an @command{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
-@command{ed} format, forward @command{ed} format cannot represent incomplete
-lines.
-
-Forward @command{ed} format is not very useful, because neither @command{ed}
-nor @command{patch} can apply diffs in this format. It exists mainly for
-compatibility with older versions of @command{diff}. Use the @option{-f} or
-@option{--forward-ed} option to select it.
-
-@node RCS
-@subsection @sc{rcs} Scripts
-@cindex @sc{rcs} script output format
-
-The @sc{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 @option{-n} or
-@option{--rcs} option to select this output format. It is like the
-forward @command{ed} format (@pxref{Forward ed}), but it can represent
-arbitrary changes to the contents of a file because it avoids the
-forward @command{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 @samp{a} and @samp{d}
-commands are used instead of @samp{c}. Also, if the second file ends
-in a changed incomplete line, then the output also ends in an
-incomplete line.
-
-Here is the output of @samp{diff -n lao tzu} (@pxref{Sample
-diff Input}, for the complete contents of the two files):
-
-@example
-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!
-@end example
-
-@node If-then-else
-@section Merging Files with If-then-else
-@cindex merged output format
-@cindex if-then-else output format
-@cindex C if-then-else output format
-@cindex @command{ifdef} output format
-
-You can use @command{diff} to merge two files of C source code. The output
-of @command{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 @code{#ifdef @var{name}} or
-@code{#ifndef @var{name}}, @code{#else}, and @code{#endif}. When
-compiling the output, you select which version to use by either defining
-or leaving undefined the macro @var{name}.
-
-To merge two files, use @command{diff} with the @option{-D @var{name}} or
-@option{--ifdef=@var{name}} option. The argument @var{name} is the C
-preprocessor identifier to use in the @code{#ifdef} and @code{#ifndef}
-directives.
-
-For example, if you change an instance of @code{wait (&s)} to
-@code{waitpid (-1, &s, 0)} and then merge the old and new files with
-the @option{--ifdef=HAVE_WAITPID} option, then the affected part of your code
-might look like this:
-
-@example
- 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);
-@end example
-
-You can specify formats for languages other than C by using line group
-formats and line formats, as described in the next sections.
-
-@menu
-* Line Group Formats:: Formats for general if-then-else line groups.
-* Line Formats:: Formats for each line in a line group.
-* Detailed If-then-else:: A detailed description of if-then-else format.
-* Example If-then-else:: Sample if-then-else format output.
-@end menu
-
-@node Line Group Formats
-@subsection Line Group Formats
-@cindex line group formats
-@cindex formats for if-then-else line groups
-
-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.
-
-For example, the following command compares the TeX files @file{old}
-and @file{new}, and outputs a merged file in which old regions are
-surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new
-regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines.
-
-@example
-diff \
- --old-group-format='\begin@{em@}
-%<\end@{em@}
-' \
- --new-group-format='\begin@{bf@}
-%>\end@{bf@}
-' \
- old new
-@end example
-
-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.
-
-@example
-diff \
- --old-group-format='\begin@{em@}
-%<\end@{em@}
-' \
- --new-group-format='\begin@{bf@}
-%>\end@{bf@}
-' \
- --unchanged-group-format='%=' \
- --changed-group-format='\begin@{em@}
-%<\end@{em@}
-\begin@{bf@}
-%>\end@{bf@}
-' \
- old new
-@end example
-
-Here is a more advanced example, which outputs a diff listing with
-headers containing line numbers in a ``plain English'' style.
-
-@example
-diff \
- --unchanged-group-format='' \
- --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
-%<' \
- --new-group-format='-------- %dN line%(N=1?:s) added after %de:
-%>' \
- --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
-%<-------- to:
-%>' \
- old new
-@end example
-
-To specify a line group format, use @command{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 @var{format}, because it
-typically contains shell metacharacters.
-
-@table @option
-@item --old-group-format=@var{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.
-
-@item --new-group-format=@var{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.
-
-@item --changed-group-format=@var{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.
-
-@item --unchanged-group-format=@var{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.
-@end table
-
-In a line group format, ordinary characters represent themselves;
-conversion specifications start with @samp{%} and have one of the
-following forms.
-
-@table @samp
-@item %<
-stands for the lines from the first file, including the trailing newline.
-Each line is formatted according to the old line format (@pxref{Line Formats}).
-
-@item %>
-stands for the lines from the second file, including the trailing newline.
-Each line is formatted according to the new line format.
-
-@item %=
-stands for the lines common to both files, including the trailing newline.
-Each line is formatted according to the unchanged line format.
-
-@item %%
-stands for @samp{%}.
-
-@item %c'@var{C}'
-where @var{C} is a single character, stands for @var{C}.
-@var{C} may not be a backslash or an apostrophe.
-For example, @samp{%c':'} stands for a colon, even inside
-the then-part of an if-then-else format, which a colon would
-normally terminate.
-
-@item %c'\@var{O}'
-where @var{O} is a string of 1, 2, or 3 octal digits,
-stands for the character with octal code @var{O}.
-For example, @samp{%c'\0'} stands for a null character.
-
-@item @var{F}@var{n}
-where @var{F} is a @code{printf} conversion specification and @var{n} is one
-of the following letters, stands for @var{n}'s value formatted with @var{F}.
-
-@table @samp
-@item e
-The line number of the line just before the group in the old file.
-
-@item f
-The line number of the first line in the group in the old file;
-equals @var{e} + 1.
-
-@item l
-The line number of the last line in the group in the old file.
-
-@item m
-The line number of the line just after the group in the old file;
-equals @var{l} + 1.
-
-@item n
-The number of lines in the group in the old file; equals @var{l} - @var{f} + 1.
-
-@item E, F, L, M, N
-Likewise, for lines in the new file.
-
-@end table
-
-@vindex LC_NUMERIC
-The @code{printf} conversion specification can be @samp{%d},
-@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal,
-lower case hexadecimal, or upper case hexadecimal output
-respectively. After the @samp{%} 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 @samp{-} for left-justification, @samp{'} for separating
-the digit into groups as specified by the @env{LC_NUMERIC} locale category,
-and @samp{0} for padding with zeros instead of spaces.
-For example, @samp{%5dN} prints the number of new lines in the group
-in a field of width 5 characters, using the @code{printf} format @code{"%5d"}.
-
-@item (@var{A}=@var{B}?@var{T}:@var{E})
-If @var{A} equals @var{B} then @var{T} else @var{E}.
-@var{A} and @var{B} are each either a decimal constant
-or a single letter interpreted as above.
-This format spec is equivalent to @var{T} if
-@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}.
-
-For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to
-@samp{no lines} if @var{N} (the number of lines in the group in the the
-new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines}
-otherwise.
-@end table
-
-@node Line Formats
-@subsection Line Formats
-@cindex line formats
-
-Line formats control how each line taken from an input file is
-output as part of a line group in if-then-else format.
-
-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 @samp{-} for deleted lines, @samp{|} for added lines, and a space for
-unchanged lines. The formats contain newline characters where newlines
-are desired on output.
-
-@example
-diff \
- --old-line-format='-%l
-' \
- --new-line-format='|%l
-' \
- --unchanged-line-format=' %l
-' \
- old new
-@end example
-
-To specify a line format, use one of the following options. You should
-quote @var{format}, since it often contains shell metacharacters.
-
-@table @option
-@item --old-line-format=@var{format}
-formats lines just from the first file.
-
-@item --new-line-format=@var{format}
-formats lines just from the second file.
-
-@item --unchanged-line-format=@var{format}
-formats lines common to both files.
-
-@item --line-format=@var{format}
-formats all lines; in effect, it sets all three above options simultaneously.
-@end table
-
-In a line format, ordinary characters represent themselves;
-conversion specifications start with @samp{%} and have one of the
-following forms.
-
-@table @samp
-@item %l
-stands for the contents of the line, not counting its trailing
-newline (if any). This format ignores whether the line is incomplete;
-@xref{Incomplete Lines}.
-
-@item %L
-stands for the contents of the line, including its trailing newline
-(if any). If a line is incomplete, this format preserves its
-incompleteness.
-
-@item %%
-stands for @samp{%}.
-
-@item %c'@var{C}'
-where @var{C} is a single character, stands for @var{C}.
-@var{C} may not be a backslash or an apostrophe.
-For example, @samp{%c':'} stands for a colon.
-
-@item %c'\@var{O}'
-where @var{O} is a string of 1, 2, or 3 octal digits,
-stands for the character with octal code @var{O}.
-For example, @samp{%c'\0'} stands for a null character.
-
-@item @var{F}n
-where @var{F} is a @code{printf} conversion specification,
-stands for the line number formatted with @var{F}.
-For example, @samp{%.5dn} prints the line number using the
-@code{printf} format @code{"%.5d"}. @xref{Line Group Formats}, for
-more about printf conversion specifications.
-
-@end table
-
-The default line format is @samp{%l} followed by a newline character.
-
-If the input contains tab characters and it is important that they line
-up on output, you should ensure that @samp{%l} or @samp{%L} in a line
-format is just after a tab stop (e.g.@: by preceding @samp{%l} or
-@samp{%L} with a tab character), or you should use the @option{-t} or
-@option{--expand-tabs} option.
-
-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 @command{diff} format. You can tailor this command
-to get fine control over @command{diff} output.
-
-@example
-diff \
- --old-line-format='< %l
-' \
- --new-line-format='> %l
-' \
- --old-group-format='%df%(f=l?:,%dl)d%dE
-%<' \
- --new-group-format='%dea%dF%(F=L?:,%dL)
-%>' \
- --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
-%<---
-%>' \
- --unchanged-group-format='' \
- old new
-@end example
-
-@node Detailed If-then-else
-@subsection Detailed Description of If-then-else Format
-
-For lines common to both files, @command{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,
-@command{diff} uses the old line group format; if the hunk contains only
-lines from the second file, @command{diff} uses the new group format;
-otherwise, @command{diff} uses the changed group format.
-
-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.
-
-The option @option{--ifdef=@var{name}} is equivalent to
-the following sequence of options using shell syntax:
-
-@example
---old-group-format='#ifndef @var{name}
-%<#endif /* ! @var{name} */
-' \
---new-group-format='#ifdef @var{name}
-%>#endif /* @var{name} */
-' \
---unchanged-group-format='%=' \
---changed-group-format='#ifndef @var{name}
-%<#else /* @var{name} */
-%>#endif /* @var{name} */
-'
-@end example
-
-You should carefully check the @command{diff} output for proper nesting.
-For example, when using the @option{-D @var{name}} or
-@option{--ifdef=@var{name}} option, you should check that if the
-differing lines contain any of the C preprocessor directives
-@samp{#ifdef}, @samp{#ifndef}, @samp{#else}, @samp{#elif}, or
-@samp{#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.
-
-The @command{patch} @option{-D @var{name}} option behaves like
-the @command{diff} @option{-D @var{name}} option, except it operates on
-a file and a diff to produce a merged file; @xref{patch Options}.
-
-@node Example If-then-else
-@subsection An Example of If-then-else Format
-
-Here is the output of @samp{diff -DTWO lao tzu} (@pxref{Sample
-diff Input}, for the complete contents of the two files):
-
-@example
-#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 */
-@end example
-
-@node Incomplete Lines
-@chapter Incomplete Lines
-@cindex incomplete lines
-@cindex full lines
-@cindex newline treatment by @command{diff}
-
-When an input file ends in a non-newline character, its last line is
-called an @dfn{incomplete line} because its last character is not a
-newline. All other lines are called @dfn{full lines} and end in a
-newline character. Incomplete lines do not match full lines unless
-differences in white space are ignored (@pxref{White Space}).
-
-An incomplete line is normally distinguished on output from a full line
-by a following line that starts with @samp{\}. However, the @sc{rcs} format
-(@pxref{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 @samp{\} or @samp{/}
-gutter marker; @xref{Side by Side}. The if-then-else line format
-preserves a line's incompleteness with @samp{%L}, and discards the
-newline with @samp{%l}; @xref{Line Formats}. Finally, with the
-@command{ed} and forward @command{ed} output formats (@pxref{Output Formats})
-@command{diff} cannot represent an incomplete line, so it pretends there
-was a newline and reports an error.
-
-For example, suppose @file{F} and @file{G} are one-byte files that
-contain just @samp{f} and @samp{g}, respectively. Then @samp{diff F G}
-outputs
-
-@example
-1c1
-< f
-\ No newline at end of file
----
-> g
-\ No newline at end of file
-@end example
-
-@noindent
-(The exact message may differ in non-English locales.)
-@samp{diff -n F G} outputs the following without a trailing newline:
-
-@example
-d1 1
-a1 1
-g
-@end example
-
-@noindent
-@samp{diff -e F G} reports two errors and outputs the following:
-
-@example
-1c
-g
-.
-@end example
-
-@node Comparing Directories
-@chapter Comparing Directories
-
-@vindex LC_COLLATE
-You can use @command{diff} to compare some or all of the files in two
-directory trees. When both file name arguments to @command{diff} are
-directories, it compares each file that is contained in both
-directories, examining file names in alphabetical order as specified by
-the @env{LC_COLLATE} locale category. Normally
-@command{diff} is silent about pairs of files that contain no differences,
-but if you use the @option{-s} or @option{--report-identical-files} option,
-it reports pairs of identical files. Normally @command{diff} reports
-subdirectories common to both directories without comparing
-subdirectories' files, but if you use the @option{-r} or
-@option{--recursive} option, it compares every corresponding pair of files
-in the directory trees, as many levels deep as they go.
-
-For file names that are in only one of the directories, @command{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 @command{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 @option{-N} or @option{--new-file}
-option.
-
-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
-@option{--unidirectional-new-file} option instead of @option{-N}.
-This option is like @option{-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. @xref{Making Patches}, for more discussion of
-making patches for distribution.
-
-To ignore some files while comparing directories, use the @option{-x
-@var{pattern}} or @option{--exclude=@var{pattern}} option. This option
-ignores any files or subdirectories whose base names match the shell
-pattern @var{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 @var{pattern} in quotes so that the shell does not
-expand it. For example, the option @option{-x '*.[ao]'} ignores any file
-whose name ends with @samp{.a} or @samp{.o}.
-
-This option accumulates if you specify it more than once. For example,
-using the options @option{-x 'RCS' -x '*,v'} ignores any file or
-subdirectory whose base name is @samp{RCS} or ends with @samp{,v}.
-
-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 @option{-X
-@var{file}} or @option{--exclude-from=@var{file}} option.
-
-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 @option{-S @var{file}} or @option{--starting-file=@var{file}}
-option. This compares only the file @var{file} and all alphabetically
-later files in the topmost directory level.
-
-If two directories differ only in that file names are lower case in
-one directory and upper case in the upper, @command{diff} normally
-reports many differences because it compares file names in a
-case sensitive way. With the @option{--ignore-file-name-case} option,
-@command{diff} ignores case differences in file names, so that for example
-the contents of the file @file{Tao} in one directory are compared to
-the contents of the file @file{TAO} in the other. The
-@option{--no-ignore-file-name-case} option cancels the effect of the
-@option{--ignore-file-name-case} option, reverting to the default
-behavior.
-
-If an @option{-x @var{pattern}}, @option{--exclude=@var{pattern}},
-@option{-X @var{file}}, or @option{--exclude-from=@var{file}} option
-is specified while the @option{--ignore-file-name-case} option is in
-effect, case is ignored when excluding file names matching the
-specified patterns.
-
-@node Adjusting Output
-@chapter Making @command{diff} Output Prettier
-
-@command{diff} provides several ways to adjust the appearance of its output.
-These adjustments can be applied to any output format.
-
-@menu
-* Tabs:: Preserving the alignment of tab stops.
-* Pagination:: Page numbering and time-stamping @command{diff} output.
-@end menu
-
-@node Tabs
-@section Preserving Tab Stop Alignment
-@cindex tab stop alignment
-@cindex aligning tab stops
-
-The lines of text in some of the @command{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. @sc{gnu} @command{diff} provides two ways to make tab-aligned columns
-line up correctly.
-
-The first way is to have @command{diff} convert all tabs into the correct
-number of spaces before outputting them; select this method with the
-@option{-t} or @option{--expand-tabs} option. @command{diff} assumes that
-tab stops are set every 8 print columns. To use this form of output with
-@command{patch}, you must give @command{patch} the @option{-l} or
-@option{--ignore-white-space} option (@pxref{Changed White Space}, for more
-information).
-
-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 @option{-T} or
-@option{--initial-tab} option.
-
-@node Pagination
-@section Paginating @command{diff} Output
-@cindex paginating @command{diff} output
-
-It can be convenient to have long output page-numbered and time-stamped.
-The @option{-l} and @option{--paginate} options do this by sending the
-@command{diff} output through the @command{pr} program. Here is what the page
-header might look like for @samp{diff -lc lao tzu}:
-
-@example
-2002-02-22 14:20 diff -lc lao tzu Page 1
-@end example
-
-@node diff Performance
-@chapter @command{diff} Performance Tradeoffs
-@cindex performance of @command{diff}
-
-@sc{gnu} @command{diff} runs quite efficiently; however, in some circumstances
-you can cause it to run faster or produce a more compact set of changes.
-
-One way to improve @command{diff} performance is to use hard or
-symbolic links to files instead of copies. This improves performance
-because @command{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 @samp{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 @sc{gnu} @samp{cp -lR} or
-@samp{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.
-
-You can also affect the performance of @sc{gnu} @command{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.
-
-The way that @sc{gnu} @command{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 @command{diff} output is large, you
-might want @command{diff} to use a modified algorithm that sometimes
-produces a smaller set of differences. The @option{-d} or
-@option{--minimal} option does this; however, it can also cause
-@command{diff} to run more slowly than usual, so it is not the default
-behavior.
-
-When the files you are comparing are large and have small groups of
-changes scattered throughout them, you can use the
-@option{--speed-large-files} option to make a different modification to
-the algorithm that @command{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, @command{diff} might produce a larger set of
-differences; however, the output will still be correct.
-
-Normally @command{diff} discards the prefix and suffix that is common to
-both files before it attempts to find a minimal set of differences.
-This makes @command{diff} run faster, but occasionally it may produce
-non-minimal output. The @option{--horizon-lines=@var{lines}} option
-prevents @command{diff} from discarding the last @var{lines} lines of the
-prefix and the first @var{lines} lines of the suffix. This gives
-@command{diff} further opportunities to find a minimal output.
-
-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 @command{diff} command is free to choose which identical sequence is
-included in the hunk. In this case, @command{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.
-
-@node Comparing Three Files
-@chapter Comparing Three Files
-@cindex comparing three files
-@cindex format of @command{diff3} output
-
-Use the program @command{diff3} to compare three files and show any
-differences among them. (@command{diff3} can also merge files; see
-@ref{diff3 Merging}).
-
-The ``normal'' @command{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.
-
-@xref{Invoking diff3}, for more information on how to run @command{diff3}.
-
-@menu
-* Sample diff3 Input:: Sample @command{diff3} input for examples.
-* Detailed diff3 Normal:: A detailed description of normal output format.
-* diff3 Hunks:: The format of normal output format.
-* Example diff3 Normal:: Sample output in the normal format.
-@end menu
-
-@node Sample diff3 Input
-@section A Third Sample Input File
-@cindex @command{diff3} sample input
-@cindex sample input for @command{diff3}
-
-Here is a third sample file that will be used in examples to illustrate
-the output of @command{diff3} and how various options can change it. The
-first two files are the same that we used for @command{diff} (@pxref{Sample
-diff Input}). This is the third sample file, called @file{tao}:
-
-@example
-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
-@end example
-
-@node Detailed diff3 Normal
-@section Detailed Description of @command{diff3} Normal Format
-
-Each hunk begins with a line marked @samp{====}. Three-way hunks have
-plain @samp{====} lines, and two-way hunks have @samp{1}, @samp{2}, or
-@samp{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.
-
-Normally, two spaces precede each copy of an input line to distinguish
-it from the commands. But with the @option{-T} or @option{--initial-tab}
-option, @command{diff3} uses a tab instead of two spaces; this lines up
-tabs correctly. @xref{Tabs}, for more information.
-
-Commands take the following forms:
-
-@table @samp
-@item @var{file}:@var{l}a
-This hunk appears after line @var{l} of file @var{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, @samp{1:11a} means that the hunk follows line 11 in the first
-file and contains no lines from that file.
-
-@item @var{file}:@var{r}c
-This hunk contains the lines in the range @var{r} of file @var{file}.
-The range @var{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, @samp{2:11,13c} means that the hunk
-contains lines 11 through 13 from the second file.
-@end table
-
-If the last line in a set of input lines is incomplete
-(@pxref{Incomplete Lines}), it is distinguished on output from a full
-line by a following line that starts with @samp{\}.
-
-@node diff3 Hunks
-@section @command{diff3} Hunks
-@cindex hunks for @command{diff3}
-@cindex @command{diff3} hunks
-
-Groups of lines that differ in two or three of the input files are
-called @dfn{diff3 hunks}, by analogy with @command{diff} hunks
-(@pxref{Hunks}). If all three input files differ in a @command{diff3}
-hunk, the hunk is called a @dfn{three-way hunk}; if just two input files
-differ, it is a @dfn{two-way hunk}.
-
-As with @command{diff}, several solutions are possible. When comparing the
-files @samp{A}, @samp{B}, and @samp{C}, @command{diff3} normally finds
-@command{diff3} hunks by merging the two-way hunks output by the two
-commands @samp{diff A B} and @samp{diff A C}. This does not necessarily
-minimize the size of the output, but exceptions should be rare.
-
-For example, suppose @file{F} contains the three lines @samp{a},
-@samp{b}, @samp{f}, @file{G} contains the lines @samp{g}, @samp{b},
-@samp{g}, and @file{H} contains the lines @samp{a}, @samp{b},
-@samp{h}. @samp{diff3 F G H} might output the following:
-
-@example
-====2
-1:1c
-3:1c
- a
-2:1c
- g
-====
-1:3c
- f
-2:3c
- g
-3:3c
- h
-@end example
-
-@noindent
-because it found a two-way hunk containing @samp{a} in the first and
-third files and @samp{g} in the second file, then the single line
-@samp{b} common to all three files, then a three-way hunk containing
-the last line of each file.
-
-@node Example diff3 Normal
-@section An Example of @command{diff3} Normal Format
-
-Here is the output of the command @samp{diff3 lao tzu tao}
-(@pxref{Sample diff3 Input}, for the complete contents of the files).
-Notice that it shows only the lines that are different among the three
-files.
-
-@example
-====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
-@end example
-
-@node diff3 Merging
-@chapter Merging From a Common Ancestor
-@cindex merging from a common ancestor
-
-When two people have made changes to copies of the same file,
-@command{diff3} can produce a merged output that contains both sets of
-changes together with warnings about conflicts.
-
-One might imagine programs with names like @command{diff4} and @command{diff5}
-to compare more than three files simultaneously, but in practice the
-need rarely arises. You can use @command{diff3} to merge three or more
-sets of changes to a file by merging two change sets at a time.
-
-@command{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:
-
-@example
-diff3 @var{mine} @var{older} @var{yours}
-@end example
-
-@noindent
-You can remember the order of the arguments by noting that they are in
-alphabetical order.
-
-@cindex conflict
-@cindex overlap
-You can think of this as subtracting @var{older} from @var{yours} and
-adding the result to @var{mine}, or as merging into @var{mine} the
-changes that would turn @var{older} into @var{yours}. This merging is
-well-defined as long as @var{mine} and @var{older} match in the
-neighborhood of each such change. This fails to be true when all three
-input files differ or when only @var{older} differs; we call this
-a @dfn{conflict}. When all three input files differ, we call the
-conflict an @dfn{overlap}.
-
-@command{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 @samp{<<<<<<<} and @samp{>>>>>>>} lines.
-
-@command{diff3} can output the merge results as an @command{ed} script that
-that can be applied to the first file to yield the merged output.
-However, it is usually better to have @command{diff3} generate the merged
-output directly; this bypasses some problems with @command{ed}.
-
-@menu
-* Which Changes:: Selecting changes to incorporate.
-* Marking Conflicts:: Marking conflicts.
-* Bypassing ed:: Generating merged output directly.
-* Merging Incomplete Lines:: How @command{diff3} merges incomplete lines.
-* Saving the Changed File:: Emulating System V behavior.
-@end menu
-
-@node Which Changes
-@section Selecting Which Changes to Incorporate
-@cindex overlapping change, selection of
-@cindex unmerged change
-
-You can select all unmerged changes from @var{older} to @var{yours} for merging
-into @var{mine} with the @option{-e} or @option{--ed} option. You can
-select only the nonoverlapping unmerged changes with @option{-3} or
-@option{--easy-only}, and you can select only the overlapping changes with
-@option{-x} or @option{--overlap-only}.
-
-The @option{-e}, @option{-3} and @option{-x} options select only
-@dfn{unmerged changes}, i.e.@: changes where @var{mine} and @var{yours}
-differ; they ignore changes from @var{older} to @var{yours} where
-@var{mine} and @var{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 @option{-A} or @option{--show-all} option
-(@pxref{Marking Conflicts}).
-
-Here is the output of the command @command{diff3} with each of these three
-options (@pxref{Sample diff3 Input}, for the complete contents of the files).
-Notice that @option{-e} outputs the union of the disjoint sets of changes
-output by @option{-3} and @option{-x}.
-
-Output of @samp{diff3 -e lao tzu tao}:
-@example
-11a
-
- -- The Way of Lao-Tzu, tr. Wing-tsit Chan
-.
-8c
- so we may see their result.
-.
-@end example
-
-Output of @samp{diff3 -3 lao tzu tao}:
-@example
-8c
- so we may see their result.
-.
-@end example
-
-Output of @samp{diff3 -x lao tzu tao}:
-@example
-11a
-
- -- The Way of Lao-Tzu, tr. Wing-tsit Chan
-.
-@end example
-
-@node Marking Conflicts
-@section Marking Conflicts
-@cindex conflict marking
-@cindex @samp{<<<<<<<} for marking conflicts
-
-@command{diff3} can mark conflicts in the merged output by
-bracketing them with special marker lines. A conflict
-that comes from two files @var{A} and @var{B} is marked as follows:
-
-@example
-<<<<<<< @var{A}
-@r{lines from @var{A}}
-=======
-@r{lines from @var{B}}
->>>>>>> @var{B}
-@end example
-
-A conflict that comes from three files @var{A}, @var{B} and @var{C} is
-marked as follows:
-
-@example
-<<<<<<< @var{A}
-@r{lines from @var{A}}
-||||||| @var{B}
-@r{lines from @var{B}}
-=======
-@r{lines from @var{C}}
->>>>>>> @var{C}
-@end example
-
-The @option{-A} or @option{--show-all} option acts like the @option{-e}
-option, except that it brackets conflicts, and it outputs all changes
-from @var{older} to @var{yours}, not just the unmerged changes. Thus,
-given the sample input files (@pxref{Sample diff3 Input}), @samp{diff3
--A lao tzu tao} puts brackets around the conflict where only @file{tzu}
-differs:
-
-@example
-<<<<<<< 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
-@end example
-
-And it outputs the three-way conflict as follows:
-
-@example
-<<<<<<< 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
-@end example
-
-The @option{-E} or @option{--show-overlap} option outputs less information
-than the @option{-A} or @option{--show-all} option, because it outputs only
-unmerged changes, and it never outputs the contents of the second
-file. Thus the @option{-E} option acts like the @option{-e} option,
-except that it brackets the first and third files from three-way
-overlapping changes. Similarly, @option{-X} acts like @option{-x}, except
-it brackets all its (necessarily overlapping) changes. For example,
-for the three-way overlapping change above, the @option{-E} and @option{-X}
-options output the following:
-
-@example
-<<<<<<< lao
-=======
-
- -- The Way of Lao-Tzu, tr. Wing-tsit Chan
->>>>>>> tao
-@end example
-
-If you are comparing files that have meaningless or uninformative names,
-you can use the @option{-L @var{label}} or @option{--label=@var{label}}
-option to show alternate names in the @samp{<<<<<<<}, @samp{|||||||}
-and @samp{>>>>>>>} brackets. This option can be given up to three
-times, once for each input file. Thus @samp{diff3 -A -L X -L Y -L Z A
-B C} acts like @samp{diff3 -A A B C}, except that the output looks like
-it came from files named @samp{X}, @samp{Y} and @samp{Z} rather than
-from files named @samp{A}, @samp{B} and @samp{C}.
-
-@node Bypassing ed
-@section Generating the Merged Output Directly
-@cindex merged @command{diff3} format
-
-With the @option{-m} or @option{--merge} option, @command{diff3} outputs the
-merged file directly. This is more efficient than using @command{ed} to
-generate it, and works even with non-text files that @command{ed} would
-reject. If you specify @option{-m} without an @command{ed} script option,
-@option{-A} (@option{--show-all}) is assumed.
-
-For example, the command @samp{diff3 -m lao tzu tao}
-(@pxref{Sample diff3 Input} for a copy of the input files) would output
-the following:
-
-@example
-<<<<<<< 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
-@end example
-
-@node Merging Incomplete Lines
-@section How @command{diff3} Merges Incomplete Lines
-@cindex incomplete line merging
-
-With @option{-m}, incomplete lines (@pxref{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 @samp{|||||||}, @samp{=======} or @samp{>>>>>>>}
-brackets appear somewhere other than the start of a line because
-they are appended to the incomplete line.
-
-Without @option{-m}, if an @command{ed} script option is specified and an
-incomplete line is found, @command{diff3} generates a warning and acts as
-if a newline had been present.
-
-@node Saving the Changed File
-@section Saving the Changed File
-@cindex System V @command{diff3} compatibility
-
-Traditional Unix @command{diff3} generates an @command{ed} script without the
-trailing @samp{w} and @samp{q} commands that save the changes.
-System V @command{diff3} generates these extra commands. @sc{gnu}
-@command{diff3} normally behaves like traditional Unix
-@command{diff3}, but with the @option{-i} option it behaves like
-System V @command{diff3} and appends the @samp{w} and @samp{q}
-commands.
-
-The @option{-i} option requires one of the @command{ed} script options
-@option{-AeExX3}, and is incompatible with the merged output option
-@option{-m}.
-
-@node Interactive Merging
-@chapter Interactive Merging with @command{sdiff}
-@cindex diff merging
-@cindex interactive merging
-
-With @command{sdiff}, you can merge two files interactively based on a
-side-by-side @option{-y} format comparison (@pxref{Side by Side}). Use
-@option{-o @var{file}} or @option{--output=@var{file}} to specify where to
-put the merged text. @xref{Invoking sdiff}, for more details on the
-options to @command{sdiff}.
-
-Another way to merge files interactively is to use the Emacs Lisp
-package @command{emerge}. @xref{emerge, , emerge, emacs, The @sc{gnu} Emacs
-Manual}, for more information.
-
-@menu
-* sdiff Option Summary:: Summary of @command{sdiff} options.
-* Merge Commands:: Merging two files interactively.
-@end menu
-
-@node sdiff Option Summary
-@section Specifying @command{diff} Options to @command{sdiff}
-@cindex @command{sdiff} output format
-
-The following @command{sdiff} options have the same meaning as for
-@command{diff}. @xref{diff Options}, for the use of these options.
-
-@example
--a -b -d -i -t -v
--B -E -I @var{regexp}
-
---ignore-blank-lines --ignore-case
---ignore-matching-lines=@var{regexp} --ignore-space-change
---ignore-tab-expansion
---left-column --minimal --speed-large-files
---strip-trailing-cr --suppress-common-lines --expand-tabs
---text --version --width=@var{columns}
-@end example
-
-For historical reasons, @command{sdiff} has alternate names for some
-options. The @option{-l} option is equivalent to the
-@option{--left-column} option, and similarly @option{-s} is equivalent
-to @option{--suppress-common-lines}. The meaning of the @command{sdiff}
-@option{-w} and @option{-W} options is interchanged from that of
-@command{diff}: with @command{sdiff}, @option{-w @var{columns}} is
-equivalent to @option{--width=@var{columns}}, and @option{-W} is
-equivalent to @option{--ignore-all-space}. @command{sdiff} without the
-@option{-o} option is equivalent to @command{diff} with the @option{-y}
-or @option{--side-by-side} option (@pxref{Side by Side}).
-
-@node Merge Commands
-@section Merge Commands
-@cindex merge commands
-@cindex merging interactively
-
-Groups of common lines, with a blank gutter, are copied from the first
-file to the output. After each group of differing lines, @command{sdiff}
-prompts with @samp{%} and pauses, waiting for one of the following
-commands. Follow each command with @key{RET}.
-
-@table @samp
-@item e
-Discard both versions.
-Invoke a text editor on an empty temporary file,
-then copy the resulting file to the output.
-
-@item eb
-Concatenate the two versions, edit the result in a temporary file,
-then copy the edited result to the output.
-
-@item ed
-Like @samp{eb}, except precede each version with a header that
-shows what file and lines the version came from.
-
-@item el
-Edit a copy of the left version, then copy the result to the output.
-
-@item er
-Edit a copy of the right version, then copy the result to the output.
-
-@item l
-Copy the left version to the output.
-
-@item q
-Quit.
-
-@item r
-Copy the right version to the output.
-
-@item s
-Silently copy common lines.
-
-@item v
-Verbosely copy common lines. This is the default.
-@end table
-
-@vindex EDITOR
-The text editor invoked is specified by the @env{EDITOR} environment
-variable if it is set. The default is system-dependent.
-
-@node Merging with patch
-@chapter Merging with @command{patch}
-
-@command{patch} takes comparison output produced by @command{diff} and applies
-the differences to a copy of the original file, producing a patched
-version. With @command{patch}, you can distribute just the changes to a
-set of files instead of distributing the entire file set; your
-correspondents can apply @command{patch} to update their copy of the files
-with your changes. @command{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
-@command{patch}.
-
-@command{patch} detects and warns about common problems like forward
-patches. It saves any patches that it could not apply. It can also maintain a
-@code{patchlevel.h} file to ensure that your correspondents apply
-diffs in the proper order.
-
-@command{patch} accepts a series of diffs in its standard input, usually
-separated by headers that specify which file to patch. It applies
-@command{diff} hunks (@pxref{Hunks}) one by one. If a hunk does not
-exactly match the original file, @command{patch} uses heuristics to try to
-patch the file as well as it can. If no approximate match can be found,
-@command{patch} rejects the hunk and skips to the next hunk. @command{patch}
-normally replaces each file @var{f} with its new version, putting reject
-hunks (if any) into @samp{@var{f}.rej}.
-
-@xref{Invoking patch}, for detailed information on the options to
-@command{patch}.
-
-@menu
-* patch Input:: Selecting the type of @command{patch} input.
-* Revision Control:: Getting files from @sc{rcs}, @sc{sccs}, etc.
-* Imperfect:: Dealing with imperfect patches.
-* Creating and Removing:: Creating and removing files with a patch.
-* Patching Time Stamps:: Updating time stamps on patched files.
-* Multiple Patches:: Handling multiple patches in a file.
-* patch Directories:: Changing directory and stripping directories.
-* Backups:: Whether backup files are made.
-* Backup Names:: Backup file names.
-* Reject Names:: Reject file names.
-* patch Messages:: Messages and questions @command{patch} can produce.
-* patch and POSIX:: Conformance to the @sc{posix} standard.
-* patch and Tradition:: @sc{gnu} versus traditional @command{patch}.
-@end menu
-
-@node patch Input
-@section Selecting the @command{patch} Input Format
-@cindex @command{patch} input format
-
-@command{patch} normally determines which @command{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 @command{patch} to interpret the patch file as a
-certain format of diff. The output formats listed here are the only
-ones that @command{patch} can understand.
-
-@table @option
-@item -c
-@itemx --context
-context diff.
-
-@item -e
-@itemx --ed
-@command{ed} script.
-
-@item -n
-@itemx --normal
-normal diff.
-
-@item -u
-@itemx --unified
-unified diff.
-@end table
-
-@node Revision Control
-@section Revision Control
-@cindex revision control
-@cindex version control
-@cindex @sc{rcs}
-@cindex ClearCase
-@cindex @sc{sccs}
-
-If a nonexistent input file is under a revision control system
-supported by @command{patch}, @command{patch} normally asks the user
-whether to get (or check out) the file from the revision control
-system. Patch currently supports @sc{rcs}, ClearCase and @sc{sccs}.
-Under @sc{rcs} and @sc{sccs}, @command{patch} also asks when the input
-file is read-only and matches the default version in the revision
-control system.
-
-@vindex PATCH_GET
-The @option{-g @var{num}} or @option{--get=@var{num}} affects access
-to files under supported revision control systems. If @var{num} is
-positive, @command{patch} gets the file without asking the user; if
-zero, @command{patch} neither asks the user nor gets the file; and if
-negative, @command{patch} asks the user before getting the file. The
-default value of @var{num} is given by the value of the
-@env{PATCH_GET} environment variable if it is set; if not, the default
-value is zero if @command{patch} is conforming to @sc{posix}, negative
-otherwise. @xref{patch and POSIX}.
-
-@vindex VERSION_CONTROL
-The choice of revision control system is unaffected by the
-@env{VERSION_CONTROL} environment variable (@pxref{Backup Names}).
-
-@node Imperfect
-@section Applying Imperfect Patches
-@cindex imperfect patch application
-
-@command{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 @command{patch}, and it should work. If the
-entire diff is indented by a constant amount of white space,
-@command{patch} automatically ignores the indentation. If a context
-diff contains trailing carriage return on each line, @command{patch}
-automatically ignores the carriage return. If a context diff has been
-encapsulated by prepending @w{@samp{- }} to lines beginning with @samp{-}
-as per @uref{ftp://ftp.isi.edu/in-notes/rfc934.txt, Internet RFC 934},
-@command{patch} automatically unencapsulates the input.
-
-However, certain other types of imperfect input require user
-intervention or testing.
-
-@menu
-* Changed White Space:: When tabs and spaces don't match exactly.
-* Reversed Patches:: Applying reversed patches correctly.
-* Inexact:: Helping @command{patch} find close matches.
-* Dry Runs:: Predicting what @command{patch} will do.
-@end menu
-
-@node Changed White Space
-@subsection Applying Patches with Changed White Space
-@cindex white space in patches
-
-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 @command{patch} will not be able to match
-them properly. If this problem occurs, use the @option{-l} or
-@option{--ignore-white-space} option, which makes @command{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.
-
-@node Reversed Patches
-@subsection Applying Reversed Patches
-@cindex reversed patches
-
-Sometimes people run @command{diff} with the new file first instead of
-second. This creates a diff that is ``reversed''. To apply such
-patches, give @command{patch} the @option{-R} or @option{--reverse} option.
-@command{patch} then attempts to swap each hunk around before applying it.
-Rejects come out in the swapped format.
-
-Often @command{patch} can guess that the patch is reversed. If the first
-hunk of a patch fails, @command{patch} reverses the hunk to see if it can
-apply it that way. If it can, @command{patch} asks you if you want to have
-the @option{-R} option set; if it can't, @command{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
-@command{patch} notices.
-
-If you apply a patch that you have already applied, @command{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 @samp{n} to this offer and to
-the subsequent ``apply anyway'' question---or type @kbd{C-c} to kill the
-@command{patch} process.
-
-@node Inexact
-@subsection Helping @command{patch} Find Inexact Matches
-@cindex inexact patches
-@cindex fuzz factor when patching
-
-For context diffs, and to a lesser extent normal diffs, @command{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, @command{patch} scans both forward and backward for a
-set of lines matching the context given in the hunk.
-
-First @command{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
-@command{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.
-
-The @option{-F @var{lines}} or @option{--fuzz=@var{lines}} option sets the
-maximum fuzz factor to @var{lines}. This option only applies to context
-and unified diffs; it ignores up to @var{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.
-
-If @command{patch} cannot find a place to install a hunk of the patch, it
-writes the hunk out to a reject file (@pxref{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 @command{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 @command{patch}
-thinks the failed hunks belong in the new file rather than in the old
-one.
-
-If the @option{--verbose} option is given, then
-as it completes each hunk @command{patch} tells you whether the hunk
-succeeded or failed, and if it failed, on which line (in the new file)
-@command{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 @emph{may} indicate that @command{patch} installed a hunk in
-the wrong place. @command{patch} also tells you if it used a fuzz factor
-to make the match, in which case you should also be slightly suspicious.
-
-@command{patch} cannot tell if the line numbers are off in an @command{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.
-
-A patch against an empty file applies to a nonexistent file, and vice
-versa. @xref{Creating and Removing}.
-
-@command{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.
-
-@node Dry Runs
-@subsection Predicting what @command{patch} will do
-@cindex testing @command{patch}
-@cindex dry runs for @command{patch}
-
-It may not be obvious in advance what @command{patch} will do with a
-complicated or poorly formatted patch. If you are concerned that the
-input might cause @command{patch} to modify the wrong files, you can
-use the @option{--dry-run} option, which causes @command{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 @command{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 @command{patch}) and try another dry run. Once
-you are satisfied with the proposed patch you can apply it by invoking
-@command{patch} as before, but this time without the
-@option{--dry-run} option.
-
-@node Creating and Removing
-@section Creating and Removing Files
-@cindex creating files
-@cindex empty files, removing
-@cindex removing empty files
-
-Sometimes when comparing two directories, a file may exist in one
-directory but not the other. If you give @command{diff} the
-@option{-N} or @option{--new-file} option, or if you supply an old or
-new file that is named @file{/dev/null} or is empty and is dated the
-Epoch (1970-01-01 00:00:00 UTC), @command{diff} outputs a patch that
-adds or deletes the contents of this file. When given such a patch,
-@command{patch} normally creates a new file or removes the old file.
-However, when conforming to @sc{posix} (@pxref{patch and POSIX}),
-@command{patch} does not remove the old file, but leaves it empty.
-The @option{-E} or @option{--remove-empty-files} option causes
-@command{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.
-
-If the patch appears to create a file that already exists,
-@command{patch} asks for confirmation before applying the patch.
-
-@node Patching Time Stamps
-@section Updating Time Stamps on Patched Files
-@cindex time stamps on patched files
-
-When @command{patch} updates a file, it normally sets the file's
-last-modified time stamp to the current time of day. If you are using
-@command{patch} to track a software distribution, this can cause
-@command{make} to incorrectly conclude that a patched file is out of
-date. For example, if @file{syntax.c} depends on @file{syntax.y}, and
-@command{patch} updates @file{syntax.c} and then @file{syntax.y}, then
-@file{syntax.c} will normally appear to be out of date with respect to
-@file{syntax.y} even though its contents are actually up to date.
-
-The @option{-Z} or @option{--set-utc} option causes @command{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 (@sc{utc}, often known as @sc{gmt}).
-
-The @option{-T} or @option{--set-time} option acts like @option{-Z} or
-@option{--set-utc}, except that it assumes that the context diff
-headers' time stamps use local time instead of @sc{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 @option{-Z} or @option{--set-utc}.
-
-@command{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 @option{-f} or @option{--force}
-option is given, the file's time stamps are set regardless.
-
-Due to the limitations of the current @command{diff} format,
-@command{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 @samp{make
-clean}) all files that depend on the patched files, so that later
-invocations of @command{make} do not get confused by the patched
-files' times.
-
-@node Multiple Patches
-@section Multiple Patches in a File
-@cindex multiple patches
-@cindex intuiting file names from patches
-
-If the patch file contains more than one patch, and if you do not
-specify an input file on the command line, @command{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 (@pxref{Making Patches}, for more on
-that topic).
-
-@command{patch} uses the following rules to intuit a file name from
-the leading text before a patch. First, @command{patch} takes an
-ordered list of candidate file names as follows:
-
-@itemize @bullet
-@item
-If the header is that of a context diff, @command{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 @option{-p@var{num}} or
-@option{--strip=@var{num}} option. The name @file{/dev/null} is also
-ignored.
-
-@item
-If there is an @samp{Index:} line in the leading garbage and if either
-the old and new names are both absent or if @command{patch} is
-conforming to @sc{posix}, @command{patch} takes the name in the
-@samp{Index:} line.
-
-@item
-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.
-@end itemize
-
-@noindent
-Then @command{patch} selects a file name from the candidate list as
-follows:
-
-@itemize @bullet
-@item
-If some of the named files exist, @command{patch} selects the first
-name if conforming to @sc{posix}, and the best name otherwise.
-
-@item
-If @command{patch} is not ignoring @sc{rcs}, ClearCase, and @sc{sccs}
-(@pxref{Revision Control}), and no named files exist but an @sc{rcs},
-ClearCase, or @sc{sccs} master is found, @command{patch} selects the
-first named file with an @sc{rcs}, ClearCase, or @sc{sccs} master.
-
-@item
-If no named files exist, no @sc{rcs}, ClearCase, or @sc{sccs} master
-was found, some names are given, @command{patch} is not conforming to
-@sc{posix}, and the patch appears to create a file, @command{patch}
-selects the best name requiring the creation of the fewest
-directories.
-
-@item
-If no file name results from the above heuristics, you are asked for
-the name of the file to patch, and @command{patch} selects that name.
-@end itemize
-
-To determine the @dfn{best} of a nonempty list of file names,
-@command{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.
-
-@xref{patch and POSIX}, to see whether @command{patch} is conforming
-to @sc{posix}.
-
-@node patch Directories
-@section Applying Patches in Other Directories
-@cindex directories and patch
-@cindex patching directories
-
-The @option{-d @var{directory}} or @option{--directory=@var{directory}}
-option to @command{patch} makes directory @var{directory} the current
-directory for interpreting both file names in the patch file, and file
-names given as arguments to other options (such as @option{-B} and
-@option{-o}). For example, while in a mail reading program, you can patch
-a file in the @file{/usr/src/emacs} directory directly from a message
-containing the patch like this:
-
-@example
-| patch -d /usr/src/emacs
-@end example
-
-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
-@option{-p@var{number}} or @option{--strip=@var{number}}
-option to set the file name strip count to @var{number}. The strip
-count tells @command{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, @command{patch} strips off all leading directories, leaving
-just the base file names.
-
-For example, suppose the file name in the patch file is
-@file{/gnu/src/emacs/etc/NEWS}. Using @option{-p0} gives the
-entire file name unmodified, @option{-p1} gives
-@file{gnu/src/emacs/etc/NEWS} (no leading slash), @option{-p4} gives
-@file{etc/NEWS}, and not specifying @option{-p} at all gives @file{NEWS}.
-
-@command{patch} looks for each file (after any slashes have been stripped)
-in the current directory, or if you used the @option{-d @var{directory}}
-option, in that directory.
-
-@node Backups
-@section Backup Files
-@cindex backup file strategy
-
-Normally, @command{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
-@samp{patch -R} (@pxref{Reversed Patches}). However, when conforming
-to @sc{posix}, @command{patch} does not create backup files by
-default. @xref{patch and POSIX}.
-
-The @option{-b} or @option{--backup} option causes @command{patch} to
-make a backup file regardless of whether the patch matches the
-original input. The @option{--backup-if-mismatch} option causes
-@command{patch} to create backup files for mismatches files; this is
-the default when not conforming to @sc{posix}. The
-@option{--no-backup-if-mismatch} option causes @command{patch} to not
-create backup files, even for mismatched patches; this is the default
-when conforming to @sc{posix}.
-
-When backing up a file that does not exist, an empty, unreadable
-backup file is created as a placeholder to represent the nonexistent
-file.
-
-@node Backup Names
-@section Backup File Names
-@cindex backup file names
-
-Normally, @command{patch} renames an original input file into a backup
-file by appending to its name the extension @samp{.orig}, or @samp{~}
-if using @samp{.orig} would make the backup file name too
-long.@footnote{A coding error in @sc{gnu} @command{patch} version
-2.5.4 causes it to always use @samp{~}, but this should be fixed in
-the next release.} The @option{-z @var{backup-suffix}} or
-@option{--suffix=@var{backup-suffix}} option causes @command{patch} to
-use @var{backup-suffix} as the backup extension instead.
-
-@vindex SIMPLE_BACKUP_SUFFIX
-Alternately, you can specify the extension for backup files with the
-@env{SIMPLE_BACKUP_SUFFIX} environment variable, which the options
-override.
-
-@command{patch} can also create numbered backup files the way @sc{gnu} Emacs
-does. With this method, instead of having a single backup of each file,
-@command{patch} makes a new backup file name each time it patches a file.
-For example, the backups of a file named @file{sink} would be called,
-successively, @file{sink.~1~}, @file{sink.~2~}, @file{sink.~3~}, etc.
-
-@vindex PATCH_VERSION_CONTROL
-@vindex VERSION_CONTROL
-The @option{-V @var{backup-style}} or
-@option{--version-control=@var{backup-style}} option takes as an
-argument a method for creating backup file names. You can alternately
-control the type of backups that @command{patch} makes with the
-@env{PATCH_VERSION_CONTROL} environment variable, which the
-@option{-V} option overrides. If @env{PATCH_VERSION_CONTROL} is not
-set, the @env{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
-(@pxref{Revision Control}).
-
-The values of these environment variables and the argument to the
-@option{-V} option are like the @sc{gnu} Emacs @code{version-control}
-variable (@pxref{Backup Names, , , emacs, The @sc{gnu} Emacs Manual},
-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.
-
-@table @option
-@item t
-@itemx numbered
-Always make numbered backups.
-
-@item nil
-@itemx existing
-Make numbered backups of files that already have them, simple backups of
-the others. This is the default.
-
-@item never
-@itemx simple
-Always make simple backups.
-@end table
-
-You can also tell @command{patch} to prepend a prefix, such as a
-directory name, to produce backup file names. The @option{-B
-@var{prefix}} or @option{--prefix=@var{prefix}} option makes backup
-files by prepending @var{prefix} to them. The @option{-Y
-@var{prefix}} or @option{--basename-prefix=@var{prefix}} prepends
-@var{prefix} to the last file name component of backup file names
-instead; for example, @option{-Y ~} causes the backup name for
-@file{dir/file.c} to be @file{dir/~file.c}. If you use either of
-these prefix options, the suffix-based options are ignored.
-
-If you specify the output file with the @option{-o} option, that file is
-the one that is backed up, not the input file.
-
-Options that affect the names of backup files do not affect whether
-backups are made. For example, if you specify the
-@option{--no-backup-if-mismatch} option, none of the options described
-in this section have any affect, because no backups are made.
-
-@node Reject Names
-@section Reject File Names
-@cindex reject file names
-
-The names for reject files (files containing patches that
-@command{patch} could not find a place to apply) are normally the name
-of the output file with @samp{.rej} appended (or @samp{#} if if using
-@samp{.rej} would make the backup file name too long).
-
-Alternatively, you can tell @command{patch} to place all of the rejected
-patches in a single file. The @option{-r @var{reject-file}} or
-@option{--reject-file=@var{reject-file}} option uses @var{reject-file} as
-the reject file name.
-
-@node patch Messages
-@section Messages and Questions from @command{patch}
-@cindex @command{patch} messages and questions
-@cindex diagnostics from @command{patch}
-@cindex messages from @command{patch}
-
-@command{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, @command{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.
-
-@menu
-* More or Fewer Messages:: Controlling the verbosity of @command{patch}.
-* patch and Keyboard Input:: Inhibiting keyboard input.
-* patch Quoting Style:: Quoting file names in diagnostics.
-@end menu
-
-@command{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.
-
-@node More or Fewer Messages
-@subsection Controlling the Verbosity of @command{patch}
-@cindex verbose messages from @command{patch}
-@cindex inhibit messages from @command{patch}
-
-You can cause @command{patch} to produce more messages by using the
-@option{--verbose} option. For example, when you give this option,
-the message @samp{Hmm...} indicates that @command{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.
-
-You can inhibit all terminal output from @command{patch}, unless an error
-occurs, by using the @option{-s}, @option{--quiet}, or @option{--silent}
-option.
-
-@node patch and Keyboard Input
-@subsection Inhibiting Keyboard Input
-@cindex keyboard input to @command{patch}
-
-There are two ways you can prevent @command{patch} from asking you any
-questions. The @option{-f} or @option{--force} option assumes that you know
-what you are doing. It causes @command{patch} to do the following:
-
-@itemize @bullet
-@item
-Skip patches that do not contain file names in their headers.
-
-@item
-Patch files even though they have the wrong version for the
-@samp{Prereq:} line in the patch;
-
-@item
-Assume that patches are not reversed even if they look like they are.
-@end itemize
-
-@noindent
-The @option{-t} or @option{--batch} option is similar to @option{-f}, in that
-it suppresses questions, but it makes somewhat different assumptions:
-
-@itemize @bullet
-@item
-Skip patches that do not contain file names in their headers
-(the same as @option{-f}).
-
-@item
-Skip patches for which the file has the wrong version for the
-@samp{Prereq:} line in the patch;
-
-@item
-Assume that patches are reversed if they look like they are.
-@end itemize
-
-@node patch Quoting Style
-@subsection @command{patch} Quoting Style
-@cindex quoting style
-
-When @command{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
-@option{--quoting-style=@var{word}} option controls how names are
-output. The @var{word} should be one of the following:
-
-@table @samp
-@item literal
-Output names as-is.
-@item shell
-Quote names for the shell if they contain shell metacharacters or would
-cause ambiguous output.
-@item shell-always
-Quote names for the shell, even if they would normally not require quoting.
-@item c
-Quote names as for a C language string.
-@item escape
-Quote as with @samp{c} except omit the surrounding double-quote
-characters.
-@c The following are not yet implemented in patch 2.5.4.
-@c @item clocale
-@c Quote as with @samp{c} except use quotation marks appropriate for the
-@c locale.
-@c @item locale
-@c @c Use @t instead of @samp to avoid duplicate quoting in some output styles.
-@c Like @samp{clocale}, but quote @t{`like this'} instead of @t{"like
-@c this"} in the default C locale. This looks nicer on many displays.
-@end table
-
-@vindex QUOTING_STYLE
-You can specify the default value of the @option{--quoting-style}
-option with the environment variable @env{QUOTING_STYLE}. If that
-environment variable is not set, the default value is @samp{shell},
-but this default may change in a future version of @command{patch}.
-
-@node patch and POSIX
-@section @command{patch} and the @sc{posix} Standard
-@cindex @sc{posix}
-
-@vindex POSIXLY_CORRECT
-If you specify the @option{--posix} option, or set the
-@env{POSIXLY_CORRECT} environment variable, @command{patch} conforms
-more strictly to the @sc{posix} standard, as follows:
-
-@itemize @bullet
-@item
-Take the first existing file from the list (old, new, index)
-when intuiting file names from diff headers. @xref{Multiple Patches}.
-
-@item
-Do not remove files that are removed by a diff.
-@xref{Creating and Removing}.
-
-@item
-Do not ask whether to get files from @sc{rcs}, ClearCase, or
-@sc{sccs}. @xref{Revision Control}.
-
-@item
-Require that all options precede the files in the command line.
-
-@item
-Do not backup files, even when there is a mismatch. @xref{Backups}.
-
-@end itemize
-
-@node patch and Tradition
-@section @sc{gnu} @command{patch} and Traditional @command{patch}
-@cindex traditional @command{patch}
-
-The current version of @sc{gnu} @command{patch} normally follows the
-@sc{posix} standard. @xref{patch and POSIX}, for the few exceptions
-to this general rule.
-
-Unfortunately, @sc{posix} redefined the behavior of @command{patch} in
-several important ways. You should be aware of the following
-differences if you must interoperate with traditional @command{patch},
-or with @sc{gnu} @command{patch} version 2.1 and earlier.
-
-@itemize @bullet
-@item
-In traditional @command{patch}, the @option{-p} option's operand was
-optional, and a bare @option{-p} was equivalent to @option{-p0}. The
-@option{-p} option now requires an operand, and @option{-p@ 0} is now
-equivalent to @option{-p0}. For maximum compatibility, use options
-like @option{-p0} and @option{-p1}.
-
-Also, traditional @command{patch} simply counted slashes when
-stripping path prefixes; @command{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 @file{//} in file names.
-
-@item
-In traditional @command{patch}, backups were enabled by default. This
-behavior is now enabled with the @option{-b} or @option{--backup}
-option.
-
-Conversely, in @sc{posix} @command{patch}, backups are never made,
-even when there is a mismatch. In @sc{gnu} @command{patch}, this
-behavior is enabled with the @option{--no-backup-if-mismatch} option,
-or by conforming to @sc{posix}.
-
-The @option{-b@ @var{suffix}} option of traditional @command{patch} is
-equivalent to the @samp{-b -z@ @var{suffix}} options of @sc{gnu}
-@command{patch}.
-
-@item
-Traditional @command{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 @sc{posix}, and had
-a few gotchas. Now @command{patch} uses a different, equally
-complicated (but better documented) method that is optionally
-@sc{posix}-conforming; we hope it has fewer gotchas. The two methods
-are compatible if the file names in the context diff header and the
-@samp{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.
-
-@item
-When traditional @command{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, @file{/dev/tty}, and standard input. Now
-@command{patch} sends questions to standard output and gets answers
-from @file{/dev/tty}. Defaults for some answers have been changed so
-that @command{patch} never goes into an infinite loop when using
-default answers.
-
-@item
-Traditional @command{patch} exited with a status value that counted
-the number of bad hunks, or with status 1 if there was real trouble.
-Now @command{patch} exits with status 1 if some hunks failed, or with
-2 if there was real trouble.
-
-@item
-Limit yourself to the following options when sending instructions
-meant to be executed by anyone running @sc{gnu} @command{patch},
-traditional @command{patch}, or a @command{patch} that conforms to
-@sc{posix}. Spaces are significant in the following list, and
-operands are required.
-
-@example
-@option{-c}
-@option{-d @var{dir}}
-@option{-D @var{define}}
-@option{-e}
-@option{-l}
-@option{-n}
-@option{-N}
-@option{-o @var{outfile}}
-@option{-p@var{num}}
-@option{-R}
-@option{-r @var{rejectfile}}
-@end example
-
-@end itemize
-
-@node Making Patches
-@chapter 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.
-
-Here are some other things you should keep in mind if you are going to
-distribute patches for updating a software package.
-
-@menu
-* Tips for Patch Producers:: Advice for making patches.
-* Tips for Patch Consumers:: Advice for using patches.
-* Avoiding Common Mistakes:: Avoiding common mistakes when using @command{patch}.
-* Generating Smaller Patches:: How to generate smaller patches.
-@end menu
-
-@node Tips for Patch Producers
-@section Tips for Patch Producers
-@cindex patch producer tips
-
-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
-@command{tar} archives of the two versions.
-
-To generate the patch, use the command @samp{diff -Naur @var{old}
-@var{new}} where @var{old} and @var{new} identify the old and new
-directories. The names @var{old} and @var{new} should not contain any
-slashes. The @option{-N} option lets the patch create and remove
-files; @option{-a} lets the patch update non-text files; @option{-u}
-generates useful time stamps and enough context; and @option{-r} lets
-the patch update subdirectories. Here is an example command, using
-Bourne shell syntax:
-
-@example
-diff -Naur gcc-3.0.3 gcc-3.0.4
-@end example
-
-Tell your recipients how to apply the patches. This should include
-which working directory to use, and which @command{patch} options to
-use; the option @samp{-p1} is recommended. Test your procedure by
-pretending to be a recipient and applying your patches to a copy of
-the original files.
-
-@xref{Avoiding Common Mistakes}, for how to avoid common mistakes when
-generating a patch.
-
-@node Tips for Patch Consumers
-@section Tips for Patch Consumers
-@cindex patch consumer tips
-
-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.
-
-@sc{gnu} @command{diff} can analyze files with arbitrarily long lines
-and files that end in incomplete lines. However, older versions of
-@command{patch} cannot patch such files. If you are having trouble
-applying such patches, try upgrading to a recent version of @sc{gnu}
-@command{patch}.
-
-@node Avoiding Common Mistakes
-@section Avoiding Common Mistakes
-@cindex common mistakes with patches
-@cindex patch, common mistakes
-
-When producing a patch for multiple files, apply @command{diff} to
-directories whose names do not have slashes. This reduces confusion
-when the patch consumer specifies the @option{-p@var{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:
-
-@example
-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
-@end example
-
-@noindent
-because the two file names have different numbers of slashes, and
-different versions of @command{patch} interpret the file names
-differently. To avoid confusion, send output that looks like this
-instead:
-
-@example
-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
-@end example
-
-Make sure you have specified the file names correctly, either in a
-context diff header or with an @samp{Index:} line. Take care to not send out
-reversed patches, since these make people wonder whether they have
-already applied the patch.
-
-Avoid sending patches that compare backup file names like
-@file{README.orig} or @file{README~}, since this might confuse
-@command{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.@: @file{old/README} and @file{new/README}.
-
-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 @file{patchlevel.h} or
-@file{version.c}, which contains a patch level or version number. If
-the input file contains the wrong version number, @command{patch} will
-complain immediately.
-
-An even clearer way to prevent this problem is to put a @samp{Prereq:}
-line before the patch. If the leading text in the patch file contains a
-line that starts with @samp{Prereq:}, @command{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, @command{patch} prompts you for
-confirmation before proceeding. This makes it difficult to accidentally
-apply patches in the wrong order.
-
-@node Generating Smaller Patches
-@section Generating Smaller Patches
-@cindex patches, shrinking
-
-The simplest way to generate a patch is to use @samp{diff -Naur}
-(@pxref{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 @command{rm} and @command{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.
-
-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,
-@file{TAGS} and output from @command{yacc} and @command{makeinfo}),
-exclude them from the patch by giving @command{diff} the @option{-x
-@var{pattern}} option (@pxref{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 @command{make}.
-
-Now you can create the patch using @samp{diff -Naur}. Make sure to
-specify the scratch directory first and the newer directory second.
-
-Add to the top of the patch a note telling the user any @command{rm} and
-@command{mv} commands to run before applying the patch. Then you can
-remove the scratch directory.
-
-You can also shrink the patch size by using fewer lines of context,
-but bear in mind that @command{patch} typically needs at least two
-lines for proper operation when patches do not exactly match the input
-files.
-
-@node Invoking cmp
-@chapter Invoking @command{cmp}
-@cindex invoking @command{cmp}
-@cindex @command{cmp} invocation
-
-The @command{cmp} command compares two files, and if they differ,
-tells the first byte and line number where they differ. Bytes and
-lines are numbered starting with 1. The arguments of @command{cmp}
-are as follows:
-
-@example
-cmp @var{options}@dots{} @var{from-file} @r{[}@var{to-file} @r{[}@var{from-skip} @r{[}@var{to-skip}@r{]}@r{]}@r{]}
-@end example
-
-The file name @file{-} is always the standard input. @command{cmp}
-also uses the standard input if one file name is omitted. The
-@var{from-skip} and @var{to-skip} operands specify how many bytes to
-ignore at the start of each file; they are equivalent to the
-@option{--ignore-initial=@var{from-skip}:@var{to-skip}} option.
-
-An exit status of 0 means no differences were found, 1 means some
-differences were found, and 2 means trouble.
-
-@menu
-* cmp Options:: Summary of options to @command{cmp}.
-@end menu
-
-@node cmp Options
-@section Options to @command{cmp}
-@cindex @command{cmp} options
-@cindex options for @command{cmp}
-
-Below is a summary of all of the options that @sc{gnu} @command{cmp} accepts.
-Most options have two equivalent names, one of which is a single letter
-preceded by @samp{-}, and the other of which is a long name preceded by
-@samp{--}. Multiple single letter options (unless they take an
-argument) can be combined into a single command line word: @option{-bl} is
-equivalent to @option{-b -l}.
-
-@table @option
-@item -b
-@itemx --print-bytes
-Print the differing bytes. Display control bytes as a
-@samp{^} followed by a letter of the alphabet and precede bytes
-that have the high bit set with @samp{M-} (which stands for ``meta'').
-
-@item --help
-Output a summary of usage and then exit.
-
-@item -i @var{skip}
-@itemx --ignore-initial=@var{skip}
-Ignore any differences in the first @var{skip} bytes of the input
-files. Treat files with fewer than @var{skip} bytes as if they are
-empty. If @var{skip} is of the form
-@option{@var{from-skip}:@var{to-skip}}, skip the first @var{from-skip}
-bytes of the first input file and the first @var{to-skip} bytes of the
-second.
-
-@item -l
-@itemx --verbose
-Print the (decimal) byte numbers and (octal) values of all differing bytes.
-
-@item -n @var{count}
-@itemx --bytes=@var{count}
-Compare at most @var{count} input bytes.
-
-@item -s
-@itemx --quiet
-@itemx --silent
-Do not print anything; only return an exit status indicating whether
-the files differ.
-
-@item -v
-@itemx --version
-Output version information and then exit.
-@end table
-
-In the above table, operands that are byte counts are normally
-decimal, but may be preceded by @samp{0} for octal and @samp{0x} for
-hexadecimal.
-
-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 @samp{iB}, specifies a multiple using
-powers of 1024. A size letter followed by @samp{B} specifies powers
-of 1000 instead. For example, @option{-n 4M} and @option{-n 4MiB} are
-equivalent to @option{-n 4194304}, whereas @option{-n 4MB} is
-equivalent to @option{-n 4000000}. This notation is upward compatible
-with the @uref{http://www.bipm.fr/enus/3_SI/si-prefixes.html, SI
-prefixes} for decimal multiples and with the
-@uref{http://physics.nist.gov/cuu/Units/binary.html, IEC 60027-2
-prefixes for binary multiples}.
-
-The following suffixes are defined. Large sizes like @code{1Y} may be
-rejected by your computer due to limitations of its arithmetic.
-
-@table @samp
-@item kB
-@cindex kilobyte, definition of
-kilobyte: @math{10^3 = 1000}.
-@item k
-@itemx K
-@itemx KiB
-@cindex kibibyte, definition of
-kibibyte: @math{2^10 = 1024}. @samp{K} is special: the SI prefix is
-@samp{k} and the IEC 60027-2 prefix is @samp{Ki}, but tradition and
-@sc{posix} use @samp{k} to mean @samp{KiB}.
-@item MB
-@cindex megabyte, definition of
-megabyte: @math{10^6 = 1,000,000}.
-@item M
-@itemx MiB
-@cindex mebibyte, definition of
-mebibyte: @math{2^20 = 1,048,576}.
-@item GB
-@cindex gigabyte, definition of
-gigabyte: @math{10^9 = 1,000,000,000}.
-@item G
-@itemx GiB
-@cindex gibibyte, definition of
-gibibyte: @math{2^30 = 1,073,741,824}.
-@item TB
-@cindex terabyte, definition of
-terabyte: @math{10^12 = 1,000,000,000,000}.
-@item T
-@itemx TiB
-@cindex tebibyte, definition of
-tebibyte: @math{2^40 = 1,099,511,627,776}.
-@item PB
-@cindex petabyte, definition of
-petabyte: @math{10^15 = 1,000,000,000,000,000}.
-@item P
-@itemx PiB
-@cindex pebibyte, definition of
-pebibyte: @math{2^50 = 1,125,899,906,842,624}.
-@item EB
-@cindex exabyte, definition of
-exabyte: @math{10^18 = 1,000,000,000,000,000,000}.
-@item E
-@itemx EiB
-@cindex exbibyte, definition of
-exbibyte: @math{2^60 = 1,152,921,504,606,846,976}.
-@item ZB
-@cindex zettabyte, definition of
-zettabyte: @math{10^21 = 1,000,000,000,000,000,000,000}
-@item Z
-@itemx ZiB
-@math{2^70 = 1,180,591,620,717,411,303,424}.
-(@samp{Zi} is a GNU extension to IEC 60027-2.)
-@item YB
-@cindex yottabyte, definition of
-yottabyte: @math{10^24 = 1,000,000,000,000,000,000,000,000}.
-@item Y
-@itemx YiB
-@math{2^80 = 1,208,925,819,614,629,174,706,176}.
-(@samp{Yi} is a GNU extension to IEC 60027-2.)
-@end table
-
-@node Invoking diff
-@chapter Invoking @command{diff}
-@cindex invoking @command{diff}
-@cindex @command{diff} invocation
-
-The format for running the @command{diff} command is:
-
-@example
-diff @var{options}@dots{} @var{files}@dots{}
-@end example
-
-In the simplest case, two file names @var{from-file} and
-@var{to-file} are given, and @command{diff} compares the contents of
-@var{from-file} and @var{to-file}. A file name of @file{-} stands for
-text read from the standard input. As a special case, @samp{diff - -}
-compares a copy of standard input to itself.
-
-If one file is a directory and the other is not, @command{diff} compares
-the file in the directory whose name is that of the non-directory.
-The non-directory file must not be @file{-}.
-
-If two file names are given and both are directories,
-@command{diff} compares corresponding files in both directories, in
-alphabetical order; this comparison is not recursive unless the
-@option{-r} or @option{--recursive} option is given. @command{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 ``file with the same name'' does not
-apply.
-
-If the @option{--from-file=@var{file}} option is given, the number of
-file names is arbitrary, and @var{file} is compared to each named file.
-Similarly, if the @option{--to-file=@var{file}} option is given, each
-named file is compared to @var{file}.
-
-@command{diff} options begin with @samp{-}, so normally file names
-may not begin with @samp{-}. However, @option{--} as an
-argument by itself treats the remaining arguments as file names even if
-they begin with @samp{-}.
-
-An exit status of 0 means no differences were found, 1 means some
-differences were found, and 2 means trouble.
-
-@menu
-* diff Options:: Summary of options to @command{diff}.
-@end menu
-
-@node diff Options
-@section Options to @command{diff}
-@cindex @command{diff} options
-@cindex options for @command{diff}
-
-Below is a summary of all of the options that @sc{gnu} @command{diff} accepts.
-Most options have two equivalent names, one of which is a single letter
-preceded by @samp{-}, and the other of which is a long name preceded by
-@samp{--}. Multiple single letter options (unless they take an
-argument) can be combined into a single command line word: @option{-ac} is
-equivalent to @option{-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.
-
-@table @option
-@item -a
-@itemx --text
-Treat all files as text and compare them line-by-line, even if they
-do not seem to be text. @xref{Binary}.
-
-@item -b
-@itemx --ignore-space-change
-Ignore changes in amount of white space. @xref{White Space}.
-
-@item -B
-@itemx --ignore-blank-lines
-Ignore changes that just insert or delete blank lines. @xref{Blank
-Lines}.
-
-@item --binary
-Read and write data in binary mode. @xref{Binary}.
-
-@item -c
-Use the context output format, showing three lines of context.
-@xref{Context Format}.
-
-@item -C @var{lines}
-@itemx --context@r{[}=@var{lines}@r{]}
-Use the context output format, showing @var{lines} (an integer) lines of
-context, or three if @var{lines} is not given. @xref{Context Format}.
-For proper operation, @command{patch} typically needs at least two lines of
-context.
-
-On older systems, @command{diff} supports an obsolete option
-@option{-@var{lines}} that has effect when combined with @option{-c}
-or @option{-p}. @sc{posix} 1003.1-2001 (@pxref{Standards
-conformance}) does not allow this; use @option{-C @var{lines}}
-instead.
-
-@item --changed-group-format=@var{format}
-Use @var{format} to output a line group containing differing lines from
-both files in if-then-else format. @xref{Line Group Formats}.
-
-@item -d
-@itemx --minimal
-Change the algorithm perhaps find a smaller set of changes. This makes
-@command{diff} slower (sometimes much slower). @xref{diff Performance}.
-
-@item -D @var{name}
-@itemx --ifdef=@var{name}
-Make merged @samp{#ifdef} format output, conditional on the preprocessor
-macro @var{name}. @xref{If-then-else}.
-
-@item -e
-@itemx --ed
-Make output that is a valid @command{ed} script. @xref{ed Scripts}.
-
-@item -E
-@itemx --ignore-tab-expansion
-Ignore changes due to tab expansion.
-@xref{White Space}.
-
-@item -f
-@itemx --forward-ed
-Make output that looks vaguely like an @command{ed} script but has changes
-in the order they appear in the file. @xref{Forward ed}.
-
-@item -F @var{regexp}
-@itemx --show-function-line=@var{regexp}
-In context and unified format, for each hunk of differences, show some
-of the last preceding line that matches @var{regexp}. @xref{Specified
-Headings}.
-
-@item --from-file=@var{file}
-Compare @var{file} to each operand; @var{file} may be a directory.
-
-@item --help
-Output a summary of usage and then exit.
-
-@item --horizon-lines=@var{lines}
-Do not discard the last @var{lines} lines of the common prefix
-and the first @var{lines} lines of the common suffix.
-@xref{diff Performance}.
-
-@item -i
-@itemx --ignore-case
-Ignore changes in case; consider upper- and lower-case letters
-equivalent. @xref{Case Folding}.
-
-@item -I @var{regexp}
-@itemx --ignore-matching-lines=@var{regexp}
-Ignore changes that just insert or delete lines that match @var{regexp}.
-@xref{Specified Folding}.
-
-@item --ignore-file-name-case
-Ignore case when comparing file names during recursive comparison.
-@xref{Comparing Directories}.
-
-@item -l
-@itemx --paginate
-Pass the output through @command{pr} to paginate it. @xref{Pagination}.
-
-@item --label=@var{label}
-Use @var{label} instead of the file name in the context format
-(@pxref{Context Format}) and unified format (@pxref{Unified Format})
-headers. @xref{RCS}.
-
-@item --left-column
-Print only the left column of two common lines in side by side format.
-@xref{Side by Side Format}.
-
-@item --line-format=@var{format}
-Use @var{format} to output all input lines in if-then-else format.
-@xref{Line Formats}.
-
-@item -n
-@itemx --rcs
-Output @sc{rcs}-format diffs; like @option{-f} except that each command
-specifies the number of lines affected. @xref{RCS}.
-
-@item -N
-@itemx --new-file
-In directory comparison, if a file is found in only one directory,
-treat it as present but empty in the other directory. @xref{Comparing
-Directories}.
-
-@item --new-group-format=@var{format}
-Use @var{format} to output a group of lines taken from just the second
-file in if-then-else format. @xref{Line Group Formats}.
-
-@item --new-line-format=@var{format}
-Use @var{format} to output a line taken from just the second file in
-if-then-else format. @xref{Line Formats}.
-
-@item --old-group-format=@var{format}
-Use @var{format} to output a group of lines taken from just the first
-file in if-then-else format. @xref{Line Group Formats}.
-
-@item --old-line-format=@var{format}
-Use @var{format} to output a line taken from just the first file in
-if-then-else format. @xref{Line Formats}.
-
-@item -p
-@itemx --show-c-function
-Show which C function each change is in. @xref{C Function Headings}.
-
-@item -q
-@itemx --brief
-Report only whether the files differ, not the details of the
-differences. @xref{Brief}.
-
-@item -r
-@itemx --recursive
-When comparing directories, recursively compare any subdirectories
-found. @xref{Comparing Directories}.
-
-@item -s
-@itemx --report-identical-files
-Report when two files are the same. @xref{Comparing Directories}.
-
-@item -S @var{file}
-@itemx --starting-file=@var{file}
-When comparing directories, start with the file @var{file}. This is
-used for resuming an aborted comparison. @xref{Comparing Directories}.
-
-@item --speed-large-files
-Use heuristics to speed handling of large files that have numerous
-scattered small changes. @xref{diff Performance}.
-
-@item --strip-trailing-cr
-Strip any trailing carriage return at the end of an input line.
-@xref{Binary}.
-
-@item --suppress-common-lines
-Do not print common lines in side by side format.
-@xref{Side by Side Format}.
-
-@item -t
-@itemx --expand-tabs
-Expand tabs to spaces in the output, to preserve the alignment of tabs
-in the input files. @xref{Tabs}.
-
-@item -T
-@itemx --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. @xref{Tabs}.
-
-@item --to-file=@var{file}
-Compare each operand to @var{file}; @var{file} may be a directory.
-
-@item -u
-Use the unified output format, showing three lines of context.
-@xref{Unified Format}.
-
-@item --unchanged-group-format=@var{format}
-Use @var{format} to output a group of common lines taken from both files
-in if-then-else format. @xref{Line Group Formats}.
-
-@item --unchanged-line-format=@var{format}
-Use @var{format} to output a line common to both files in if-then-else
-format. @xref{Line Formats}.
-
-@item --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.
-@xref{Comparing Directories}.
-
-@item -U @var{lines}
-@itemx --unified@r{[}=@var{lines}@r{]}
-Use the unified output format, showing @var{lines} (an integer) lines of
-context, or three if @var{lines} is not given. @xref{Unified Format}.
-For proper operation, @command{patch} typically needs at least two lines of
-context.
-
-On older systems, @command{diff} supports an obsolete option
-@option{-@var{lines}} that has effect when combined with @option{-u}.
-@sc{posix} 1003.1-2001 (@pxref{Standards conformance}) does not allow
-this; use @option{-U @var{lines}} instead.
-
-@item -v
-@itemx --version
-Output version information and then exit.
-
-@item -w
-@itemx --ignore-all-space
-Ignore white space when comparing lines. @xref{White Space}.
-
-@item -W @var{columns}
-@itemx --width=@var{columns}
-Output at most @var{columns} (default 130) print columns per line in
-side by side format. @xref{Side by Side Format}.
-
-@item -x @var{pattern}
-@itemx --exclude=@var{pattern}
-When comparing directories, ignore files and subdirectories whose basenames
-match @var{pattern}. @xref{Comparing Directories}.
-
-@item -X @var{file}
-@itemx --exclude-from=@var{file}
-When comparing directories, ignore files and subdirectories whose basenames
-match any pattern contained in @var{file}. @xref{Comparing Directories}.
-
-@item -y
-@itemx --side-by-side
-Use the side by side output format. @xref{Side by Side Format}.
-@end table
-
-@node Invoking diff3
-@chapter Invoking @command{diff3}
-@cindex invoking @command{diff3}
-@cindex @command{diff3} invocation
-
-The @command{diff3} command compares three files and outputs descriptions
-of their differences. Its arguments are as follows:
-
-@example
-diff3 @var{options}@dots{} @var{mine} @var{older} @var{yours}
-@end example
-
-The files to compare are @var{mine}, @var{older}, and @var{yours}.
-At most one of these three file names may be @file{-},
-which tells @command{diff3} to read the standard input for that file.
-
-An exit status of 0 means @command{diff3} was successful, 1 means some
-conflicts were found, and 2 means trouble.
-
-@menu
-* diff3 Options:: Summary of options to @command{diff3}.
-@end menu
-
-@node diff3 Options
-@section Options to @command{diff3}
-@cindex @command{diff3} options
-@cindex options for @command{diff3}
-
-Below is a summary of all of the options that @sc{gnu} @command{diff3}
-accepts. Multiple single letter options (unless they take an argument)
-can be combined into a single command line argument.
-
-@table @option
-@item -a
-@itemx --text
-Treat all files as text and compare them line-by-line, even if they
-do not appear to be text. @xref{Binary}.
-
-@item -A
-@itemx --show-all
-Incorporate all unmerged changes from @var{older} to @var{yours} into
-@var{mine}, surrounding conflicts with bracket lines.
-@xref{Marking Conflicts}.
-
-@item --diff-program=@var{program}
-Use the compatible comparison program @var{program} to compare files
-instead of @command{diff}.
-
-@item -e
-@itemx --ed
-Generate an @command{ed} script that incorporates all the changes from
-@var{older} to @var{yours} into @var{mine}. @xref{Which Changes}.
-
-@item -E
-@itemx --show-overlap
-Like @option{-e}, except bracket lines from overlapping changes' first
-and third files.
-@xref{Marking Conflicts}.
-With @option{-E}, an overlapping change looks like this:
-
-@example
-<<<<<<< @var{mine}
-@r{lines from @var{mine}}
-=======
-@r{lines from @var{yours}}
->>>>>>> @var{yours}
-@end example
-
-@item --help
-Output a summary of usage and then exit.
-
-@item -i
-Generate @samp{w} and @samp{q} commands at the end of the @command{ed}
-script for System V compatibility. This option must be combined with
-one of the @option{-AeExX3} options, and may not be combined with @option{-m}.
-@xref{Saving the Changed File}.
-
-@item -L @var{label}
-@itemx --label=@var{label}
-Use the label @var{label} for the brackets output by the @option{-A},
-@option{-E} and @option{-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 @samp{diff3 -L X -L Y -L Z -m A B C} acts like
-@samp{diff3 -m A B C}, except that the output looks like it came from
-files named @samp{X}, @samp{Y} and @samp{Z} rather than from files
-named @samp{A}, @samp{B} and @samp{C}. @xref{Marking Conflicts}.
-
-@item -m
-@itemx --merge
-Apply the edit script to the first file and send the result to standard
-output. Unlike piping the output from @command{diff3} to @command{ed}, this
-works even for binary files and incomplete lines. @option{-A} is assumed
-if no edit script option is specified. @xref{Bypassing ed}.
-
-@item -T
-@itemx --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. @xref{Tabs}.
-
-@item -v
-@itemx --version
-Output version information and then exit.
-
-@item -x
-@itemx --overlap-only
-Like @option{-e}, except output only the overlapping changes.
-@xref{Which Changes}.
-
-@item -X
-Like @option{-E}, except output only the overlapping changes.
-In other words, like @option{-x}, except bracket changes as in @option{-E}.
-@xref{Marking Conflicts}.
-
-@item -3
-@itemx --easy-only
-Like @option{-e}, except output only the nonoverlapping changes.
-@xref{Which Changes}.
-@end table
-
-@node Invoking patch
-@chapter Invoking @command{patch}
-@cindex invoking @command{patch}
-@cindex @command{patch} invocation
-
-Normally @command{patch} is invoked like this:
-
-@example
-patch <@var{patchfile}
-@end example
-
-The full format for invoking @command{patch} is:
-
-@example
-patch @var{options}@dots{} @r{[}@var{origfile} @r{[}@var{patchfile}@r{]}@r{]}
-@end example
-
-You can also specify where to read the patch from with the @option{-i
-@var{patchfile}} or @option{--input=@var{patchfile}} option.
-If you do not specify @var{patchfile}, or if @var{patchfile} is
-@file{-}, @command{patch} reads the patch (that is, the @command{diff} output)
-from the standard input.
-
-If you do not specify an input file on the command line, @command{patch}
-tries to intuit from the @dfn{leading text} (any text in the patch
-that comes before the @command{diff} output) which file to edit.
-@xref{Multiple Patches}.
-
-By default, @command{patch} replaces the original input file with the
-patched version, possibly after renaming the original file into a
-backup file (@pxref{Backup Names}, for a description of how
-@command{patch} names backup files). You can also specify where to
-put the output with the @option{-o @var{file}} or
-@option{--output=@var{file}} option; however, do not use this option
-if @var{file} is one of the input files.
-
-@menu
-* patch Options:: Summary table of options to @command{patch}.
-@end menu
-
-@node patch Options
-@section Options to @command{patch}
-@cindex @command{patch} options
-@cindex options for @command{patch}
-
-Here is a summary of all of the options that @sc{gnu} @command{patch}
-accepts. @xref{patch and Tradition}, for which of these options are
-safe to use in older versions of @command{patch}.
-
-Multiple single-letter options that do not take an argument can be
-combined into a single command line argument with only one dash.
-
-@table @option
-@item -b
-@itemx --backup
-Back up the original contents of each file, even if backups would
-normally not be made. @xref{Backups}.
-
-@item -B @var{prefix}
-@itemx --prefix=@var{prefix}
-Prepend @var{prefix} to backup file names. @xref{Backup Names}.
-
-@item --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 @sc{posix}. @xref{Backups}.
-
-@item --binary
-Read and write all files in binary mode, except for standard output
-and @file{/dev/tty}. This option has no effect on
-@sc{posix}-conforming systems like @sc{gnu}/Linux. On systems where
-this option makes a difference, the patch should be generated by
-@samp{diff -a --binary}. @xref{Binary}.
-
-@item -c
-@itemx --context
-Interpret the patch file as a context diff. @xref{patch Input}.
-
-@item -d @var{directory}
-@itemx --directory=@var{directory}
-Make directory @var{directory} the current directory for interpreting
-both file names in the patch file, and file names given as arguments to
-other options. @xref{patch Directories}.
-
-@item -D @var{name}
-@itemx --ifdef=@var{name}
-Make merged if-then-else output using @var{name}. @xref{If-then-else}.
-
-@item --dry-run
-Print the results of applying the patches without actually changing
-any files. @xref{Dry Runs}.
-
-@item -e
-@itemx --ed
-Interpret the patch file as an @command{ed} script. @xref{patch Input}.
-
-@item -E
-@itemx --remove-empty-files
-Remove output files that are empty after the patches have been applied.
-@xref{Creating and Removing}.
-
-@item -f
-@itemx --force
-Assume that the user knows exactly what he or she is doing, and do not
-ask any questions. @xref{patch Messages}.
-
-@item -F @var{lines}
-@itemx --fuzz=@var{lines}
-Set the maximum fuzz factor to @var{lines}. @xref{Inexact}.
-
-@item -g @var{num}
-@itemx --get=@var{num}
-If @var{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. @xref{Revision Control}.
-
-@item --help
-Output a summary of usage and then exit.
-
-@item -i @var{patchfile}
-@itemx --input=@var{patchfile}
-Read the patch from @var{patchfile} rather than from standard input.
-@xref{patch Options}.
-
-@item -l
-@itemx --ignore-white-space
-Let any sequence of blanks (spaces or tabs) in the patch file match
-any sequence of blanks in the input file. @xref{Changed White Space}.
-
-@item -n
-@itemx --normal
-Interpret the patch file as a normal diff. @xref{patch Input}.
-
-@item -N
-@itemx --forward
-Ignore patches that @command{patch} thinks are reversed or already applied.
-See also @option{-R}. @xref{Reversed Patches}.
-
-@item --no-backup-if-mismatch
-Do not back up the original contents of files. This is the default
-behavior when conforming to @sc{posix}. @xref{Backups}.
-
-@item -o @var{file}
-@itemx --output=@var{file}
-Use @var{file} as the output file name. @xref{patch Options}.
-
-@item -p@var{number}
-@itemx --strip=@var{number}
-Set the file name strip count to @var{number}. @xref{patch Directories}.
-
-@item --posix
-Conform to @sc{posix}, as if the @env{POSIXLY_CORRECT} environment
-variable had been set. @xref{patch and POSIX}.
-
-@item --quoting-style=@var{word}
-Use style @var{word} to quote names in diagnostics, as if the
-@env{QUOTING_STYLE} environment variable had been set to @var{word}.
-@xref{patch Quoting Style}.
-
-@item -r @var{reject-file}
-@itemx --reject-file=@var{reject-file}
-Use @var{reject-file} as the reject file name. @xref{Reject Names}.
-
-@item -R
-@itemx --reverse
-Assume that this patch was created with the old and new files swapped.
-@xref{Reversed Patches}.
-
-@item -s
-@itemx --quiet
-@itemx --silent
-Work silently unless an error occurs. @xref{patch Messages}.
-
-@item -t
-@itemx --batch
-Do not ask any questions. @xref{patch Messages}.
-
-@item -T
-@itemx --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. @xref{Patching Time Stamps}.
-
-@item -u
-@itemx --unified
-Interpret the patch file as a unified diff. @xref{patch Input}.
-
-@item -v
-@itemx --version
-Output version information and then exit.
-
-@item -V @var{backup-style}
-@itemx --version=control=@var{backup-style}
-Select the naming convention for backup file names. @xref{Backup Names}.
-
-@item --verbose
-Print more diagnostics than usual. @xref{patch Messages}.
-
-@item -x @var{number}
-@itemx --debug=@var{number}
-Set internal debugging flags. Of interest only to @command{patch}
-patchers.
-
-@item -Y @var{prefix}
-@itemx --basename-prefix=@var{prefix}
-Prepend @var{prefix} to base names of backup files. @xref{Backup Names}.
-
-@item -z @var{suffix}
-@itemx --suffix=@var{suffix}
-Use @var{suffix} as the backup extension instead of @samp{.orig} or
-@samp{~}. @xref{Backup Names}.
-
-@item -Z
-@itemx --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 @sc{utc}. @xref{Patching Time Stamps}.
-
-@end table
-
-@node Invoking sdiff
-@chapter Invoking @command{sdiff}
-@cindex invoking @command{sdiff}
-@cindex @command{sdiff} invocation
-
-The @command{sdiff} command merges two files and interactively outputs the
-results. Its arguments are as follows:
-
-@example
-sdiff -o @var{outfile} @var{options}@dots{} @var{from-file} @var{to-file}
-@end example
-
-This merges @var{from-file} with @var{to-file}, with output to @var{outfile}.
-If @var{from-file} is a directory and @var{to-file} is not, @command{sdiff}
-compares the file in @var{from-file} whose file name is that of @var{to-file},
-and vice versa. @var{from-file} and @var{to-file} may not both be
-directories.
-
-@command{sdiff} options begin with @samp{-}, so normally @var{from-file}
-and @var{to-file} may not begin with @samp{-}. However, @option{--} as an
-argument by itself treats the remaining arguments as file names even if
-they begin with @samp{-}. You may not use @file{-} as an input file.
-
-@command{sdiff} without @option{-o} (or @option{--output}) produces a
-side-by-side difference. This usage is obsolete; use the @option{-y}
-or @option{--side-by-side} option of @command{diff} instead.
-
-An exit status of 0 means no differences were found, 1 means some
-differences were found, and 2 means trouble.
-
-@menu
-* sdiff Options:: Summary of options to @command{diff}.
-@end menu
-
-@node sdiff Options
-@section Options to @command{sdiff}
-@cindex @command{sdiff} options
-@cindex options for @command{sdiff}
-
-Below is a summary of all of the options that @sc{gnu} @command{sdiff} accepts.
-Each option has two equivalent names, one of which is a single
-letter preceded by @samp{-}, and the other of which is a long name
-preceded by @samp{--}. 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.
-
-@table @option
-@item -a
-@itemx --text
-Treat all files as text and compare them line-by-line, even if they
-do not appear to be text. @xref{Binary}.
-
-@item -b
-@itemx --ignore-space-change
-Ignore changes in amount of white space. @xref{White Space}.
-
-@item -B
-@itemx --ignore-blank-lines
-Ignore changes that just insert or delete blank lines. @xref{Blank
-Lines}.
-
-@item -d
-@itemx --minimal
-Change the algorithm to perhaps find a smaller set of changes. This
-makes @command{sdiff} slower (sometimes much slower). @xref{diff
-Performance}.
-
-@item --diff-program=@var{program}
-Use the compatible comparison program @var{program} to compare files
-instead of @command{diff}.
-
-@item -E
-@itemx --ignore-tab-expansion
-Ignore changes due to tab expansion.
-@xref{White Space}.
-
-@item --help
-Output a summary of usage and then exit.
-
-@item -i
-@itemx --ignore-case
-Ignore changes in case; consider upper- and lower-case to be the same.
-@xref{Case Folding}.
-
-@item -I @var{regexp}
-@itemx --ignore-matching-lines=@var{regexp}
-Ignore changes that just insert or delete lines that match @var{regexp}.
-@xref{Specified Folding}.
-
-@item -l
-@itemx --left-column
-Print only the left column of two common lines.
-@xref{Side by Side Format}.
-
-@item -o @var{file}
-@itemx --output=@var{file}
-Put merged output into @var{file}. This option is required for merging.
-
-@item -s
-@itemx --suppress-common-lines
-Do not print common lines. @xref{Side by Side Format}.
-
-@item --speed-large-files
-Use heuristics to speed handling of large files that have numerous
-scattered small changes. @xref{diff Performance}.
-
-@item --strip-trailing-cr
-Strip any trailing carriage return at the end of an input line.
-@xref{Binary}.
-
-@item -t
-@itemx --expand-tabs
-Expand tabs to spaces in the output, to preserve the alignment of tabs
-in the input files. @xref{Tabs}.
-
-@item -v
-@itemx --version
-Output version information and then exit.
-
-@item -w @var{columns}
-@itemx --width=@var{columns}
-Output at most @var{columns} (default 130) print columns per line.
-@xref{Side by Side Format}. Note that for historical reasons, this
-option is @option{-W} in @command{diff}, @option{-w} in @command{sdiff}.
-
-@item -W
-@itemx --ignore-all-space
-Ignore white space when comparing lines. @xref{White Space}.
-Note that for historical reasons, this option is @option{-w} in @command{diff},
-@option{-W} in @command{sdiff}.
-@end table
-
-@node Standards conformance
-@chapter Standards conformance
-@cindex @sc{posix}
-
-@vindex POSIXLY_CORRECT
-In a few cases, the @sc{gnu} utilities' default behavior is
-incompatible with the @sc{posix} standard. To suppress these
-incompatibilities, define the @env{POSIXLY_CORRECT} environment
-variable. Unless you are checking for @sc{posix} conformance, you
-probably do not need to define @env{POSIXLY_CORRECT}.
-
-Normally options and operands can appear in any order, and programs act
-as if all the options appear before any operands. For example,
-@samp{diff lao tzu -C 2} acts like @samp{diff -C 2 lao tzu}, since
-@samp{2} is an option-argument of @option{-C}. However, if the
-@env{POSIXLY_CORRECT} environment variable is set, options must appear
-before operands, unless otherwise specified for a particular command.
-
-Newer versions of @sc{posix} are occasionally incompatible with older
-versions. For example, older versions of @sc{posix} allowed the
-command @samp{diff -c -10} to have the same meaning as @samp{diff -C
-10}, but @sc{posix} 1003.1-2001 @samp{diff} no longer allows
-digit-string options like @option{-10}.
-
-@vindex _POSIX2_VERSION
-The @sc{gnu} utilities normally conform to the version of @sc{posix}
-that is standard for your system. To cause them to conform to a
-different version of @sc{posix}, define the @env{_POSIX2_VERSION}
-environment variable to a value of the form @var{yyyymm} specifying
-the year and month the standard was adopted. Two values are currently
-supported for @env{_POSIX2_VERSION}: @samp{199209} stands for
-@sc{posix} 1003.2-1992, and @samp{200112} stands for @sc{posix}
-1003.1-2001. For example, if you are running older software that
-assumes an older version of @sc{posix} and uses @samp{diff -c -10},
-you can work around the compatibility problems by setting
-@samp{_POSIX2_VERSION=199209} in your environment.
-
-@node Projects
-@chapter Future Projects
-
-Here are some ideas for improving @sc{gnu} @command{diff} and
-@command{patch}. The @sc{gnu} project has identified some
-improvements as potential programming projects for volunteers. You
-can also help by reporting any bugs that you find.
-
-If you are a programmer and would like to contribute something to the
-@sc{gnu} project, please consider volunteering for one of these
-projects. If you are seriously contemplating work, please write to
-@email{gnu@@gnu.org} to coordinate with other volunteers.
-
-@menu
-* Shortcomings:: Suggested projects for improvements.
-* Bugs:: Reporting bugs.
-@end menu
-
-@node Shortcomings
-@section Suggested Projects for Improving @sc{gnu} @command{diff} and @command{patch}
-@cindex projects for directories
-
-One should be able to use @sc{gnu} @command{diff} to generate a patch from any
-pair of directory trees, and given the patch and a copy of one such
-tree, use @command{patch} to generate a faithful copy of the other.
-Unfortunately, some changes to directory trees cannot be expressed using
-current patch formats; also, @command{patch} does not handle some of the
-existing formats. These shortcomings motivate the following suggested
-projects.
-
-@menu
-* Internationalization:: Handling multibyte and varying-width characters.
-* Changing Structure:: Handling changes to the directory structure.
-* Special Files:: Handling symbolic links, device special files, etc.
-* Unusual File Names:: Handling file names that contain unusual characters.
-* Time Stamp Order:: Outputting diffs in time stamp order.
-* Ignoring Changes:: Ignoring certain changes while showing others.
-* Speedups:: Improving performance.
-@end menu
-
-@node Internationalization
-@subsection Handling Multibyte and Varying-Width Characters
-@cindex multibyte characters
-@cindex varying-width characters
-
-@command{diff}, @command{diff3} and @command{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,
-@command{diff} does not properly ignore a multibyte space character.
-
-Also, @command{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 @option{-y} or
-@option{--side-by-side} option of @command{diff}.
-
-These problems need to be fixed without unduly affecting the
-performance of the utilities in unibyte environments.
-
-The IBM GNU/Linux Technology Center Internationalization Team has
-proposed some patches to support internationalized @command{diff}
-@uref{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 @command{diff}, so more work needs to be done in this area.
-
-@node Changing Structure
-@subsection Handling Changes to the Directory Structure
-@cindex directory structure changes
-
-@command{diff} and @command{patch} do not handle some changes to directory
-structure. For example, suppose one directory tree contains a directory
-named @samp{D} with some subsidiary files, and another contains a file
-with the same name @samp{D}. @samp{diff -r} does not output enough
-information for @command{patch} to transform the directory subtree into
-the file.
-
-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 @command{patch} that a file was renamed, even if
-there is no way for @command{diff} to generate such information.
-There should be a way to tell @command{patch} that a file's time stamp
-has changed, even if its contents have not changed.
-
-These problems can be fixed by extending the @command{diff} output format
-to represent changes in directory structure, and extending @command{patch}
-to understand these extensions.
-
-@node Special Files
-@subsection Files that are Neither Directories Nor Regular Files
-@cindex special files
-
-Some files are neither directories nor regular files: they are unusual
-files like symbolic links, device special files, named pipes, and
-sockets. Currently, @command{diff} treats symbolic links like regular files;
-it 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 @command{patch} cannot represent changes
-to such files. For example, if you change which file a symbolic link
-points to, @command{diff} outputs the difference between the two files,
-instead of the change to the symbolic link.
-
-@c This might not be a good idea; is it wise for root to install devices
-@c this way?
-@command{diff} should optionally report changes to special files specially,
-and @command{patch} should be extended to understand these extensions.
-
-@node Unusual File Names
-@subsection File Names that Contain Unusual Characters
-@cindex file names with unusual characters
-
-When a file name contains an unusual character like a newline or
-white space, @samp{diff -r} generates a patch that @command{patch} cannot
-parse. The problem is with format of @command{diff} output, not just with
-@command{patch}, because with odd enough file names one can cause
-@command{diff} to generate a patch that is syntactically correct but
-patches the wrong files. The format of @command{diff} output should be
-extended to handle all possible file names.
-
-@node Time Stamp Order
-@subsection Outputting Diffs in Time Stamp Order
-
-Applying @command{patch} to a multiple-file diff can result in files
-whose time stamps are out of order. @sc{gnu} @command{patch} has
-options to restore the time stamps of the updated files
-(@pxref{Patching Time Stamps}), but sometimes it is useful to generate
-a patch that works even if the recipient does not have @sc{gnu} patch,
-or does not use these options. One way to do this would be to
-implement a @command{diff} option to output diffs in time stamp order.
-
-@node Ignoring Changes
-@subsection Ignoring Certain Changes
-
-It would be nice to have a feature for specifying two strings, one in
-@var{from-file} and one in @var{to-file}, which should be considered to
-match. Thus, if the two strings are @samp{foo} and @samp{bar}, then if
-two lines differ only in that @samp{foo} in file 1 corresponds to
-@samp{bar} in file 2, the lines are treated as identical.
-
-It is not clear how general this feature can or should be, or
-what syntax should be used for it.
-
-A partial substitute is to filter one or both files before comparing,
-e.g.:
-
-@example
-sed 's/foo/bar/g' file1 | diff - file2
-@end example
-
-However, this outputs the filtered text, not the original.
-
-@node Speedups
-@subsection Improving Performance
-
-When comparing two large directory structures, one of which was
-originally copied from the other with time stamps preserved (e.g.,
-with @samp{cp -pR}), it would greatly improve performance if an option
-told @command{diff} to assume that two files with the same size and
-time stamps have the same content. @xref{diff Performance}.
-
-@node Bugs
-@section Reporting Bugs
-@cindex bug reports
-@cindex reporting bugs
-
-If you think you have found a bug in @sc{gnu} @command{cmp},
-@command{diff}, @command{diff3}, or @command{sdiff}, please report it
-by electronic mail to the
-@uref{http://mail.gnu.org/mailman/listinfo/bug-gnu-utils,GNU utilities
-bug report mailing list} @email{bug-gnu-utils@@gnu.org}. Please send
-bug reports for @sc{gnu} @command{patch} to
-@email{bug-patch@@gnu.org}. Send as precise a description of the
-problem as you can, including the output of the @option{--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 @uref{ftp://alpha.gnu.org/gnu/diffutils/}.
-
-@node Copying This Manual
-@appendix Copying This Manual
-
-@menu
-* GNU Free Documentation License:: License for copying this manual.
-@end menu
-
-@include fdl.texi
-
-@node Index
-@appendix Index
-
-@printindex cp
-
-@bye