oasis-root

diff.1p (24961B)

'\" et
.TH DIFF "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
diff
\(em compare two files
.SH SYNOPSIS
.LP
.nf
diff \fB[\fR-c|-e|-f|-u|-C \fIn\fR|-U \fIn\fB] [\fR-br\fB] \fIfile1 file2\fR
.fi
.SH DESCRIPTION
The
.IR diff
utility shall compare the contents of
.IR file1
and
.IR file2
and write to standard output a list of changes necessary to convert
.IR file1
into
.IR file2 .
This list should be minimal. No output shall be produced if the files
are identical.
.SH OPTIONS
The
.IR diff
utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 12.2" ", " "Utility Syntax Guidelines".
.P
The following options shall be supported:
.IP "\fB\-b\fP" 10
Cause any amount of white space at the end of a line to be treated as a
single
<newline>
(that is, the white-space characters preceding the
<newline>
are ignored) and other strings of white-space characters, not including
<newline>
characters, to compare equal.
.IP "\fB\-c\fP" 10
Produce output in a form that provides three lines of copied context.
.IP "\fB\-C\ \fIn\fR" 10
Produce output in a form that provides
.IR n
lines of copied context (where
.IR n
shall be interpreted as a positive decimal integer).
.IP "\fB\-e\fP" 10
Produce output in a form suitable as input for the
.IR ed
utility, which can then be used to convert
.IR file1
into
.IR file2 .
.IP "\fB\-f\fP" 10
Produce output in an alternative form, similar in format to
.BR \-e ,
but not intended to be suitable as input for the
.IR ed
utility, and in the opposite order.
.IP "\fB\-r\fP" 10
Apply
.IR diff
recursively to files and directories of the same name when
.IR file1
and
.IR file2
are both directories.
.RS 10 
.P
The
.IR diff
utility shall detect infinite loops; that is, entering a previously
visited directory that is an ancestor of the last file encountered.
When it detects an infinite loop,
.IR diff
shall write a diagnostic message to standard error and shall either
recover its position in the hierarchy or terminate.
.RE
.IP "\fB\-u\fP" 10
Produce output in a form that provides three lines of unified context.
.IP "\fB\-U\ \fIn\fR" 10
Produce output in a form that provides
.IR n
lines of unified context (where
.IR n
shall be interpreted as a non-negative decimal integer).
.SH OPERANDS
The following operands shall be supported:
.IP "\fIfile1\fR,\ \fIfile2\fR" 10
A pathname of a file to be compared. If either the
.IR file1
or
.IR file2
operand is
.BR '\-' ,
the standard input shall be used in its place.
.P
If both
.IR file1
and
.IR file2
are directories,
.IR diff
shall not compare block special files, character special files, or FIFO
special files to any files and shall not compare regular files to
directories.
Further details are as specified in
.IR "Diff Directory Comparison Format".
The behavior of
.IR diff
on other file types is implementation-defined when found in directories.
.P
If only one of
.IR file1
and
.IR file2
is a directory,
.IR diff
shall be applied to the non-directory file and the file contained in
the directory file with a filename that is the same as the last
component of the non-directory file.
.SH STDIN
The standard input shall be used only if one of the
.IR file1
or
.IR file2
operands references standard input. See the INPUT FILES section.
.SH "INPUT FILES"
The input files may be of any type.
.SH "ENVIRONMENT VARIABLES"
The following environment variables shall affect the execution of
.IR diff :
.IP "\fILANG\fP" 10
Provide a default value for the internationalization variables that are
unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 8.2" ", " "Internationalization Variables"
for the precedence of internationalization variables used to determine
the values of locale categories.)
.IP "\fILC_ALL\fP" 10
If set to a non-empty string value, override the values of all the
other internationalization variables.
.IP "\fILC_CTYPE\fP" 10
Determine the locale for the interpretation of sequences of bytes of
text data as characters (for example, single-byte as opposed to
multi-byte characters in arguments and input files).
.IP "\fILC_MESSAGES\fP" 10
.br
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard error and
informative messages written to standard output.
.IP "\fILC_TIME\fP" 10
Determine the locale for affecting the format of file timestamps
written with the
.BR \-C
and
.BR \-c
options.
.IP "\fINLSPATH\fP" 10
Determine the location of message catalogs for the processing of
.IR LC_MESSAGES .
.IP "\fITZ\fP" 10
Determine the timezone used for calculating file timestamps written
with a context format. If
.IR TZ
is unset or null, an unspecified default timezone shall be used.
.SH "ASYNCHRONOUS EVENTS"
Default.
.SH STDOUT
.SS "Diff Directory Comparison Format"
.P
If both
.IR file1
and
.IR file2
are directories, the following output formats shall be used.
.P
In the POSIX locale, each file that is present in only one directory
shall be reported using the following format:
.sp
.RS 4
.nf
"Only in %s: %s\en", <\fIdirectory pathname\fP>, <\fIfilename\fR>
.fi
.P
.RE
.P
In the POSIX locale, subdirectories that are common to the two
directories may be reported with the following format:
.sp
.RS 4
.nf
"Common subdirectories: %s and %s\en", <\fIdirectory1 pathname\fR>,
    <\fIdirectory2 pathname\fR>
.fi
.P
.RE
.P
For each file common to the two directories, if the two files are not to
be compared: if the two files have the same device ID and file
serial number, or are both block special files that refer to the
same device, or are both character special files that refer to the
same device, in the POSIX locale the output format is unspecified.
Otherwise, in the POSIX locale an unspecified format shall be used
that contains the pathnames of the two files.
.P
For each file common to the two directories, if the files are
compared and are identical, no output shall be written. If the two
files differ, the following format is written:
.sp
.RS 4
.nf
"diff %s %s %s\en", <\fIdiff_options\fR>, <\fIfilename1\fR>, <\fIfilename2\fR>
.fi
.P
.RE
.P
where <\fIdiff_options\fP> are the options as specified on the command
line.
.P
All directory pathnames listed in this section shall be relative to the
original command line arguments. All other names of files listed in
this section shall be filenames (pathname components).
.SS "Diff Binary Output Format"
.P
In the POSIX locale, if one or both of the files being compared are not
text files, it is implementation-defined whether
.IR diff
uses the binary file output format or the other formats as specified
below. The binary file output format shall contain the pathnames of
two files being compared and the string
.BR \(dqdiffer\(dq .
.P
If both files being compared are text files, depending on the options
specified, one of the following formats shall be used to write the
differences.
.SS "Diff Default Output Format"
.P
The default (without
.BR \-e ,
.BR \-f ,
.BR \-c ,
.BR \-C ,
.BR \-u ,
or
.BR \-U
options)
.IR diff
utility output shall contain lines of these forms:
.sp
.RS 4
.nf
"%da%d\en", <\fInum1\fR>, <\fInum2\fR>
.P
"%da%d,%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR>
.P
"%dd%d\en", <\fInum1\fR>, <\fInum2\fR>
.P
"%d,%dd%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR>
.P
"%dc%d\en", <\fInum1\fR>, <\fInum2\fR>
.P
"%d,%dc%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR>
.P
"%dc%d,%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR>
.P
"%d,%dc%d,%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR>, <\fInum4\fR>
.fi
.P
.RE
.P
These lines resemble
.IR ed
subcommands to convert
.IR file1
into
.IR file2 .
The line numbers before the action letters shall pertain to
.IR file1 ;
those after shall pertain to
.IR file2 .
Thus, by exchanging
.IR a
for
.IR d
and reading the line in reverse order, one can also determine how to
convert
.IR file2
into
.IR file1 .
As in
.IR ed ,
identical pairs (where
.IR num1 =
.IR num2 )
are abbreviated as a single number.
.P
Following each of these lines,
.IR diff
shall write to standard output all lines affected in the first
file using the format:
.sp
.RS 4
.nf
"< %s", <\fIline\fR>
.fi
.P
.RE
.P
and all lines affected in the second file using the format:
.sp
.RS 4
.nf
"> %s", <\fIline\fR>
.fi
.P
.RE
.P
If there are lines affected in both
.IR file1
and
.IR file2
(as with the
.BR c
subcommand), the changes are separated with a line consisting of three
<hyphen-minus>
characters:
.sp
.RS 4
.nf
"---\en"
.fi
.P
.RE
.SS "Diff \-e Output Format"
.P
With the
.BR \-e
option, a script shall be produced that shall, when provided as input
to
.IR ed ,
along with an appended
.BR w
(write) command, convert
.IR file1
into
.IR file2 .
Only the
.BR a
(append),
.BR c
(change),
.BR d
(delete),
.BR i
(insert), and
.BR s
(substitute) commands of
.IR ed
shall be used in this script. Text lines, except those consisting of
the single character
<period>
(\c
.BR '.' ),
shall be output as they appear in the file.
.SS "Diff \-f Output Format"
.P
With the
.BR \-f
option, an alternative format of script shall be produced. It is
similar to that produced by
.BR \-e ,
with the following differences:
.IP " 1." 4
It is expressed in reverse sequence; the output of
.BR \-e
orders changes from the end of the file to the beginning; the
.BR \-f
from beginning to end.
.IP " 2." 4
The command form <\fIlines\fP> <\fIcommand-letter\fR> used by
.BR \-e
is reversed. For example, 10\fIc\fP with
.BR \-e
would be
.IR c 10
with
.BR \-f .
.IP " 3." 4
The form used for ranges of line numbers is
<space>-separated,
rather than
<comma>-separated.
.SS "Diff \-c or \-C Output Format"
.P
With the
.BR \-c
or
.BR \-C
option, the output format shall consist of affected lines along with
surrounding lines of context. The affected lines shall show which ones
need to be deleted or changed in
.IR file1 ,
and those added from
.IR file2 .
With the
.BR \-c
option, three lines of context, if available, shall be written before
and after the affected lines. With the
.BR \-C
option, the user can specify how many lines of context are written.
The exact format follows.
.P
The name and last modification time of each file shall be output in the
following format:
.sp
.RS 4
.nf
"*** %s %s\en", \fIfile1\fR, <\fIfile1 timestamp\fR>
"--- %s %s\en", \fIfile2\fR, <\fIfile2 timestamp\fR>
.fi
.P
.RE
.P
Each <\fIfile\fP> field shall be the pathname of the corresponding
file being compared. The pathname written for standard input is
unspecified.
.P
In the POSIX locale, each <\fItimestamp\fP> field shall be equivalent
to the output from the following command:
.sp
.RS 4
.nf
date "+%a %b %e %T %Y"
.fi
.P
.RE
.P
without the trailing
<newline>,
executed at the time of last modification of the corresponding file (or
the current time, if the file is standard input).
.P
Then, the following output formats shall be applied for every set of
changes.
.P
First, a line shall be written in the following format:
.sp
.RS 4
.nf
"***************\en"
.fi
.P
.RE
.P
Next, the range of lines in
.IR file1
shall be written in the following format if the range contains
two or more lines:
.sp
.RS 4
.nf
"*** %d,%d ****\en", <\fIbeginning line number\fR>, <\fIending line number\fR>
.fi
.P
.RE
.P
and the following format otherwise:
.sp
.RS 4
.nf
"*** %d ****\en", <\fIending line number\fR>
.fi
.P
.RE
.P
The ending line number of an empty range shall be the number of the
preceding line, or 0 if the range is at the start of the file.
.P
Next, the affected lines along with lines of context (unaffected lines)
shall be written. Unaffected lines shall be written in the following
format:
.sp
.RS 4
.nf
"  %s", <\fIunaffected_line\fR>
.fi
.P
.RE
.P
Deleted lines shall be written as:
.sp
.RS 4
.nf
"- %s", <\fIdeleted_line\fR>
.fi
.P
.RE
.P
Changed lines shall be written as:
.sp
.RS 4
.nf
"! %s", <\fIchanged_line\fR>
.fi
.P
.RE
.P
Next, the range of lines in
.IR file2
shall be written in the following format if the range contains two
or more lines:
.sp
.RS 4
.nf
"--- %d,%d ----\en", <\fIbeginning line number\fR>, <\fIending line number\fR>
.fi
.P
.RE
.P
and the following format otherwise:
.sp
.RS 4
.nf
"--- %d ----\en", <\fIending line number\fR>
.fi
.P
.RE
.P
Then, lines of context and changed lines shall be written as described in
the previous formats. Lines added from
.IR file2
shall be written in the following format:
.sp
.RS 4
.nf
"+ %s", <\fIadded_line\fR>
.fi
.P
.RE
.SS "Diff \-u or \-U Output Format"
.P
The
.BR \-u
or
.BR \-U
options behave like the
.BR \-c
or
.BR \-C
options, except that the context lines are not repeated; instead,
the context, deleted, and added lines are shown together, interleaved.
The exact format follows.
.P
The name and last modification time of each file shall be output
in the following format:
.sp
.RS 4
.nf
"--- %s\et%s%s %s\en", file1, <file1 timestamp>, <file1 frac>, <file1 zone>
"+++ %s\et%s%s %s\en", file2, <file2 timestamp>, <file2 frac>, <file2 zone>
.fi
.P
.RE
.P
Each <\fIfile\fR> field shall be the pathname of the corresponding file
being compared, or the single character
.BR '\-' 
if standard input is being compared. However, if the pathname contains
a
<tab>
or a
<newline>,
or if it does not consist entirely of characters taken
from the portable character set, the behavior is implementation-defined.
.P
Each <\fItimestamp\fR> field shall be equivalent to the output from the
following command:
.sp
.RS 4
.nf
date \(aq+%Y-%m-%d %H:%M:%S\(aq
.fi
.P
.RE
.P
without the trailing
<newline>,
executed at the time of last modification of the corresponding file
(or the current time, if the file is standard input).
.P
Each <\fIfrac\fR> field shall be either empty, or a decimal point
followed by at least one decimal digit, indicating the
fractional-seconds part (if any) of the file timestamp. The
number of fractional digits shall be at least the number needed to
represent the file's timestamp without loss of information.
.P
Each <\fIzone\fR> field shall be of the form
.BR \(dqshhmm\(dq ,
where
.BR \(dqshh\(dq 
is a signed two-digit decimal number in the range \-24 through +25, and
.BR \(dqmm\(dq 
is an unsigned two-digit decimal number in the range 00 through 59.
It represents the timezone of the timestamp as the number of hours
(hh) and minutes (mm) east (+) or west (\-) of UTC for the timestamp.
If the hours and minutes are both zero, the sign shall be
.BR '+' .
However, if the timezone is not an integral number of minutes away
from UTC, the <\fIzone\fR> field is implementation-defined.
.P
Then, the following output formats shall be applied for every set
of changes.
.P
First, the range of lines in each file shall be written in the
following format:
.sp
.RS 4
.nf
"@@ -%s +%s @@", <file1 range>, <file2 range>
.fi
.P
.RE
.P
Each <\fIrange\fR> field shall be of the form:
.sp
.RS 4
.nf
"%1d", <beginning line number>
.fi
.P
.RE
.P
or:
.sp
.RS 4
.nf
"%1d,1", <beginning line number>
.fi
.P
.RE
.P
if the range contains exactly one line, and:
.sp
.RS 4
.nf
"%1d,%1d", <beginning line number>, <number of lines>
.fi
.P
.RE
.P
otherwise. If a range is empty, its beginning line number shall be
the number of the line just before the range, or 0 if the empty
range starts the file.
.P
Next, the affected lines along with lines of context shall be written.
Each non-empty unaffected line shall be written in the following format:
.sp
.RS 4
.nf
" %s", <unaffected_line>
.fi
.P
.RE
.P
where the contents of the unaffected line shall be taken from
.IR file1 .
It is implementation-defined whether an empty unaffected line is written
as an empty line or a line containing a single
<space>
character. This line also represents the same line of
.IR file2 ,
even though
.IR file2 's
line may contain different contents due to the
.BR \-b .
Deleted lines shall be written as:
.sp
.RS 4
.nf
"-%s", <deleted_line>
.fi
.P
.RE
.P
Added lines shall be written as:
.sp
.RS 4
.nf
"+%s", <added_line>
.fi
.P
.RE
.P
The order of lines written shall be the same as that of the
corresponding file. A deleted line shall never be written
immediately after an added line.
.P
If
.BR \-U
.IR n
is specified, the output shall contain no more than 2\c
.IR n
consecutive unaffected lines; and if the output contains an
affected line and this line is adjacent to up to
.IR n
consecutive unaffected lines in the corresponding file, the output shall
contain these unaffected lines.
.BR \-u
shall act like
.BR \-U 3.
.SH STDERR
The standard error shall be used only for diagnostic messages.
.SH "OUTPUT FILES"
None.
.SH "EXTENDED DESCRIPTION"
None.
.SH "EXIT STATUS"
The following exit values shall be returned:
.IP "\00" 6
No differences were found.
.IP "\01" 6
Differences were found.
.IP >1 6
An error occurred.
.SH "CONSEQUENCES OF ERRORS"
Default.
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
If lines at the end of a file are changed and other lines are added,
.IR diff
output may show this as a delete and add, as a change, or as a change
and add;
.IR diff
is not expected to know which happened and users should not care about
the difference in output as long as it clearly shows the differences
between the files.
.SH EXAMPLES
If
.BR dir1
is a directory containing a directory named
.BR x ,
.BR dir2
is a directory containing a directory named
.BR x ,
.BR dir1/x
and
.BR dir2/x
both contain files named
.BR date.out ,
and
.BR dir2/x
contains a file named
.BR y ,
the command:
.sp
.RS 4
.nf
diff -r dir1 dir2
.fi
.P
.RE
.P
could produce output similar to:
.sp
.RS 4
.nf
Common subdirectories: dir1/x and dir2/x
Only in dir2/x: y
diff -r dir1/x/date.out dir2/x/date.out
1c1
< Mon Jul  2 13:12:16 PDT 1990
---
> Tue Jun 19 21:41:39 PDT 1990
.fi
.P
.RE
.SH RATIONALE
The
.BR \-h
option was omitted because it was insufficiently specified and does not
add to applications portability.
.P
Historical implementations employ algorithms that do not always produce
a minimum list of differences; the current language about making every
effort is the best this volume of POSIX.1\(hy2017 can do, as there is no metric that could be
employed to judge the quality of implementations against any and all
file contents. The statement ``This list should be minimal'' clearly
implies that implementations are not expected to provide the following
output when comparing two 100-line files that differ in only one
character on a single line:
.sp
.RS 4
.nf
1,100c1,100
all 100 lines from file1 preceded with "< "
---
all 100 lines from file2 preceded with "> "
.fi
.P
.RE
.P
The ``Only in'' messages required when the
.BR \-r
option is specified are not used by most historical implementations if
the
.BR \-e
option is also specified. It is required here because it provides
useful information that must be provided to update a target directory
hierarchy to match a source hierarchy. The ``Common subdirectories''
messages are written by System V and 4.3 BSD when the
.BR \-r
option is specified. They are allowed here but are not required because
they are reporting on something that is the same, not reporting a
difference, and are not needed to update a target hierarchy.
.P
The
.BR \-c
option, which writes output in a format using lines of context, has
been included. The format is useful for a variety of reasons, among
them being much improved readability and the ability to understand
difference changes when the target file has line numbers that differ
from another similar, but slightly different, copy. The
.IR patch
utility is most valuable when working with difference listings using
a context format. The BSD version of
.BR \-c
takes an optional argument specifying the amount of context. Rather
than overloading
.BR \-c
and breaking the Utility Syntax Guidelines for
.IR diff ,
the standard developers decided to add a separate option for specifying
a context diff with a specified amount of context (\c
.BR \-C ).
Also, the format for context
.IR diff s
was extended slightly in 4.3 BSD to allow multiple changes that are
within context lines from each other to be merged together. The output
format contains an additional four
<asterisk>
characters after the range of affected lines in the first filename. This
was to provide a flag for old programs (like old versions of
.IR patch )
that only understand the old context format. The version of context
described here does not require that multiple changes within context
lines be merged, but it does not prohibit it either. The extension is
upwards-compatible, so any vendors that wish to retain the old version
of
.IR diff
can do so by adding the extra four
<asterisk>
characters (that is, utilities that currently use
.IR diff
and understand the new merged format will also understand the old
unmerged format, but not \fIvice versa\fP).
.P
The
.BR \-u
and
.BR \-U
options of GNU
.IR diff
have been included. Their output format, designed by Wayne Davison,
takes up less space than
.BR \-c
and
.BR \-C
format, and in many cases is easier to read. The format's timestamps
do not vary by locale, so
.IR LC_TIME
does not affect it. The format's line numbers are rendered with the
.BR %1d
format, not
.BR %d ,
because the file format notation rules would allow extra
<blank>
characters to appear around the numbers.
.P
The substitute command was added as an additional format for the
.BR \-e
option. This was added to provide implementations with a way to fix the
classic ``dot alone on a line'' bug present in many versions of
.IR diff .
Since many implementations have fixed this bug, the standard developers
decided not to standardize broken behavior, but rather to provide the
necessary tool for fixing the bug. One way to fix this bug is to output
two periods whenever a lone period is needed, then terminate the append
command with a period, and then use the substitute command to convert
the two periods into one period.
.P
The BSD-derived
.BR \-r
option was added to provide a mechanism for using
.IR diff
to compare two file system trees. This behavior is useful, is standard
practice on all BSD-derived systems, and is not easily reproducible
with the
.IR find
utility.
.P
The requirement that
.IR diff
not compare files in some circumstances, even though they have the same
name, is based on the actual output of historical implementations.
The specified behavior precludes the problems arising from running
into FIFOs and other files that would cause
.IR diff
to hang waiting for input with no indication to the user that
.IR diff
was hung. An earlier version of this standard specified the output
format more precisely, but in practice this requirement was widely
ignored and the benefit of standardization seemed small, so it is now
unspecified. In most common usage,
.IR diff
.BR \-r
should indicate differences in the file hierarchies, not the difference
of contents of devices pointed to by the hierarchies.
.P
Many early implementations of
.IR diff
require seekable files. Since the System Interfaces volume of POSIX.1\(hy2017 supports named pipes, the
standard developers decided that such a restriction was unreasonable.
Note also that the allowed filename
.BR \-
almost always refers to a pipe.
.P
No directory search order is specified for
.IR diff .
The historical ordering is, in fact, not optimal, in that it prints out
all of the differences at the current level, including the statements
about all common subdirectories before recursing into those
subdirectories.
.P
The message:
.sp
.RS 4
.nf
"diff %s %s %s\en", <\fIdiff_options\fP>, <\fIfilename1\fP>, <\fIfilename2\fP>
.fi
.P
.RE
.P
does not vary by locale because it is the representation of a command,
not an English sentence.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIcmp\fR\^",
.IR "\fIcomm\fR\^",
.IR "\fIed\fR\^",
.IR "\fIfind\fR\^"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "Chapter 8" ", " "Environment Variables",
.IR "Section 12.2" ", " "Utility Syntax Guidelines"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .