TDIFF

NAME

tdiff − tree diff, list differences between various inode attributes ( stat(2) structure) and contents for two directory trees

SYNOPSIS

tdiff [OPTIONS]... DIRECTORY1 DIRECTORY2

DESCRIPTION

List differences between DIRECTORY1 and DIRECTORY2 file trees, comparing any of the inode attributes, also known as stat(2) structure members. Inode attributes are:

By default, tdiff reports differences in any file contents or attributes except for the various file times. The set of attributes to be checked can be modified with the various options.

Beyond inode attribute checks, tdiff can check (and will check by default) regular files for contents difference. Optionally, tdiff can use an external program to determine if the files are considered to be different. See the −x/−−exec, −w/−−exec−always, and −W/−−exec−always−diff options.

OPTIONS

Most single-letter options come in two versions, upper-case and lower-case. The lower-case option enables the the attribute check, while the upper-case option disables it. Similarly, most long options have a −−no− version to turn off the equivalent check.
−a, −−all

Turn on all checks, except for file times.
This is equivalent to −dtmogsbcnejkql or −−dirs −−type −−mode −−owner −−group −−size −−blocks −−contents −−nlinks −−major −−minor −−xattr −−acl.
Note that the file time options are not touched.
This is the default.

−A, −−no−all

Turn off all checks, including file times.
This is equivalent to −DTMOGZIRSBCNEJKQL or −−no−dirs −−no−type −−no−mode −−no−owner −−no−group −−no−ctime −−no−mtime −−no−atime −−no−size −−no−blocks −−no−contents −−no−nlinks −−no−major −−no−minor −−no−xattr −−no−acl.
Unless an other option is used after −A/−−no−all, tdiff will not report anything but will still traverse the file trees.

−b, −−blocks

Report file block count differences for regular files, directories and symbolic links (st_blocks does not make sense on other types of inodes).

−B, −−no−blocks

Do not report file block count differences.

−c, −−contents

Report file content differences for regular files and symbolic links.
For regular files, their contents are compared and any discrepancies are reported as contents difference.
For symbolic links, a difference will be reported if their targets differ.
See the CONTENTS COMPARISONS section below for the exact semantics.

−C, −−no−contents

Do not report file content differences.

−d, −−dirs

Diff directory contents: report if any file is present in only one directory.

−D, −−no−dirs

Do not diff directory contents: files only present in a single directory are not reported.

−g, −−group

Report on any differences in file group ownership (owner group id).

−G, −−no−group

Do not report any differences in file group ownership (owner group id).

−h, −−help

Show a short help message and exit.

−i, −−mtime

Report on any differences in file modification time (st_mtime), up to nanosecond resolution if the underlying OS reports it.

−I, −−no−mtime

Do not report any differences in file modification times (st_mtime).

−j, −−major

For device files (either block or character), report any differences in major device numbers.
Note that major numbers will be compared across same or different (block or character) device file types.

−J, −−no−major

Do not report any differences in major device numbers on device files.

−k, −−minor

For device files (either block or character), report any differences in minor device numbers.
Note that minor numbers will be compared across same or different (block or character) device file types.

−K, −−no−minor

Do not report any differences in minor device numbers on device files.

−l, −−acl

Report on any differences in file ACLs as defined by acl_set_file(3).
Any missing or different ACLs between the file pairs are reported. Access, default and mask ACL entries are supported.

−L, −−no−acl

Do not report any differences in file ACLs.

−m, −−mode

Report on any differences in file access mode (permission bits as set by chmod(1)). If set, −−mode−or and −−mode−and bitmasks are applied

−M, −−no−mode

Do not report any differences in file access modes (permission bits).

−n, −−nlinks

Report on any differences in file (hard) link counts (st_nlinks).

−N, −−no−nlinks

Do not report any differences in file (hard) link counts.

−o, −−owner

Report on any differences in file ownership (owner user id).

−O, −−no−owner

Do not report any differences in file ownership (owner user id).

−q, −−xattr

Report on any differences in file extended attributes as defined by setxattr(2).
Any missing or different extended attributes between the file pairs are reported.

−Q, −−no−xattr

Do not report any differences in file extended attributes.

−r, −−atime

Report on any differences in file access time (st_atime), up to nanosecond resolution if the underlying OS reports it.
Since merely reading a file causes the access time to be updated, this option is likely to be of limited use. tdiff will not update the file access times when comparing files if compiled on an OS with O_NOATIME open(2) support. However commands specified with −x/−−exec, −w/−−exec−always or −W/−−exec−always−diff may update the access times of the files they read.

−R, −−no−atime

Do not report any differences in file access times (st_atime).

−s, −−size

Report file size differences for regular files and symbolic links (st_size does not make sense on other types of inodes).

−S, −−no−size

Do not report file size differences.

−t, −−type

Report file type differences (files, directories, symbolic links, etc.)

−T, −−no−type

Do not report file type differences between the two compared directories.

−v, −−verbose

Increase verbosity, currently reports about the inode cache used to avoid comparing hard-linked files more than once. Four cumulative levels of logging verbosity are supported:

−V, −−version

Show the tdiff version information and compiled-in features then exit.
The compiled-in feature list shows which features tdiff has been compiled with: O_NOATIME, flags, acl, and xattr support, the list of supported file system flags, and the readdir(2) implementation used.

−w, −−exec−always COMMAND... \;

Always execute COMMAND for any pair of matching regular files found in the trees. COMMAND is defined as for the −x/−−exec options.
If the option is specified more than once, the last command defined will be used.

−W, −−exec−always−diff

Always execute diff −u for any pair of matching regular files found in the trees. This is a shortcut for:

tdiff −−exec−always diff −u %1 %2 ;

The option will supersede whichever command was specified in a −w/−−exec−always option appearing earlier on the option list.

−x, −−exec COMMAND... \;

Uses COMMAND when comparing files whose sizes are the same. COMMAND is a command line terminated by a semi-colon, which must be escaped to avoid processing by the shell.
In the arguments can appear the strings %1 and %2 which will be replaced by the paths to files in the first or second compared directories. %1 and %2 can only appear once on the command line, and must be full words: they cannot appear inside a larger shell word.
If the option is specified more than once, the last command defined will be used.

−X, −−exclude FILE

Excludes FILE from processing: any discrepancies on a file or missing file named FILE will not be reported. Neither will external commands be ran on them. If FILE matches the name of a directory, it will not be descended into and any sub-directories or files it contains will be completely ignored.
This option may be specified more than once, all the files listed will be added to the exclusion list.

−z, −−ctime

Report on any differences in file inode change time (st_ctime), up to nanosecond resolution if the underlying OS reports it.
Since inode change times are automatically set by Unix to the current time and cannot be changed afterwards, they will always be reported as different for any two file trees, except in rare cases (likely involving cloning raw file system images).

−Z, −−no−ctime

Do not report any differences in file file inode change times (st_ctime).

−\|, −−mode−or MASK

Note that the pipe character must be escaped to prevent it from being interpreted by the shell.
When comparing file permission bits, perform a binary or between the permission bits and MASK before comparing them.
MASK is specified in octal, like with chmod(2), unless prefixed with 0x, in which case it is parsed as hexadecimal.

−\&, −−mode−and MASK

Note that the ampersand character must be escaped to prevent it from being interpreted by the shell.
When comparing file permission bits, perform a binary and between the permission bits and MASK before comparing them.
MASK is specified in octal, like with chmod(2), unless prefixed with 0x, in which case it is parsed as hexadecimal.

HARD LINKS

tdiff optimizes for hard links in two ways:

For example, if you have file1 hard linked to file2 in both DIRECTORY1 and DIRECTORY2, tdiff will only report any differences for file1 and will skip file2 entirely since it’s linked to file1 in both examined directories, and the list of differences would the same as for the already reported file1 case.

For example, if dir1/file is hard linked to dir2/file, then tdiff will omit examining the file pair entirely since they really are the same object and would have no differences at all.

tdiff’s hard link optimization depends on files’ inode and device numbers to be stable, unique and consistent at least for the duration of the tdiff run. This is generally the case for traditional file systems.

tdiff can optionally show which hard linked files are skipped and for what reason when run at the verbosity level 2 or above (-vv or --verbose --verbose).

CONTENTS COMPARISONS

tdiff uses built-in code for file contents comparisons. It avoid running an actual comparison if the file’s sizes (st_size) are different: the files with different sizes will be reported as having different contents without even comparing them as the size difference is enough to ascertain that their contents differ.

If either the −x or −−exec options are used, the command specified there will be ran instead of the built-in comparison and its exit status used to detect a difference (zero exit status meaning no difference, and non-zero meaning a difference). With either these options in effect, tdiff will not print any error message if the files are different, the command used for −x/−−exec should take care of reporting the error. Note that the command will not be ran if tdiff can find via the file size that the files differ by virtue of having different sizes.

If either the −w/−−exec−always or −W/−−exec−always−diff options are used, the command specified with these options will always be ran for every pair of regular files having the same path in both directories, whether or not they have the same size. The internal comparison pass will run and will report if the files are different, then the −w/−−exec−always/−W/−−exec−always−diff command will run. tdiff will record a difference if the −w/−−exec−always/−W/−−exec−always−diff command returns with non−zero exit status, even if the internal comparison or the −x/−−exec command are successful.

If both −x/−−exec and −w/−−exec−always/−W/−−exec−always−diff options are used, then the command specified for −x/−−exec will be ran if the file sizes of the compared files are the same, and the command specified by −w/−−exec−always/−W/−−exec−always−diff will always run.
This means that with options from both groups active, both the −x/−−exec and −w/−−exec−always/−W/−−exec−always−diff commands will be ran for files with the same size.

EXIT STATUS

tdiff exits with status:

EXAMPLES

Only report if any files are present in only one directory:

tdiff −−no−all −−dirs directory1 directory2

Report only ownership differences, ignore any missing files:

tdiff −−no−all −−owner −−group directory1 directory2

Report only group permission bits differences, ignore any missing files:

tdiff −−no−all −−mode −−mode−and 70 directory1 directory2

or:

tdiff −−no−all −−mode −−mode−or 7707 directory1 directory2

Report only sticky bits differences, ignore any missing files:

tdiff −−no−all −−mode −−mode−and 1000 directory1 directory2

or:

tdiff −−no−all −−mode −−mode−or 6777 directory1 directory2

Run cmp −l on every file of the same size in both trees:

tdiff −−no−all −−exec cmp -l %1 %2 \; directory1 directory2

Run super-diff: diff files with diff −u and reports any other kind of differences in inode contents except for times:

tdiff −−exec−always−diff directory1 directory2

or more tersely:

tdiff −W directory1 directory2

REPORTING BUGS

Report bugs on the GitHub Issues page.

COPYRIGHT

Copyright (C) 1999, 2008, 2014, 2019 Philippe Troin ( F-i-f on GitHub).

tdiff comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it under certain conditions.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

SEE ALSO

acl_set_file(1), chmod(1), diff(1), getfacl(1), getfattr(1), open(2), setxattr(2), stat(2).