dir-compare

What is dir-compare?

The dir-compare npm package is used to compare the contents of directories. It can compare files and subdirectories, providing detailed information about differences and similarities. This package is useful for tasks such as synchronizing directories, verifying backups, and ensuring consistency between different environments.

What are dir-compare's main functionalities?

Basic Directory Comparison

This feature allows you to compare two directories. The `compareSync` method performs a synchronous comparison, and the `compareContent` option ensures that file contents are compared as well.

const dircompare = require('dir-compare');
const options = { compareContent: true };
const res = dircompare.compareSync('path/to/dir1', 'path/to/dir2', options);
console.log(res);

Asynchronous Directory Comparison

This feature allows you to perform an asynchronous comparison of two directories. The `compare` method returns a promise that resolves with the comparison result.

const dircompare = require('dir-compare');
const options = { compareContent: true };
dircompare.compare('path/to/dir1', 'path/to/dir2', options)
  .then(res => console.log(res))
  .catch(error => console.error(error));

Custom Comparison Options

This feature allows you to customize the comparison process with various options. For example, you can exclude certain file types or include only specific file types in the comparison.

const dircompare = require('dir-compare');
const options = { compareContent: true, excludeFilter: '*.txt', includeFilter: '*.js' };
const res = dircompare.compareSync('path/to/dir1', 'path/to/dir2', options);
console.log(res);

Detailed Comparison Result

This feature provides detailed information about the comparison result. The `diffSet` property contains an array of differences, which you can iterate over to get detailed information about each difference.

const dircompare = require('dir-compare');
const options = { compareContent: true };
const res = dircompare.compareSync('path/to/dir1', 'path/to/dir2', options);
res.diffSet.forEach(dif => console.log(dif));

Other packages similar to dir-compare

diff

The diff package provides a way to compare text differences between two strings or files. While it is more focused on text comparison rather than directory structures, it can be used to compare file contents in a more granular way.

fs-extra

The fs-extra package extends the native Node.js fs module with additional methods, including methods for copying, moving, and removing directories. While it does not provide direct comparison features, it can be used in conjunction with other tools to manage directory contents.

rsyncwrapper

The rsyncwrapper package is a Node.js wrapper for the rsync command-line utility. It can be used to synchronize directories and files between different locations. While it focuses on synchronization rather than comparison, it can be used to achieve similar goals.

README

dir-compare

Node JS directory compare

Installation

$ npm install dir-compare

or

$ npm install dir-compare -g

for command line utility.

Library usage

Synchronous mode:

var dircompare = require('dir-compare');
var options = {compareSize: true};
var path1 = '...';
var path2 = '...';
var res = dircompare.compareSync(path1, path2, options);
console.log('equal: ' + res.equal);
console.log('distinct: ' + res.distinct);
console.log('left: ' + res.left);
console.log('right: ' + res.right);
console.log('differences: ' + res.differences);
console.log('same: ' + res.same);
var format = require('util').format;
res.diffSet.forEach(function (entry) {
    var state = {
        'equal' : '==',
        'left' : '->',
        'right' : '<-',
        'distinct' : '<>'
    }[entry.state];
    var name1 = entry.name1 ? entry.name1 : '';
    var name2 = entry.name2 ? entry.name2 : '';

    console.log(format('%s(%s)%s%s(%s)', name1, entry.type1, state, name2, entry.type2));
});

Asynchronous:

var dircompare = require('dir-compare');
var options = {compareSize: true};
var path1 = '...';
var path2 = '...';
dircompare.compare(path1, path2, options).then(function(res){
    console.log('equal: ' + res.equal);
    console.log('distinct: ' + res.distinct);
    console.log('left: ' + res.left);
    console.log('right: ' + res.right);
    console.log('differences: ' + res.differences);
    console.log('same: ' + res.same);
    var format = require('util').format;
    res.diffSet.forEach(function (entry) {
        var state = {
            'equal' : '==',
            'left' : '->',
            'right' : '<-',
            'distinct' : '<>'
        }[entry.state];
        var name1 = entry.name1 ? entry.name1 : '';
        var name2 = entry.name2 ? entry.name2 : '';

        console.log(format('%s(%s)%s%s(%s)', name1, entry.type1, state, name2, entry.type2));
    });    
}).catch(function(error){
    console.error(error);
})

Options:

• compareSize: true/false - Compares files by size. Defaults to 'false'.
• compareDate: true/false - Compares files by date of modification (stat.mtime). Defaults to 'false'.
• dateTolerance: milliseconds - Two files are considered to have the same date if the difference between their modification dates fits within date tolerance. Defaults to 1000 ms.
• compareContent: true/false - Compares files by content. Defaults to 'false'.
• skipSubdirs: true/false - Skips sub directories. Defaults to 'false'.
• skipSymlinks: true/false - Ignore symbolic links. Defaults to 'false'.
• ignoreCase: true/false - Ignores case when comparing names. Defaults to 'false'.
• noDiffSet: true/false - Toggles presence of diffSet in output. If true, only statistics are provided. Use this when comparing large number of files to avoid out of memory situations. Defaults to 'false'.
• includeFilter: File name filter. Comma separated minimatch patterns.
• excludeFilter: File/directory name exclude filter. Comma separated minimatch patterns.
• resultBuilder: Callback for constructing result - function (entry1, entry2, state, level, relativePath, options, statistics, diffSet). Called for each compared entry pair. Updates 'statistics' and 'diffSet'. Example here

Result:

• distinct: number of distinct entries
• equal: number of equal entries
• left: number of entries only in path1
• right: number of entries only in path2
• differences: total number of differences (distinct+left+right)
• distinctFiles: number of distinct files
• equalFiles: number of equal files
• leftFiles: number of files only in path1
• rightFiles: number of files only in path2
• differencesFiles: total number of different files (distinctFiles+leftFiles+rightFiles)
• distinctDirs: number of distinct directories
• equalDirs: number of equal directories
• leftDirs: number of directories only in path1
• rightDirs: number of directories only in path2
• differencesDirs: total number of different directories (distinctDirs+leftDirs+rightDirs)
• same: true if directories are identical
• diffSet - List of changes (present if Options.noDiffSet is false)
  • path1: absolute path not including file/directory name,
  • path2: absolute path not including file/directory name,
  • relativePath: common path relative to root,
  • name1: file/directory name
  • name2: file/directory name
  • state: one of equal, left, right, distinct,
  • type1: one of missing, file, directory
  • type2: one of missing, file, directory
  • size1: file size
  • size2: file size
  • date1: modification date (stat.mtime)
  • date2: modification date (stat.mtime)
  • level: depth

Command line

  Usage: dircompare [options] leftdir rightdir

  Options:

    -h, --help               output usage information
    -V, --version            output the version number
    -c, --compare-content    compare files by content
    -D, --compare-date       compare files by date
    --date-tolerance [type]  tolerance to be used in date comparison (milliseconds)
    -f, --filter [type]      file name filter
    -x, --exclude [type]     file/directory name exclude filter
    -S, --skip-subdirs       do not recurse into subdirectories
    -L, --skip-symlinks      ignore symlinks
    -i, --ignore-case        ignores case when comparing file names
    -l, --show-left          report - show entries occurring in leftdir
    -r, --show-right         report - show entries occurring in rightdir
    -e, --show-equal         report - show identic entries occuring in both dirs
    -d, --show-distinct      report - show distinct entries occuring in both dirs
    -a, --show-all           report - show all entries
    -w, --whole-report       report - include directories in detailed report
    --csv                    report - print details as csv
    --nocolors               don't use console colors
    --async                  Make use of multiple cores

  By default files are compared by size.
  --date-tolerance defaults to 1000 ms. Two files are considered to have
  the same date if the difference between their modification dates fits
  within date tolerance.

  Exit codes:
    0 - entries are identical
    1 - entries are different
    2 - error occurred

  Examples:
  compare by content         dircompare -c dir1 dir2
  exclude filter             dircompare -x .git dir1 dir2
  include filter             dircompare -f *.js,*.yml dir1 dir2
  show only different files  dircompare -d dir1 dir2

Changelog

• v1.3.0
  • added date tolerance option
• v1.2.0
  • added compare by date option
• v1.1.0
  • detect symlink loops
  • improved color scheme for command line utility
• v1.0.0
  • asynchronous processing
  • new library options: noDiffSet, resultBuilder
  • new statistics: distinctFiles, equalFiles, leftFiles, rightFiles, distinctDirs, equalDirs, leftDirs, rightDirs
  • new --async command line option
  • Fix for https://github.com/tj/commander.js/issues/125
• v0.0.3 Fix fille ordering issue for newer node versions