# diff

## 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.
    


## NAME



           diff — compare two files
    


## SYNOPSIS



           diff **[** -c|-e|-f|-u|-C _n_ |-U _n_**] [** -br**]**_file1 file2_
    


## DESCRIPTION



           The _diff_ utility shall compare the contents of _file1_ and _file2_ and
           write to standard output a list of changes necessary to convert
           _file1_ into _file2_.  This list should be minimal. No output shall be
           produced if the files are identical.
    


## OPTIONS



           The _diff_ utility shall conform to the Base Definitions volume of
           POSIX.1‐2017, _Section 12.2_ , _Utility Syntax Guidelines_.
    
           The following options shall be supported:
    
           **-b** 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.
    
           **-c** Produce output in a form that provides three lines of
                     copied context.
    
           **-C** _n_      Produce output in a form that provides _n_ lines of copied
                     context (where _n_ shall be interpreted as a positive
                     decimal integer).
    
           **-e** Produce output in a form suitable as input for the _ed_
                     utility, which can then be used to convert _file1_ into
                     _file2_.
    
           **-f** Produce output in an alternative form, similar in format
                     to **-e** , but not intended to be suitable as input for the
                     _ed_ utility, and in the opposite order.
    
           **-r** Apply _diff_ recursively to files and directories of the
                     same name when _file1_ and _file2_ are both directories.
    
                     The _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, _diff_ shall write a diagnostic message
                     to standard error and shall either recover its position
                     in the hierarchy or terminate.
    
           **-u** Produce output in a form that provides three lines of
                     unified context.
    
           **-U** _n_      Produce output in a form that provides _n_ lines of
                     unified context (where _n_ shall be interpreted as a non-
                     negative decimal integer).
    


## OPERANDS



           The following operands shall be supported:
    
           _file1_ , _file2_
                     A pathname of a file to be compared. If either the _file1_
                     or _file2_ operand is **'-'** , the standard input shall be
                     used in its place.
    
           If both _file1_ and _file2_ are directories, _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 _Diff Directory_
           _Comparison Format_.  The behavior of _diff_ on other file types is
           implementation-defined when found in directories.
    
           If only one of _file1_ and _file2_ is a directory, _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.
    


## STDIN



           The standard input shall be used only if one of the _file1_ or _file2_
           operands references standard input. See the INPUT FILES section.
    


## INPUT FILES



           The input files may be of any type.
    


## ENVIRONMENT VARIABLES



           The following environment variables shall affect the execution of
           _diff_ :
    
           _LANG_      Provide a default value for the internationalization
                     variables that are unset or null. (See the Base
                     Definitions volume of POSIX.1‐2017, _Section 8.2_ ,
                     _Internationalization Variables_ for the precedence of
                     internationalization variables used to determine the
                     values of locale categories.)
    
           _LC_ALL_    If set to a non-empty string value, override the values
                     of all the other internationalization variables.
    
           _LC_CTYPE_  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).
    
           _LC_MESSAGES_
                     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.
    
           _LC_TIME_   Determine the locale for affecting the format of file
                     timestamps written with the **-C** and **-c** options.
    
           _NLSPATH_   Determine the location of message catalogs for the
                     processing of _LC_MESSAGES_.
    
           _TZ_        Determine the timezone used for calculating file
                     timestamps written with a context format. If _TZ_ is unset
                     or null, an unspecified default timezone shall be used.
    


## ASYNCHRONOUS EVENTS



           Default.
    


## STDOUT



       **Diff Directory Comparison Format**
           If both _file1_ and _file2_ are directories, the following output
           formats shall be used.
    
           In the POSIX locale, each file that is present in only one
           directory shall be reported using the following format:
    
               "Only in %s: %s\n", <_directory pathname_ >, <_filename_ >
    
           In the POSIX locale, subdirectories that are common to the two
           directories may be reported with the following format:
    
               "Common subdirectories: %s and %s\n", <_directory1 pathname_ >,
                   <_directory2 pathname_ >
    
           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.
    
           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:
    
               "diff %s %s %s\n", <_diff_options_ >, <_filename1_ >, <_filename2_ >
    
           where <_diff_options_ > are the options as specified on the command
           line.
    
           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).
    
       **Diff Binary Output Format**
           In the POSIX locale, if one or both of the files being compared
           are not text files, it is implementation-defined whether _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 **"differ"**.
    
           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.
    
       **Diff Default Output Format**
           The default (without **-e** , **-f** , **-c** , **-C** , **-u** , or **-U** options) _diff_
           utility output shall contain lines of these forms:
    
               "%da%d\n", <_num1_ >, <_num2_ >
    
               "%da%d,%d\n", <_num1_ >, <_num2_ >, <_num3_ >
    
               "%dd%d\n", <_num1_ >, <_num2_ >
    
               "%d,%dd%d\n", <_num1_ >, <_num2_ >, <_num3_ >
    
               "%dc%d\n", <_num1_ >, <_num2_ >
    
               "%d,%dc%d\n", <_num1_ >, <_num2_ >, <_num3_ >
    
               "%dc%d,%d\n", <_num1_ >, <_num2_ >, <_num3_ >
    
               "%d,%dc%d,%d\n", <_num1_ >, <_num2_ >, <_num3_ >, <_num4_ >
    
           These lines resemble _ed_ subcommands to convert _file1_ into _file2_.
           The line numbers before the action letters shall pertain to _file1_ ;
           those after shall pertain to _file2_.  Thus, by exchanging _a_ for _d_
           and reading the line in reverse order, one can also determine how
           to convert _file2_ into _file1_.  As in _ed_ , identical pairs (where
           _num1_ = _num2_) are abbreviated as a single number.
    
           Following each of these lines, _diff_ shall write to standard output
           all lines affected in the first file using the format:
    
               "< %s", <_line_ >
    
           and all lines affected in the second file using the format:
    
               "> %s", <_line_ >
    
           If there are lines affected in both _file1_ and _file2_ (as with the **c**
           subcommand), the changes are separated with a line consisting of
           three <hyphen-minus> characters:
    
               "---\n"
    
       **Diff -e Output Format**
           With the **-e** option, a script shall be produced that shall, when
           provided as input to _ed_ , along with an appended **w**(write) command,
           convert _file1_ into _file2_.  Only the **a**(append), **c**(change), **d**
           (delete), **i**(insert), and **s**(substitute) commands of _ed_ shall be
           used in this script. Text lines, except those consisting of the
           single character <period> (**'.'**), shall be output as they appear in
           the file.
    
       **Diff -f Output Format**
           With the **-f** option, an alternative format of script shall be
           produced. It is similar to that produced by **-e** , with the following
           differences:
    
            1. It is expressed in reverse sequence; the output of **-e** orders
               changes from the end of the file to the beginning; the **-f** from
               beginning to end.
    
            2. The command form <_lines_ > <_command-letter_ > used by **-e** is
               reversed. For example, 10 _c_ with **-e** would be _c_ 10 with **-f**.
    
            3. The form used for ranges of line numbers is <space>-separated,
               rather than <comma>-separated.
    
       **Diff -c or -C Output Format**
           With the **-c** or **-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 _file1_ , and those added from _file2_.  With the **-c** option, three
           lines of context, if available, shall be written before and after
           the affected lines. With the **-C** option, the user can specify how
           many lines of context are written.  The exact format follows.
    
           The name and last modification time of each file shall be output
           in the following format:
    
               "*** %s %s\n", _file1_ , <_file1 timestamp_ >
               "--- %s %s\n", _file2_ , <_file2 timestamp_ >
    
           Each <_file_ > field shall be the pathname of the corresponding file
           being compared. The pathname written for standard input is
           unspecified.
    
           In the POSIX locale, each <_timestamp_ > field shall be equivalent to
           the output from the following command:
    
               date "+%a %b %e %T %Y"
    
           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).
    
           Then, the following output formats shall be applied for every set
           of changes.
    
           First, a line shall be written in the following format:
    
               "***************\n"
    
           Next, the range of lines in _file1_ shall be written in the
           following format if the range contains two or more lines:
    
               "*** %d,%d ****\n", <_beginning line number_ >, <_ending line number_ >
    
           and the following format otherwise:
    
               "*** %d ****\n", <_ending line number_ >
    
           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.
    
           Next, the affected lines along with lines of context (unaffected
           lines) shall be written. Unaffected lines shall be written in the
           following format:
    
               "  %s", <_unaffected_line_ >
    
           Deleted lines shall be written as:
    
               "- %s", <_deleted_line_ >
    
           Changed lines shall be written as:
    
               "! %s", <_changed_line_ >
    
           Next, the range of lines in _file2_ shall be written in the
           following format if the range contains two or more lines:
    
               "--- %d,%d ----\n", <_beginning line number_ >, <_ending line number_ >
    
           and the following format otherwise:
    
               "--- %d ----\n", <_ending line number_ >
    
           Then, lines of context and changed lines shall be written as
           described in the previous formats. Lines added from _file2_ shall be
           written in the following format:
    
               "+ %s", <_added_line_ >
    
       **Diff -u or -U Output Format**
           The **-u** or **-U** options behave like the **-c** or **-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.
    
           The name and last modification time of each file shall be output
           in the following format:
    
               "--- %s\t%s%s %s\n", file1, <file1 timestamp>, <file1 frac>, <file1 zone>
               "+++ %s\t%s%s %s\n", file2, <file2 timestamp>, <file2 frac>, <file2 zone>
    
           Each <_file_ > field shall be the pathname of the corresponding file
           being compared, or the single character **'-'** 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.
    
           Each <_timestamp_ > field shall be equivalent to the output from the
           following command:
    
               date '+%Y-%m-%d %H:%M:%S'
    
           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).
    
           Each <_frac_ > 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.
    
           Each <_zone_ > field shall be of the form **"shhmm"** , where **"shh"** is a
           signed two-digit decimal number in the range -24 through +25, and
           **"mm"** 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 **'+'**.  However, if the timezone is not an integral
           number of minutes away from UTC, the <_zone_ > field is
           implementation-defined.
    
           Then, the following output formats shall be applied for every set
           of changes.
    
           First, the range of lines in each file shall be written in the
           following format:
    
               "@@ -%s +%s @@", <file1 range>, <file2 range>
    
           Each <_range_ > field shall be of the form:
    
               "%1d", <beginning line number>
    
           or:
    
               "%1d,1", <beginning line number>
    
           if the range contains exactly one line, and:
    
               "%1d,%1d", <beginning line number>, <number of lines>
    
           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.
    
           Next, the affected lines along with lines of context shall be
           written.  Each non-empty unaffected line shall be written in the
           following format:
    
               " %s", <unaffected_line>
    
           where the contents of the unaffected line shall be taken from
           _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
           _file2_ , even though _file2_ 's line may contain different contents due
           to the **-b**.  Deleted lines shall be written as:
    
               "-%s", <deleted_line>
    
           Added lines shall be written as:
    
               "+%s", <added_line>
    
           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.
    
           If **-U** _n_ is specified, the output shall contain no more than 2 _n_
           consecutive unaffected lines; and if the output contains an
           affected line and this line is adjacent to up to _n_ consecutive
           unaffected lines in the corresponding file, the output shall
           contain these unaffected lines.  **-u** shall act like **-U** 3.
    


## STDERR



           The standard error shall be used only for diagnostic messages.
    


## OUTPUT FILES



           None.
    


## EXTENDED DESCRIPTION



           None.
    


## EXIT STATUS



           The following exit values shall be returned:
    
            0    No differences were found.
    
            1    Differences were found.
    
           >1    An error occurred.
    


## CONSEQUENCES OF ERRORS



           Default.
    
           _The following sections are informative._
    


## APPLICATION USAGE



           If lines at the end of a file are changed and other lines are
           added, _diff_ output may show this as a delete and add, as a change,
           or as a change and add; _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.
    


## EXAMPLES



           If **dir1** is a directory containing a directory named **x** , **dir2** is a
           directory containing a directory named **x** , **dir1/x** and **dir2/x** both
           contain files named **date.out** , and **dir2/x** contains a file named **y** ,
           the command:
    
               diff -r dir1 dir2
    
           could produce output similar to:
    
               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
    


## RATIONALE



           The **-h** option was omitted because it was insufficiently specified
           and does not add to applications portability.
    
           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‐2017 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:
    
               1,100c1,100
               all 100 lines from file1 preceded with "< "
               ---
               all 100 lines from file2 preceded with "> "
    
           The ``Only in'' messages required when the **-r** option is specified
           are not used by most historical implementations if the **-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 **-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.
    
           The **-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 _patch_ utility is most valuable when working
           with difference listings using a context format. The BSD version
           of **-c** takes an optional argument specifying the amount of context.
           Rather than overloading **-c** and breaking the Utility Syntax
           Guidelines for _diff_ , the standard developers decided to add a
           separate option for specifying a context diff with a specified
           amount of context (**-C**).  Also, the format for context _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 _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 _diff_ can do so by adding the
           extra four <asterisk> characters (that is, utilities that
           currently use _diff_ and understand the new merged format will also
           understand the old unmerged format, but not _vice versa_).
    
           The **-u** and **-U** options of GNU _diff_ have been included. Their output
           format, designed by Wayne Davison, takes up less space than **-c** and
           **-C** format, and in many cases is easier to read. The format's
           timestamps do not vary by locale, so _LC_TIME_ does not affect it.
           The format's line numbers are rendered with the **%1d** format, not
           **%d** , because the file format notation rules would allow extra
           <blank> characters to appear around the numbers.
    
           The substitute command was added as an additional format for the
           **-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 _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.
    
           The BSD-derived **-r** option was added to provide a mechanism for
           using _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 _find_ utility.
    
           The requirement that _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 _diff_ to hang waiting for input with no indication to
           the user that _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, _diff_
           **-r** should indicate differences in the file hierarchies, not the
           difference of contents of devices pointed to by the hierarchies.
    
           Many early implementations of _diff_ require seekable files. Since
           the System Interfaces volume of POSIX.1‐2017 supports named pipes,
           the standard developers decided that such a restriction was
           unreasonable.  Note also that the allowed filename **-** almost always
           refers to a pipe.
    
           No directory search order is specified for _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.
    
           The message:
    
               "diff %s %s %s\n", <_diff_options_ >, <_filename1_ >, <_filename2_ >
    
           does not vary by locale because it is the representation of a
           command, not an English sentence.
    


## FUTURE DIRECTIONS



           None.
    


* * *