diff.texi

这是一个同样来自贝尔实验室的和UNIX有着渊源的操作系统, 其简洁的设计和实现易于我们学习和理解

GNU @code{diff} can treat lowercase letters as equivalent to their
uppercase 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 @samp{-i} or @samp{--ignore-case} option.

@node Specified Folding, Brief, Case Folding, Comparison
@section Suppressing Lines Matching a Regular Expression
@cindex regular expression suppression

To ignore insertions and deletions of lines that match a regular
expression, use the @samp{-I @var{regexp}} or
@samp{--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 '^[0-9]'} ignores
all changes to lines beginning with a digit.

However, @samp{-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, @code{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 @samp{-I} option.  @code{diff} tries to match each
line against each regular expression, starting with the last one given.

@node Brief, Binary, Specified Folding, Comparison
@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, @code{diff} simply reports whether files differ.  The @samp{-q}
and @samp{--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 @code{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
@code{cmp}.  For files that are identical, @code{cmp} produces no
output.  When the files differ, by default, @code{cmp} outputs the byte
offset and line number where the first difference occurs.  You can use
the @samp{-s} option to suppress that information, so that @code{cmp}
produces no output and reports whether the files differ using only its
exit status (@pxref{Invoking cmp}).

@c Fix this.
Unlike @code{diff}, @code{cmp} cannot compare directories; it can only
compare two files.

@node Binary, , Brief, Comparison
@section Binary Files and Forcing Text Comparisons
@cindex binary file diff
@cindex text versus binary diff

If @code{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.

@code{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 character in
that part of the file is non-null, @code{diff} considers the file to be
text; otherwise it considers the file to be binary.

Sometimes you might want to force @code{diff} to consider files to be
text.  For example, you might be comparing text files that contain
null characters; @code{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 @code{diff} to consider all
files to be text files, and compare them line by line, by using the
@samp{-a} or @samp{--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 @code{diff} output will consist of hunks
showing differences between long lines of whatever characters the files
contain.

You can also force @code{diff} to consider all files to be binary files,
and report only whether they differ (but not how).  Use the
@samp{--brief} option for this.

In operating systems that distinguish between text and binary files,
@code{diff} normally reads and writes all data as text.  Use the
@samp{--binary} option to force @code{diff} to read and write binary
data instead.  This option has no effect on a Posix-compliant system
like GNU or traditional Unix.  However, many personal computer
operating systems represent the end of a line with a carriage return
followed by a newline.  On such systems, @code{diff} normally ignores
these carriage returns on input and generates them at the end of each
output line, but with the @samp{--binary} option @code{diff} treats
each carriage return as just another input character, and does not
generate a carriage return at the end of each output line.  This can be
useful when dealing with non-text files that are meant to be
interchanged with Posix-compliant systems.

If you want to compare two files byte by byte, you can use the
@code{cmp} program with the @samp{-l} option to show the values of each
differing byte in the two files.  With GNU @code{cmp}, you can also use
the @samp{-c} option to show the ASCII representation of those bytes.
@xref{Invoking cmp}, for more information.

If @code{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.  @code{diff3} uses the same test as
@code{diff} to decide whether a file is binary.  As with @code{diff}, if
the input files contain a few non-text characters but otherwise are like
text files, you can force @code{diff3} to consider all files to be text
files and compare them line by line by using the @samp{-a} or
@samp{--text} options.

@node Output Formats, Comparing Directories, Comparison, Top
@chapter @code{diff} Output Formats
@cindex output formats
@cindex format of @code{diff} output

@code{diff} has several mutually exclusive options for output format.
The following sections describe each format, illustrating how
@code{diff} reports the differences between two sample input files.

@menu
* Sample diff Input::	Sample @code{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, Normal, , Output Formats
@section Two Sample Input Files
@cindex @code{diff} sample input
@cindex sample input for @code{diff}

Here are two sample files that we will use in numerous examples to
illustrate the output of @code{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, Context, Sample diff Input, Output Formats
@section Showing Differences Without Context
@cindex normal output format
@cindex @samp{<} output format

The ``normal'' @code{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 @code{diff} and the Posix standard.

@menu
* Detailed Normal::	A detailed description of normal output format.
* Example Normal::	Sample output in the normal format.
@end menu

@node Detailed Normal, Example Normal, , 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, , Detailed Normal, 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, Side by Side, Normal, Output Formats
@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}.

GNU @code{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 @code{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.  @code{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, @code{patch} can adjust
the line numbers accordingly and still apply the diff correctly.
@xref{Imperfect}, for more information on using @code{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, Unified Format, , Context
@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 @samp{-C @var{lines}},
@samp{--context@r{[}=@var{lines}@r{]}}, or @samp{-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, @code{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, Example Context, , Context Format
@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