Import translated manuals from JM CVS Repository.

[linuxjm/jm.git] / manual / gnumaniak / original / man1 / diff.1

.\" You may copy, distribute and modify under the terms of the LDP General
.\" Public License as specified in the LICENSE file that comes with the
.\" gnumaniak distribution
.\"
.\" The author kindly requests that no comments regarding the "better"
.\" suitability or up-to-date notices of any info documentation alternative
.\" is added without contacting him first.
.\"
.\" (C) 2002 Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>
.\"
.\"     GNU diff man page
.\"     man pages are NOT obsolete!
.\"     <ragnar@ragnar-hojland.com>
.TH DIFF 1 "October 2002" "GNU diff Utilities 2.8.1"
.SH NAME
\fBdiff\fR \- find differences between two files
.SH SYNOPSIS
.B diff
[\fB\-abcdefhilnpqrstuwyBEHNPT\fR]
[\-\fILINES\fR]
[\fB\-x \fIPATTERN\fR]
[\fB\-C \fILINES\fR]
[\fB\-D \fINAME\fR]
[\fB\-F \fIREGEXP\fR] 
[\fB\-I \fIREGEXP\fR]
[\fB\-L \fILABEL\fR]
[\fB\-S \fIFILE\fR]
[\fB\-U \fILINES\fR]
[\fB\-W \fICOLUMNS\fR]
[\fB\-X \fIFILE\fR]
[\fB\-\-binary\fR]
[\fB\-\-brief\fR]
[\fB\-\-changed\-group\-format=\fIfORMAT\fR]
[\fB\-\-context\fR[\fB=\fILINES\fR]]
[\fB\-\-diff\-program=\fIPROGRAM\fR]
[\fB\-\-ed\fR]
[\fB\-\-exclude=\fIPATTERN\fR]
[\fB\-\-exclude-from=\fIFILE\fR]
[\fB\-\-expand\-tabs\fR]
[\fB\-\-forward\-ed\fR]
[\fB\-\-from\-file=\fIFILE\fR]
[\fB\-\-horizon\-lines=\fILINES\fR]
[\fB\-\-ifdef=\fINAME\fR]
[\fB\-\-ignore\-all\-space\fR]
[\fB\-\-ignore\-blank\-lines\fR]
[\fB\-\-ignore\-case\fR]
[\fB\-\-ignore\-file\-name\-case\fR]
[\fB\-\-ignore\-matching\-lines=\fIREGEXP\fR]
[\fB\-\-ignore\-space\-change\fR]
[\fB\-\-ignore\-tab\-expansion\fR]
[\fB\-\-inhibit\-hunk\-merge\fR]
[\fB\-\-initial\-tab]
[\fB\-\-label=\fILABEL\fR]
[\fB\-\-left\-column\fR]
[\fB\-\-line\-format=\fIFORMAT\fR]
[\fB\-\-minimal\fR]
[\fB\-\-new\-file\fR]
[\fB\-\-new\-group\-format=\fIFORMAT\fR]
[\fB\-\-new\-line\-format=\fIFORMAT\fR] 
[\fB\-\-no\-ignore\-file\-name\-case] 
[\fB\-\-old\-group\-format=\fIFORMAT\fR]
[\fB\-\-old\-line\-format=\fIFORMAT\fR]
[\fB\-\-paginate\fR] [\fB\-\-rcs\fR]
[\fB\-\-recursive\fR]
[\fB\-\-report\-identical\-files\fR]
[\fB\-\-sdiff\-merge\-assist\fR]
[\fB\-\-show\-c\-function\fR]
[\fB\-\-show\-function\-line=\fIREGEXP\fR]
[\fB\-\-side\-by\-side\fR]
[\fB\-\-speed\-large\-files\fR]
[\fB\-\-starting\-file=\fIFILE\fR]
[\fB\-\-strip\-trailing\-cr\fR]
[\fB\-\-supress\-common\-lines\fR]
[\fB\-\-text\fR] 
[\fB\-\-to\-file=\fIFILE\fR]
[\fB\-\-unchanged\-group\-format=\fIFORMAT\fR]
[\fB\-\-unchanged\-line\-format=\fIFORMAT\fR]
[\fB\-\-unidirectional\-new\-file]
[\fB\-\-unified\fR[\fB=\fILINES\fR]]
[\fB\-\-width=\fICOLUMNS\fR]
.I FROMFILE TOFILE

.B diff
[\fB\-v\fR] [\fB\-\-help\fR] [\fB\-\-version\fR]

.SH DESCRIPTION
.B diff
compares two files and outputs descriptions of their differences.

In the simplest case, the files to compare are
.I FROMFILE
and
.IR TOFILE .
At most one of these two file names may be
.RB ` \- ',
which tells
.B diff
to read the standard input for that file.

If 
.I FROMFILE
is a directory and
.I TOFILE
is not,
.B diff
compares the file in directory
.I FROMFILE
whose file name is that of
.IR TOFILE ,
and vice versa.  The non-directory file must not be
.RB ` \- '.

If both files are directories,
.B diff
compares corresponding files in both directories, in
alphabetical order; this comparison is not recursive unless the
.B \-r
or
.B \-\-recursive
option is given.
.B diff
never compares the actual contents of a directory as if it were a file.  The
file that is fully specified may not be
.RB ` \- ',
, because standard
input is nameless and the notion of ``file with the same name'' does not
apply.

If the
.B \-\-from\-file=\fIFILE\fR
option is given, the number of file names
is arbitrary, and \fIFILE\fR is compared to each named file.  Similarly, if
the
.B \-\-to\-file=\fIFILE\fR
option is given, each named file is compared to \fIFILE\fR.

.SH OPTIONS
.TP
.BI \- LINES
Show
.I LINES
(an integer) lines of context.  This option does not
specify an output format by itself; it has no effect unless it is
combined with
.B \-c
or
.BR \-u .
This option is obsolete.  For proper
operation,
.B patch
typically needs at least two lines of context.
.TP
.B \-a, \-\-text
Treat all files as text and compare them line-by-line, even if they
do not seem to be text.
.TP
.B \-b, \-\-ignore\-space\-change
Ignore changes in amount of white space.  Incomplete lines are ignored.
.TP
.B \-c
Use the context output format.
.TP
.B \-d, \-\-minimal
Change the algorithm to perhaps find a smaller set of changes.  This makes
.B diff
slower (sometimes much slower).
.TP
.B \-e, \-\-ed
Make output that is a valid
.BR ed (1)
script.
.TP
.B \-f, \-\-forward\-ed
Make output that looks vaguely like an
.B ed
script but has changes in the order they appear in the file.
.TP
.B \-h
This option currently has no effect; it is present for Unix
compatibility, and has been deprecated.
.TP
.B \-i, \-\-ignore\-case
Ignore changes in case; consider upper- and lower-case letters
equivalent.
.TP
.B \-l, \-\-paginate
Pass the output through
.BR pr (1)
to paginate it.
.TP
.B \-n, \-\-rcs
Output RCS-format diffs; like
.B \-f
except that each command
specifies the number of lines affected.
.TP
.B \-p, \-\-show\-c\-function
Show which C function each change is in. This is equivalent to
`\-F'^[_a\-zA\-Z$]''.
.TP
.B \-q, \-\-brief
Report only whether the files differ, not the details of the
differences.
.TP
.B \-r, \-\-recursive
When comparing directories, recursively compare any subdirectories
found.
.TP
.B \-s, \-\-report\-identical\-files
Report when two files are the same.
.TP
.B \-t, \-\-expand\-tabs
Expand tabs to spaces in the output, to preserve the alignment of tabs
in the input files.
.TP
.B \-u
Use the unified output format.
.TP
.B \-w, \-\-ignore\-all\-space
Ignore white space when comparing lines.  Incomplete lines are ignored.
.TP
.BI "\-x " PATTERN ", \-\-exclude=" PATTERN
When comparing directories, ignore files and subdirectories whose basenames
match
.IR PATTERN .
.TP
.B \-y, \-\-side\-by\-side
Use the side by side output format.
.TP
.B \-B, \-\-ignore\-blank\-lines
Ignore changes that just insert or delete blank lines.
.TP
.BI "\-C " LINES ", \-\-context[=" LINES ]
Use the context output format, showing
.I LINES
(an integer) lines of
context, or three if
.I LINES
is not given.  For proper operation,
.B patch
typically needs at least two lines of context.
.TP
.BI "\-D " NAME ", \-\-ifdef=" NAME
Make merged if-then-else format output, conditional on the preprocessor
macro
.IR NAME .
.TP
.B "\-E, \-\-ignore\-tab\-expansion"
Ignores changes in whitespace due to tab expansion.
.TP
.BI "\-F " REGEXP ", \-\-show\-function\-line=" REGEXP
In context and unified format, for each hunk of differences, show some
of the last preceding line that matches
.IR REGEXP .
.TP
.B \-H, \-\-speed\-large\-files
Use heuristics to speed handling of large files that have numerous
scattered small changes.  \-H short form has been deprecated.
.TP
.BI "\-I " REGEXP ", \-\-ignore\-matching\-lines=" REGEXP
Ignore changes that just insert or delete lines that match
.IR REGEXP .
.TP
.BI "\-L " LABEL ", \-\-label=" LABEL
Use
.I LABEL
instead of the file name in the context format
and unified format
headers.  \-L short form has been deprecated.
.TP
.B \-N, \-\-new\-file
In directory comparison, if a file is found in only one directory,
treat it as present but empty in the other directory.
.TP
.B \-P, \-\-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.
\-P short form has been deprecated.
.TP
.BI "\-S " FILE ", \-\-starting\-file=" FILE
When comparing directories, start with the file
.IR FILE .
This is used for resuming an aborted comparison.
.TP
.B \-T, \-\-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.
.TP
.BI "\-U " LINES ", \-\-unified" \fR[ = LINES \fR]
Use the unified output format, showing
.I LINES
(an integer) lines of context, or three if
.I LINES
is not given.  For proper operation,
.B patch
typically needs at least two lines of context.
.TP
.BI "\-W " COLUMNS ", \-\-width=" COLUMNS
Use an output width of
.I COLUMNS
in side by side format.
.TP
.BI \-X FILE ", \-\-exclude\-from=" FILE
When comparing directories, ignore files and subdirectories whose basenames
match any pattern contained in
.IR FILE .
.TP
.B \-\-binary
Read and write data in binary mode (no effect in Linux or other POSIX hosts).
.TP
.BI \-\-changed\-group\-format= FORMAT
Use
.I FORMAT
to output a line group containing differing lines from
both files in if-then-else format.
.TP
.B \-\-diff\-program= \fIPROGRAM
Use an external \fIPROGRAM\fR, compatible with \fBdiff\fR, to compare files.
.TP
.BI \-\-from\-file= FILE
Compare \fIFILE\fR with each operand; \fIFILE\fR may be a directory.
.TP
.BI \-\-horizon\-lines= LINES
Do not discard the last
.I LINES
lines of the common prefix
and the first
.I LINES
lines of the common suffix.
.TP
.B \-\-ignore\-file\-name\-case
Ignore case in filenames when comparing files, so that ``foo'' and ``Foo''
are considered the same and therefore compared with each other.
.TP
.B \-\-inhibit\-hunk\-merge
Do not shift hunk boundaries to merge adjacent hunks.
.TP
.B \-\-left\-column
Print only the left column of two common lines in side by side format.
.TP
.BI \-\-line\-format= FORMAT
Use
.I FORMAT
to output all input lines in in-then-else format.
.TP
.BI \-\-new\-group\-format= FORMAT
Use
.I FORMAT
to output a group of lines taken from just the second
file in if-then-else format.
.TP
.BI \-\-new\-line\-format= FORMAT
Use 
.I FORMAT
to output a line taken from just the second file in
if-then-else format.
.TP
.B \-\-no\-ignore\-file\-name\-case
Case in filenames is taken into account comparing files, so that names ``foo'' and
``Foo'' are not considered the same.  See \fB\-\-ignore\-file\-name\-case\fR.
.TP
.BI \-\-old\-group\-format= FORMAT
Use
.I FORMAT
to output a group of lines taken from just the first
file in if-then-else format.
.TP
.BI \-\-old\-line\-format= FORMAT
Use
.I FORMAT
to output a line taken from just the first file in
if-then-else format.
.TP
.B \-\-sdiff\-merge\-assist
Print extra information to help
.BR sdiff (1).
.B sdiff
uses this option when it runs
.BR diff .
This option is not intended for users to use directly.
.TP
.B \-\-strip\-trailing\-cr
Strips trailing CRs.  Useful when processing output from systems that use
CRLF as end of line markers.
.TP
.B \-\-suppress\-common\-lines
Do not print common lines in side by side format.
.TP
.BI \-\-unchanged\-group\-format= FORMAT
Use
.I FORMAT
to output a group of common lines taken from both files
in if-then-else format.
.TP
.BI \-\-unchanged\-line\-format= FORMAT
Use
.I FORMAT
to output a line common to both files in if-then-else
format.
.TP
.B "\-\-help"
Print a usage message on standard output and exit successfully.
.TP
.B \-v, \-\-version
Output the version number of
.BR diff .
.SH OUTPUT FORMATS
.SS Context format
The context output format starts with a two-line header, which looks
like this:
.sp
.nf
*** FROMFILE FROMFILE-MODIFICATION-TIME
--- TOFILE TOFILE-MODIFICATION-TIME
.fi
.sp
You can change the header's content with the 
.BI "-L " LABEL      
Next come one or more hunks of differences; each hunk shows
one area where the files differ.  Context format hunks look like this:
.sp
.nf
***************
*** FROMFILE-LINE-RANGE ****
  FROMFILE-LINE
  FROMFILE-LINE...
--- TOFILE-LINE-RANGE ----
  TOFILE-LINE
  TOFILE-LINE...
.fi
.sp
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:
.TP
.B !
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 
.RB ` ! '
in the part of this hunk for the other file.
.TP
.B +
An "inserted" line in the second file that corresponds to nothing in the
first file.
.TP
.B -
A "deleted" line in the first file that corresponds to nothing in the
second file.
.PP
If all of the changes in a hunk are insertions, the lines of
.I FROMFILE
are omitted.  If all of the changes are deletions, the lines
of 
.I TOFILE
are omitted.
.SS Unified format      
The unified output format starts with a two-line header, which looks
like this:
.sp
.nf   
--- FROMFILE FROMFILE-MODIFICATION-TIME
+++ TOFILE TOFILE-MODIFICATION-TIME
.fi
.sp
You can change the header's content with the 
.BI "-L " LABEL      
Next come one or more hunks of differences; each hunk shows
one area where the files differ.  Unified format hunks look like this:
.sp
.nf
@@ FROMFILE-RANGE TOFILE-RANGE @@
LINE-FROM-EITHER-FILE
LINE-FROM-EITHER-FILE...
.fi
.sp
The lines lines common to both files start with 1 space character.  The lines
that differ start with one of the following indicator characters:
.TP
.B +
A line was added here to the first file.
.TP
.B -
A line was removed here from the first file.
.SS Side by side format
The files are listed in two columns with a gutter between them.  The
gutter contains one of the following markers:
.TP
.B ` '
The corresponding lines are in common.  That is, either the lines
are identical, or the difference is ignored because of one of the
.B \-\-ignore
options.
.TP
.B |
The corresponding lines differ, and they are either both complete
or both incomplete.
.TP
.B <
The files differ and only the first file contains the line.
.TP
.B >
The files differ and only the second file contains the line.
.TP
.B (
Only the first file contains the line, but the difference is ignored.
.TP
.B )
Only the second file contains the line, but the difference is ignored.
.TP
.B \e
The corresponding lines differ, and only the first line is incomplete.
.TP
.B /
The corresponding lines differ, and only the second line is incomplete.
Normally, an output line is incomplete if and only if the lines that
it contains are incomplete.  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 
.RB ` \e '
if the first line is incomplete, 
.RB ` / '
if the second line is.
.PP
Side by side format is sometimes easiest to read, but it has
limitations.  It generates much wider output than usual, and truncates
lines that are too long to fit.  Also, it relies on lining up output
more heavily than usual, so its output looks particularly bad if you
use varying width fonts, nonstandard tab stops, or nonprinting
characters.
You can use
.BR sdiff (1)
command to interactively merge side by side differences.
.SS ed(1) 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 
.B ed
interprets line numbers in succeeding commands.
.B  ed 
format hunks look like this:
.sp
.nf
CHANGE-COMMAND
TO-FILE-LINE
TO-FILE-LINE...
.
.fi
.sp
Because
.B ed
uses a single period on a line to indicate the end of input, 
.B diff
protects lines of changes that contain a single period on a line by writing
two periods instead, then writing a subsequent ed' command to change the two 
periods into one.  The 
.B ed
format cannot represent an incomplete line, so if the second file ends
in a changed incomplete line,
.B 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:
.TP
.IB L a
Add text from the second file after line \fIL\fP in the first file.  For
example, `8a' means to add the following lines after line 8 of file 1.
.TP
.IB R c 
Replace the lines in range \fIR\fP in the first file with the following
lines.  Like a combined add and delete, but more compact.  For
example, `5,7c' means change lines 5-7 of file 1 to read as the
text file 2.
.TP
.IB R d 
Delete the lines in range \fIR\fP from the first file.  For example,
`5,7d' means delete lines 5-7 of file 1.
.PP
.B diff
can produce output that is like an 
.B 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 
.B ed
format, forward 
.B ed 
format cannot represent incomplete lines.

Forward
.B ed
format is not very useful, because neither
.B ed
nor
.B patch
can apply diffs in this format.  It exists mainly for  compatibility with
older versions of
.BR diff .
.SS RCS format
The RCS output format is designed specifically for use by the
Revision Control System, which is a set of free programs used for
organizing different versions and systems of files. It is like the forward
.B ed
format, but it can represent arbitrary changes to the contents of a file
because it avoids the 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
.RB ` a '
and 
.RB ` d '
commands are used
instead of 
.RB ` c '.
Also, if the second file ends in a changed incomplete line, then the output
also ends in an incomplete line.
.SH IF\-THEN\-ELSE
.SS C source format
You can use 
.B diff
to merge two files of C source code.  The output 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 
.BI "#ifdef " NAME
or
.B #ifndef 
.IR NAME ,
,BR #else ", and " #endif .
When compiling the output, you select which version to use by either
defining or leaving undefined the macro
.IR NAME .

For example, if you change an instance of `wait (&s)' to `waitpid
(-1, &s, 0)' and then merge the old and new files with the
`\fB--ifdef=\fIHAVE_WAITPID\fR' option, then the affected part of your code 
might look like this:
.sp
.nf
    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);
.fi
.SS Group formats
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 `old' and
`new', and outputs a merged file in which old regions are surrounded by
`\ebegin{em}'-`\eend{em}' lines, and new regions are surrounded by
`\ebegin{bf}'-`\eend{bf}' lines.
.sp
.nf
 diff \e
    --old-group-format='\ebegin{em}
 %<\eend{em}
 '  \e
    --new-group-format='\ebegin{bf}
 %>\eend{bf}
 '  \e
    old new
.fi
.sp                                                    
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.
.sp
.nf
 diff \e
    --old-group-format='\ebegin{em}
 %<\eend{em}
 ' \e
    --new-group-format='\ebegin{bf}
 %>\eend{bf}
 ' \e
    --unchanged-group-format='%=' \e
    --changed-group-format='\ebegin{em}
 %<\eend{em}
 \ebegin{bf}
 %>\eend{bf}
 '  \e
    old new
.fi
.sp
Here is a more advanced example, which outputs a diff listing with headers
containing line numbers in a "plain English" style. 
.sp
.nf
 diff \e
    --unchanged-group-format='' \e
    --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
 %<' \e
    --new-group-format='-------- %dN line%(N=1?:s) added after %de:
 %>' \e
    --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
 %<-------- to:
 %>' \e
    old new
.fi
.sp
To specify a line group format, use \fBdiff\fR 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 \fIFORMAT\fR, because it typically contains
shell metacharacters.
.TP
.BI \-\-old-group\-format= 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.
.TP
.BI \-\-new-group\-format= FORMAT
These line groups are hunks containing only lines
from the second file.  The default new group format is same as the the changed
group format if it is specified; otherwise it is a format that outputs the line
group as-is.
.TP
.BI \-\-changed\-group\-format= 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.
.TP
.BI \-\-unchanged\-group\-format= 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.
.SS Group conversions
.TP
.B %<
stands for the lines from the first file, including the trailing
newline.  Each line is formatted according to the old line format
.TP
.B %>
stands for the lines from the second file, including the trailing
newline.  Each line is formatted according to the new line format.
.TP
.B %=
stands for the lines common to both files, including the trailing
newline.  Each line is formatted according to the unchanged line format.
.TP
.B %%
stands for `%'.
.TP
.B %c'\fIC\fB''
where 
.I C
is a single character, stands for
.IR C ".  " C
may not be a backslash or an apostrophe.  For example, `%c':'' stands for a
colon, even inside the then-part of an if-then-else format, which a colon
would normally terminate.
.TP
.B %c'\eO''
where
.I O
is a string of 1, 2, or 3 octal digits, stands for the
character with octal code
.IR O .
For example, %c'\e0'' stands for a null character.
.TP
.BI ( A = B ? T : E )
If 
.I A
equals
.I B
then
.I T
else
.IR E .
.I A
and
.I B
are each either a decimal constant or a single letter interpreted as above.
This format spec is equivalent to 
.IR T " if " A "'s value equals " B "'s; otherwise it is equivalent to " E .

For example, `%(N=0?no:%dN) line%(N=1?:s)' is equivalent to no
lines' if N (the number of lines in the group in the the new file)
is 0, to 1 line' if N is 1, and to %dN lines' otherwise.
.TP
.I FN
where F is a 
.BR printf (3)
conversion specification and 
.I N
is one of the following letters, stands for 
.IR N "'s value formatted with " F .
.RS
.TP
.B e
The line number of the line just before the group in the old file.
.TP
.B f
The line number of the first line in the group in the old file; equals E + 1.
.TP
.B l
The line number of the last line in the group in the old file.
.TP
.B m
The line number of the line just after the group in the old file; equals L + 1.
.TP
.B n
The number of lines in the group in the old file; equals L - F + 1.
.TP
.B E, F, L, M, N
Likewise, for lines in the new file.
.RE
.sp
The 
.B printf
conversion specification can be 
.BR %d ", " %o ", " %x ", or " %X ,
specifying decimal, octal, lower case hexadecimal, or upper
case hexadecimal output respectively.  After the 
.RB ` % '
the following options can appear in sequence: a 
.RB ` - '
specifying left-justification; an integer specifying the minimum field width;
and a period followed by an optional integer specifying the
minimum number of digits.  For example, `%5dN' prints the number
of new lines in the group in a field of width 5 characters, using the 
.B printf
format "%5d"'.
.SS Line group format
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-column
change indicator to the left of the text.  The first column of output
is `-' for deleted lines, `|' for added lines, and a space for
unchanged lines.  The formats contain newline characters where newlines
are desired on output.
      
 diff \e
    --old-line-format='-%l
 ' \e
    --new-line-format='|%l
 ' \e
    --unchanged-line-format=' %l
 ' \e
   old new

To specify a line format, use one of the following options.  You
should quote \fIFORMAT\fR, since it often contains shell metacharacters.
.TP
.BI \-\-old-line-format= FORMAT
Formats lines just from the first file.
.TP
.BI \-\-new\-line\-format= FORMAT
Formats lines just from the second file.
.TP
.BI \-\-unchanged\-line\-format= FORMAT
Formats lines common to both files.
.TP
.BI \-\-line\-format= FORMAT
Formats all lines; in effect, it sets all three above options simultaneously.
.PP
In a line format, ordinary characters represent themselves; conversion
specifications start with
.RB ` % '
and have  forms.
.TP
.B %l
stands for the the contents of the line, not counting its trailing
newline (if any).  This format ignores whether the line is incomplete.
.TP
.B %L
stands for the the contents of the line, including its trailing newline (if
any).  If a line is incomplete, this format preserves its incompleteness.
.TP
.B %%
stands for `%'.
.TP
.B %c'\fIC\fB''
where 
.I C
is a single character, stands for
.IR C ".  " C
may not be a backslash or an apostrophe.  For example, `%c':'' stands for a
colon.
.TP
.B %c'\eO''
where
.I O
is a string of 1, 2, or 3 octal digits, stands for the
character with octal code
.IR O .
For example, %c'\e0'' stands for a null character.
.TP
.I Fn
where 
.I F
is a 
.B printf conversion specification, stands for the line number formatted with
.IR F .
For example, `%.5dn' prints the line number using the format `%.5d'.  For
more on printf conversion specifications, read the Group Format subsection
above. 
.PP
The default line format is 
.RB ` %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 `%l' or
%L' in a line format is just after a tab stop (e.g. by preceding %l' or %L'
with a tab character), or you should use the \fB\-t\fR 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 diff's normal format.  You can tailor this command to get
fine control over diff's output.
.sp
.nf
 diff \e
    --old-line-format='< %l
 ' \e
    --new-line-format='> %l
 ' \e
    --old-group-format='%df%(f=l?:,%dl)d%dE
 %<' \e
    --new-group-format='%dea%dF%(F=L?:,%dL)
 %>' \e
    --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
 %<---
 %>' \e
    --unchanged-group-format='' \e
    old new
.fi
.SH COMPARING DIRECTORIES
When both file name arguments to \fBdiff\fR are directories, it compares
each file that is contained in both directories, examining file names in
alphabetical order.  Normally it is silent about pairs of files that contain
no differences, but if you use the \fB\-s\fR option, it reports pairs of 
identical files.  Normally \fBdiff\fR reports subdirectories common to both
directories without comparing subdirectories' files, but if you use the 
\fB\-r\fR 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, \fBdiff\fR
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 \fBdiff\fR 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 \fB\-N\fR 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
.B \-P
option instead of 
.BR \-N .
This option is like 
.B \-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.  

To ignore some files while comparing directories, use the 
\fB\-x \fIPATTERN\fR option.  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 \fIPATTERN\fR in quotes so that the shell does not expand it.
For example, the option `\-x '*.[ao]'' ignores any file whose name ends with
`.a' or `.o'. This option accumulates if you specify it more than once.  For
example, using the options `-x 'RCS' -x '*,v'' ignores any file or
subdirectory whose base name is `RCS' or ends with `,v'.
.SH DIAGNOSTICS
.B diff
exits with one of the following values:
.TP
.B 0
No differences were found.
.TP
.B 1
Some difference was found.
.TP
.B 2
Some error occurred.
.SH SEE ALSO
cmp(1), comm(1), diff3(1), ed(1), patch(1), pr(1), sdiff(1).
.SH NOTES
Report bugs to bug-gnu-utils@gnu.org.
Page updated by Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>