.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
.\" Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2022 OmniOS Community Edition (OmniOSce) Association.
.\"
.Dd February 23, 2022
.Dt DIFF 1
.Os
.Sh NAME
.Nm diff
.Nd compare two files
.Sh SYNOPSIS
.Nm
.Op Fl biqtw
.Op Fl c | e | f | h | n | u
.Ar file1
.Ar file2
.Nm
.Op Fl biqtw
.Op Fl C Ar number | Fl U Ar number
.Ar file1
.Ar file2
.Nm
.Op Fl biqtw
.Op Fl D Ar string
.Ar file1
.Ar file2
.Nm
.Op Fl biqtw
.Op Fl c | e | f | h | n | u
.Op Fl l
.Op Fl r
.Op Fl s
.Op Fl S Ar name
.Ar directory1
.Ar directory2
.Sh DESCRIPTION
The
.Nm
utility will compare the contents of
.Ar file1
and
.Ar file2
and write to standard output a list of changes necessary to convert
.Ar file1
into
.Ar file2 .
This list should be minimal.
Except in rare circumstances,
.Nm
finds a smallest sufficient set of file differences.
No output will be produced if the files are identical.
.Pp
The normal output contains lines of these forms:
.Pp
.Bl -item -offset indent -compact
.Sm off
.It
.Ar n1 Sy a Ar n3 , n4
.It
.Ar n1 , n2 Sy d Ar n3
.It
.Ar n1 , n2 Sy c Ar n3 , n4
.Sm on
.El
.Pp
where
.Ar n1
and
.Ar n2
represent lines in
.Ar file1
and
.Ar n3
and
.Ar n4
represent lines in
.Ar file2
These lines resemble
.Xr ed 1
commands to convert
.Ar file1
to
.Ar file2 .
By exchanging
.Sy a
for
.Sy d
and reading backwards,
.Ar file2
can be converted to
.Ar file1 .
As in
.Xr ed 1 ,
identical pairs, where
.Ar n1 Ns = Ns Ar n2
or
.Ar n3 Ns = Ns Ar n4
are abbreviated as a single number.
.Pp
Following each of these lines come all the lines that are affected in the first
file flagged by
.Sq < ,
then all the lines that are affected in the second file flagged by
.Sq > .
.Sh OPTIONS
The following options are supported:
.Bl -tag -width Ds
.It Fl b
Ignores trailing blanks
.Pq spaces and tabs
and treats other strings of blanks as equivalent.
.It Fl i
Ignores the case of letters.
For example, `
.Sq A
will compare equal to
.Sq a .
.It Fl q
report only when files differ
.It Fl t
Expands TAB characters in output lines.
Normal or
.Fl c
output adds character(s) to the front of each line that may adversely affect
the indentation of the original source lines and make the output lines
difficult to interpret.
This option will preserve the original source's indentation.
.It Fl w
Ignores all blanks
.Pq SPACE and TAB characters
and treats all other strings of blanks as equivalent.
For example,
.Ql if ( a == b )
will compare equal to
.Ql if (a==b) .
.El
.Pp
The following options are mutually exclusive:
.Bl -tag -width Ds
.It Fl c
Produces a listing of differences with three lines of context.
With this option, output format is modified slightly.
That is, output begins with identification of the files involved and their
creation dates, then each change is separated by a line with a dozen
asterisks
.Pq \&* .
The lines removed from
.Ar file1
are marked with
.Sq -- .
The lines added to
.Ar file2
are marked
.Sq \&+ .
Lines that are changed from one file to the other are marked in both files with
.Sq \&! .
.It Fl C Ar number
Produces a listing of differences identical to that produced by
.Fl c
with
.Ar number
lines of context.
.It Fl D Ar string
Creates a merged version of
.Ar file1
and
.Ar file2
with C preprocessor controls included so that a compilation of the result
without defining
.Ar string
is equivalent to compiling
.Ar file1 ,
while defining
.Ar string
will yield
.Ar file2 .
.It Fl e
Produces a script of only
.Sy a ,
.Sy c ,
and
.Sy d
commands for the editor
.Xr ed 1 ,
which will recreate
.Ar file2
from
.Ar file1 .
In connection with the
.Fl e
option, the following shell program may help maintain multiple versions of a
file.
Only an ancestral file
.Pq $1
and a chain of version-to-version
.Sy ed
scripts
.Pq $2,$3,...
made by
.Nm
need be on hand.
A
.Dq latest version
appears on the standard output.
.Pp
.Dl (shift; cat $*; echo a'1,$p') | ed - $1
.It Fl f
Produces a similar script, not useful with
.Xr ed 1 ,
in the opposite order.
.It Fl h
Does a fast, half-hearted job.
It works only when changed stretches are short and well separated, but does
work on files of unlimited length.
Options
.Fl c ,
.Fl C ,
.Fl D ,
.Fl e ,
.Fl f ,
and
.Fl n
are unavailable with
.Fl h .
.Nm
does not descend into directories with this option.
.It Fl n
Produces a script similar to
.Fl e ,
but in the opposite order and with a count of changed lines on each insert or
delete command.
.It Fl u
Produces a listing of differences with three lines of context.
The output is similar to that of the
.Fl c
option, except that the context is
.Dq unified .
Removed and changed lines in
.Ar file1
are marked by a
.Sq \&-
while lines added or changed in
.Ar file2
are marked by a
.Sq \&+ .
Both versions of changed lines appear in the output, while added, removed, and
context lines appear only once.
The identification of
.Ar file1
and
.Ar file2
is different, with
.Dq ---
and
.Dq +++
being printed where
.Dq ***
and
.Dq ---
would appear with the
.Fl c
option.
Each change is separated by a line of the form
.Pp
.D1 Cm @@ Cm \&- Ns Ar n1 , Ns Ar n2 Cm + Ns Ar n3 , Ns Ar n4 Cm @@
.It Fl U Ar number
Produces a listing of differences identical to that produced by
.Fl u
with
.Ar number
lines of context.
.El
.Pp
The following options are used for comparing directories:
.Bl -tag -width Ds
.It Fl l
Produces output in long format.
Before the
.Nm ,
each text file is piped through
.Xr pr 1
to paginate it.
Other differences are remembered and summarized after all text file differences
are reported.
.It Fl r
Applies
.Nm
recursively to common subdirectories encountered.
.It Fl s
Reports files that are identical.
These identical files would not otherwise be mentioned.
.It Fl S Ar name
Starts a directory
.Nm
in the middle, beginning with the file
.Ar name .
.El
.Sh OPERANDS
The following operands are supported:
.Pp
.Bl -tag -offset Ds -width directory1 -compact
.It Ar file1
.It Ar file2
A path name of a file or directory to be compared.
If either
.Ar file1
or
.Ar file2
is
.Sq \&- ,
the standard input will be used in its place.
.Pp
.It Ar directory1
.It Ar directory2
A path name of a directory to be compared.
.El
.Pp
If only one of
.Ar file1
and
.Ar file2
is a directory,
.Nm
will 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 USAGE
See
.Xr largefile 5
for the description of the behavior of
.Nm
when encountering files greater than or equal to 2 Gbyte
.Pq  2^31 bytes .
.Sh FILES
.Bl -tag -width Ds
.It Pa /tmp/d?????
temporary file used for comparison
.It Pa /usr/lib/diffh
executable file for
.Fl h
option
.El
.Sh EXIT STATUS
The following exit values are returned:
.Bl -tag -width Ds
.It 0
No differences were found.
.It 1
Differences were found.
.It >1
An error occurred.
.El
.Sh EXAMPLES
.Sy Example 1 No Typical output of the diff command
.Pp
In the following command,
.Ar dir1
is a directory containing a directory named
.Pa x ,
.Ar dir2
is a directory containing a directory named
.Pa x ,
.Pa dir1/x
and
.Pa dir2/x
both contain files named
.Pa date.out ,
and
.Pa dir2/x
contains a file named
.Pa y :
.Bd -literal -offset 4n
example% diff -r dir1 dir2
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
.Ed
.Sh ENVIRONMENT VARIABLES
See
.Xr environ 5
for descriptions of the following environment variables that affect the
execution of
.Nm :
.Ev LANG ,
.Ev LC_ALL ,
.Ev LC_CTYPE ,
.Ev LC_MESSAGES ,
.Ev LC_TIME ,
and
.Ev NLSPATH .
.Bl -tag -width Ds
.It Ev TZ
Determines the locale for affecting the timezone used for calculating file
timestamps written with the
.Fl C
and
.Fl c
options.
.El
.Sh INTERFACE STABILITY
The command line interface of
.Nm
is
.Sy Committed .
The output of
.Nm
is
.Sy Committed .
.Sh SEE ALSO
.Xr bdiff 1 ,
.Xr cmp 1 ,
.Xr comm 1 ,
.Xr dircmp 1 ,
.Xr ed 1 ,
.Xr pr 1 ,
.Xr sdiff 1 ,
.Xr attributes 5 ,
.Xr environ 5 ,
.Xr largefile 5 ,
.Xr standards 5
.Sh NOTES
Editing scripts produced under the
.Fl e
or
.Fl f
options are na\(:ive about creating lines consisting of a single dot
.Sq \&. .
.Pp
Missing NEWLINE at end of file indicates that the last line of the file in
question did not have a NEWLINE.
If the lines are different, they will be flagged and output, although the
output will seem to indicate they are the same.