DIFF(1)                    POSIX Programmer's Manual                   DIFF(1)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       diff -- compare two files

SSYYNNOOPPSSIISS
       diff [[-c|-e|-f|-u|-C _n|-U _n]] [[-br]] _f_i_l_e_1 _f_i_l_e_2

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

OOPPTTIIOONNSS
       The _d_i_f_f utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following options shall be supported:

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

       --cc        Produce output in a form that provides three lines of copied
                 context.

       --CC _n      Produce output in a form that provides _n lines of copied
                 context (where _n shall be interpreted as a positive decimal
                 integer).

       --ee        Produce output in a form suitable as input for the _e_d
                 utility, which can then be used to convert _f_i_l_e_1 into _f_i_l_e_2.

       --ff        Produce output in an alternative form, similar in format to
                 --ee, but not intended to be suitable as input for the _e_d
                 utility, and in the opposite order.

       --rr        Apply _d_i_f_f recursively to files and directories of the same
                 name when _f_i_l_e_1 and _f_i_l_e_2 are both directories.

                 The _d_i_f_f 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, _d_i_f_f shall write a diagnostic message to standard error
                 and shall either recover its position in the hierarchy or
                 terminate.

       --uu        Produce output in a form that provides three lines of unified
                 context.

       --UU _n      Produce output in a form that provides _n lines of unified
                 context (where _n shall be interpreted as a non-negative
                 decimal integer).

OOPPEERRAANNDDSS
       The following operands shall be supported:

       _f_i_l_e_1, _f_i_l_e_2
                 A pathname of a file to be compared. If either the _f_i_l_e_1 or
                 _f_i_l_e_2 operand is ''--'', the standard input shall be used in its
                 place.

       If both _f_i_l_e_1 and _f_i_l_e_2 are directories, _d_i_f_f 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 _D_i_f_f _D_i_r_e_c_t_o_r_y _C_o_m_p_a_r_i_s_o_n _F_o_r_m_a_t.  The
       behavior of _d_i_f_f on other file types is implementation-defined when
       found in directories.

       If only one of _f_i_l_e_1 and _f_i_l_e_2 is a directory, _d_i_f_f 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.

SSTTDDIINN
       The standard input shall be used only if one of the _f_i_l_e_1 or _f_i_l_e_2
       operands references standard input. See the INPUT FILES section.

IINNPPUUTT FFIILLEESS
       The input files may be of any type.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _d_i_f_f:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

       _L_C___A_L_L    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       _L_C___C_T_Y_P_E  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).

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

       _L_C___T_I_M_E   Determine the locale for affecting the format of file
                 timestamps written with the --CC and --cc options.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

       _T_Z        Determine the timezone used for calculating file timestamps
                 written with a context format. If _T_Z is unset or null, an
                 unspecified default timezone shall be used.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
   DDiiffff DDiirreeccttoorryy CCoommppaarriissoonn FFoorrmmaatt
       If both _f_i_l_e_1 and _f_i_l_e_2 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", <_d_i_r_e_c_t_o_r_y _p_a_t_h_n_a_m_e>, <_f_i_l_e_n_a_m_e>

       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", <_d_i_r_e_c_t_o_r_y_1 _p_a_t_h_n_a_m_e>,
               <_d_i_r_e_c_t_o_r_y_2 _p_a_t_h_n_a_m_e>

       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", <_d_i_f_f___o_p_t_i_o_n_s>, <_f_i_l_e_n_a_m_e_1>, <_f_i_l_e_n_a_m_e_2>

       where <_d_i_f_f___o_p_t_i_o_n_s> 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).

   DDiiffff BBiinnaarryy OOuuttppuutt FFoorrmmaatt
       In the POSIX locale, if one or both of the files being compared are not
       text files, it is implementation-defined whether _d_i_f_f 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 ""ddiiffffeerr"".

       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.

   DDiiffff DDeeffaauulltt OOuuttppuutt FFoorrmmaatt
       The default (without --ee, --ff, --cc, --CC, --uu, or --UU options) _d_i_f_f utility
       output shall contain lines of these forms:


           "%da%d\n", <_n_u_m_1>, <_n_u_m_2>

           "%da%d,%d\n", <_n_u_m_1>, <_n_u_m_2>, <_n_u_m_3>

           "%dd%d\n", <_n_u_m_1>, <_n_u_m_2>

           "%d,%dd%d\n", <_n_u_m_1>, <_n_u_m_2>, <_n_u_m_3>

           "%dc%d\n", <_n_u_m_1>, <_n_u_m_2>

           "%d,%dc%d\n", <_n_u_m_1>, <_n_u_m_2>, <_n_u_m_3>

           "%dc%d,%d\n", <_n_u_m_1>, <_n_u_m_2>, <_n_u_m_3>

           "%d,%dc%d,%d\n", <_n_u_m_1>, <_n_u_m_2>, <_n_u_m_3>, <_n_u_m_4>

       These lines resemble _e_d subcommands to convert _f_i_l_e_1 into _f_i_l_e_2.  The
       line numbers before the action letters shall pertain to _f_i_l_e_1; those
       after shall pertain to _f_i_l_e_2.  Thus, by exchanging _a for _d and reading
       the line in reverse order, one can also determine how to convert _f_i_l_e_2
       into _f_i_l_e_1.  As in _e_d, identical pairs (where _n_u_m_1= _n_u_m_2) are
       abbreviated as a single number.

       Following each of these lines, _d_i_f_f shall write to standard output all
       lines affected in the first file using the format:


           "< %s", <_l_i_n_e>

       and all lines affected in the second file using the format:


           "> %s", <_l_i_n_e>

       If there are lines affected in both _f_i_l_e_1 and _f_i_l_e_2 (as with the cc
       subcommand), the changes are separated with a line consisting of three
       <hyphen-minus> characters:


           "---\n"

   DDiiffff --ee OOuuttppuutt FFoorrmmaatt
       With the --ee option, a script shall be produced that shall, when
       provided as input to _e_d, along with an appended ww (write) command,
       convert _f_i_l_e_1 into _f_i_l_e_2.  Only the aa (append), cc (change), dd (delete),
       ii (insert), and ss (substitute) commands of _e_d 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.

   DDiiffff --ff OOuuttppuutt FFoorrmmaatt
       With the --ff option, an alternative format of script shall be produced.
       It is similar to that produced by --ee, with the following differences:

        1. It is expressed in reverse sequence; the output of --ee orders
           changes from the end of the file to the beginning; the --ff from
           beginning to end.

        2. The command form <_l_i_n_e_s> <_c_o_m_m_a_n_d_-_l_e_t_t_e_r> used by --ee is reversed.
           For example, 10_c with --ee would be _c10 with --ff.

        3. The form used for ranges of line numbers is <space>-separated,
           rather than <comma>-separated.

   DDiiffff --cc oorr --CC OOuuttppuutt FFoorrmmaatt
       With the --cc or --CC 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 _f_i_l_e_1, and those added
       from _f_i_l_e_2.  With the --cc option, three lines of context, if available,
       shall be written before and after the affected lines. With the --CC
       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", _f_i_l_e_1, <_f_i_l_e_1 _t_i_m_e_s_t_a_m_p>
           "--- %s %s\n", _f_i_l_e_2, <_f_i_l_e_2 _t_i_m_e_s_t_a_m_p>

       Each <_f_i_l_e> field shall be the pathname of the corresponding file being
       compared. The pathname written for standard input is unspecified.

       In the POSIX locale, each <_t_i_m_e_s_t_a_m_p> 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 _f_i_l_e_1 shall be written in the following
       format if the range contains two or more lines:


           "*** %d,%d ****\n", <_b_e_g_i_n_n_i_n_g _l_i_n_e _n_u_m_b_e_r>, <_e_n_d_i_n_g _l_i_n_e _n_u_m_b_e_r>

       and the following format otherwise:


           "*** %d ****\n", <_e_n_d_i_n_g _l_i_n_e _n_u_m_b_e_r>

       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", <_u_n_a_f_f_e_c_t_e_d___l_i_n_e>

       Deleted lines shall be written as:


           "- %s", <_d_e_l_e_t_e_d___l_i_n_e>

       Changed lines shall be written as:


           "! %s", <_c_h_a_n_g_e_d___l_i_n_e>

       Next, the range of lines in _f_i_l_e_2 shall be written in the following
       format if the range contains two or more lines:


           "--- %d,%d ----\n", <_b_e_g_i_n_n_i_n_g _l_i_n_e _n_u_m_b_e_r>, <_e_n_d_i_n_g _l_i_n_e _n_u_m_b_e_r>

       and the following format otherwise:


           "--- %d ----\n", <_e_n_d_i_n_g _l_i_n_e _n_u_m_b_e_r>

       Then, lines of context and changed lines shall be written as described
       in the previous formats. Lines added from _f_i_l_e_2 shall be written in the
       following format:


           "+ %s", <_a_d_d_e_d___l_i_n_e>

   DDiiffff --uu oorr --UU OOuuttppuutt FFoorrmmaatt
       The --uu or --UU options behave like the --cc or --CC 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 <_f_i_l_e> 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 <_t_i_m_e_s_t_a_m_p> 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 <_f_r_a_c> 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 <_z_o_n_e> field shall be of the form ""sshhhhmmmm"", where ""sshhhh"" is a signed
       two-digit decimal number in the range -24 through +25, and ""mmmm"" 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
       <_z_o_n_e> 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 <_r_a_n_g_e> 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 _f_i_l_e_1.
       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 _f_i_l_e_2, even
       though _f_i_l_e_2's line may contain different contents due to the --bb.
       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 --UU _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.  --uu shall act like --UU3.

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    No differences were found.

        1    Differences were found.

       >1    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

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

EEXXAAMMPPLLEESS
       If ddiirr11 is a directory containing a directory named xx, ddiirr22 is a
       directory containing a directory named xx, ddiirr11//xx and ddiirr22//xx both
       contain files named ddaattee..oouutt, and ddiirr22//xx contains a file named yy, 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

RRAATTIIOONNAALLEE
       The --hh 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 --rr option is specified are
       not used by most historical implementations if the --ee 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 --rr 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 --cc 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 _p_a_t_c_h utility
       is most valuable when working with difference listings using a context
       format. The BSD version of --cc takes an optional argument specifying the
       amount of context. Rather than overloading --cc and breaking the Utility
       Syntax Guidelines for _d_i_f_f, the standard developers decided to add a
       separate option for specifying a context diff with a specified amount
       of context (--CC).  Also, the format for context _d_i_f_fs 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 _p_a_t_c_h) 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 _d_i_f_f can do so by adding the
       extra four <asterisk> characters (that is, utilities that currently use
       _d_i_f_f and understand the new merged format will also understand the old
       unmerged format, but not _v_i_c_e _v_e_r_s_a).

       The --uu and --UU options of GNU _d_i_f_f have been included. Their output
       format, designed by Wayne Davison, takes up less space than --cc and --CC
       format, and in many cases is easier to read. The format's timestamps do
       not vary by locale, so _L_C___T_I_M_E does not affect it. The format's line
       numbers are rendered with the %%11dd format, not %%dd, 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 --ee
       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 _d_i_f_f.
       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 --rr option was added to provide a mechanism for using
       _d_i_f_f 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 _f_i_n_d utility.

       The requirement that _d_i_f_f 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 _d_i_f_f to hang waiting for input with no indication to the user
       that _d_i_f_f 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, _d_i_f_f --rr should indicate
       differences in the file hierarchies, not the difference of contents of
       devices pointed to by the hierarchies.

       Many early implementations of _d_i_f_f 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 _d_i_f_f.  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", <_d_i_f_f___o_p_t_i_o_n_s>, <_f_i_l_e_n_a_m_e_1>, <_f_i_l_e_n_a_m_e_2>

       does not vary by locale because it is the representation of a command,
       not an English sentence.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_m_p, _c_o_m_m, _e_d, _f_i_n_d

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

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

       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 .



IEEE/The Open Group                  2017                              DIFF(1)
