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.
dir-compare
Node JS directory compare
!! Important !! Starting with v3.0.0 the CLI utility has been moved to dir-compare-cli.
Installation
npm install dir-compare
Library
Use
const dircompare = require('dir-compare');
const options = { compareSize: true };
const path1 = '...';
const path2 = '...';
const res = dircompare.compareSync(path1, path2, options)
print(res)
dircompare.compare(path1, path2, options)
.then(res => print(res))
.catch(error => console.error(error));
function print(result) {
console.log('Directories are %s', result.same ? 'identical' : 'different')
console.log('Statistics - equal entries: %s, distinct entries: %s, left only entries: %s, right only entries: %s, differences: %s',
result.equal, result.distinct, result.left, result.right, result.differences)
result.diffSet.forEach(dif => console.log('Difference - name1: %s, type1: %s, name2: %s, type2: %s, state: %s',
dif.name1, dif.type1, dif.name2, dif.type2, dif.state))
}
Typescript
import { compare, compareSync, Options, Result } from "dir-compare";
const path1 = '...';
const path2 = '...';
const options: Options = { compareSize: true };
const res: Result = compareSync(path1, path2, options);
console.log(res)
compare(path1, path2, options)
.then(res => console.log(res))
.catch(error => console.error(error));
Api
compare(path1: string, path2: string, options?: Options): Promise<Result>
compareSync(path1: string, path2: string, options?: Options): Result
More details can be found in the reference documentation:
Common options:
Glob patterns
Minimatch patterns are used to include/exclude files to be compared.
The pattern is matched against the relative path of the entry being compared.
Following examples assume we are comparing two dir-compare code bases.
const options = {
excludeFilter: ".git,node_modules",
excludeFilter: "expected" ,
excludeFilter: "/tests/expected" ,
excludeFilter: "**/expected" ,
excludeFilter: "**/tests/**/*.js" ,
includeFilter: "*.js,*.yml" ,
includeFilter: "/tests/**/*.js" ,
includeFilter: "**/tests/**/*.ts"
}
Custom file content comparators
By default file content is binary compared. As of version 1.5.0 custom file comparison handlers may be specified.
Custom handlers are specified by compareFileSync
and compareFileAsync
options which correspond to dircompare.compareSync()
or dircompare.compare()
methods.
A couple of handlers are included in the library:
- binary sync compare -
dircompare.fileCompareHandlers.defaultFileCompare.compareSync
- binary async compare -
dircompare.fileCompareHandlers.defaultFileCompare.compareAsync
- text sync compare -
dircompare.fileCompareHandlers.lineBasedFileCompare.compareSync
- text async compare -
dircompare.fileCompareHandlers.lineBasedFileCompare.compareAsync
Use defaultFileCompare.js as an example to create your own.
Ignore line endings and white spaces
Line based comparator can be used to ignore line ending and white space differences.
const dircompare = require('dir-compare');
const options = {
compareContent: true,
compareFileSync: dircompare.fileCompareHandlers.lineBasedFileCompare.compareSync,
compareFileAsync: dircompare.fileCompareHandlers.lineBasedFileCompare.compareAsync,
ignoreLineEnding: true,
ignoreWhiteSpaces: true,
ignoreAllWhiteSpaces: true,
ignoreEmptyLines: true
};
const path1 = '...';
const path2 = '...';
const res = dircompare.compareSync(path1, path2, options);
console.log(res)
dircompare.compare(path1, path2, options)
.then(res => console.log(res))
Custom name comparators
If default name comparison is not enough, custom behavior can be specified with compareNameHandler option.
Following example adds the possibility to ignore file extensions.
import { Options, compare } from 'dir-compare'
import path from 'path'
const options: Options = {
compareSize: false,
compareContent: false,
compareNameHandler: customNameCompare,
ignoreExtension: true,
};
function customNameCompare(name1: string, name2: string, options: Options) {
if (options.ignoreCase) {
name1 = name1.toLowerCase()
name2 = name2.toLowerCase()
}
if (options.ignoreExtension) {
name1 = path.basename(name1, path.extname(name1))
name2 = path.basename(name2, path.extname(name2))
}
return ((name1 === name2) ? 0 : ((name1 > name2) ? 1 : -1))
}
const path1 = '/tmp/a';
const path2 = '/tmp/b';
const res = compare(path1, path2, options).then(res => {
console.log(`Same: ${res.same}`)
if (!res.diffSet) {
return
}
res.diffSet.forEach(dif => console.log(`${dif.name1} ${dif.name2} ${dif.state}`))
})
Custom result builder
Result builder is called for each pair of entries encountered during comparison. Its purpose is to append entries in diffSet
and eventually update statistics
object with new stats.
If needed it can be replaced with custom implementation.
const dircompare = require("dircompare")
const customResultBuilder = function (entry1, entry2, state, level, relativePath, options, statistics, diffSet, reason) {
...
}
const options = {
compareSize: true,
resultBuilder: customResultBuilder
}
const res = dircompare.compareSync('...', '...', options)
The default builder can be used as an example.
Symbolic links
Unless compareSymlink
option is used, symbolic links are resolved and any comparison is applied to the file/directory they point to.
Circular loops are handled by breaking the loop as soon as it is detected.
Version 1.x
treats broken links as ENOENT: no such file or directory
.
Since 2.0
they are treated as a special type of entry - broken-link
- and are available as stats (totalBrokenLinks
, distinctBrokenLinks
, ...).
Using compareSymlink
option causes dircompare
to check symlink values for equality.
In this mode two entries with identical name are considered different if
- one is symlink, the other is not
- both are symlinks but point to different locations
These rules are applied in addition to the other comparison modes; ie. by content, by size...
If entries are different because of symlinks, reason
will be different-symlink
. Also statistics summarizes differences caused by symbolik links.
Handling permission denied errors
Unreadable files or directories are normally reported as errors. The comparison will be intrerrupted with an EACCES
exception.
This behavior can be altered with Options.handlePermissionDenied.
UI tools
Changelog
-
v4.0.0
- Switched project to typescript
- Async comparator improvements when comparing large directory structures
- Heap usage has decreased 3x compared to previous version
- Works 2x faster when comparing by content
- Better concurrency. UI apps will be more responsive while comparison is ongoing
Breaking changes:
- Using this library to compare two files will ignore the name of the files. More details in #48
- Removed support for node 8, 9
-
v3.3.0 Added skipEmptyDirs
option
-
v3.2.0 Handle permission denied errors
-
v3.1.0 Added ignoreAllWhiteSpaces
and ignoreEmptyLines
options
-
v3.0.0 Moved CLI component into separate project dir-compare-cli
-
v2.4.0 New option to customize file/folder name comparison
-
v2.3.0 Fixes
-
v2.1.0 Removed bluebird dependency
-
v2.0.0
- New option to compare symlinks.
- New field indicating reason for two entries being distinct.
- Improved command line output format.
- Tests are no longer part of published package.
- Generated Api documentation.
Breaking changes:
- Broken links are no longer treated as errors. As a result there are new statistics (leftBrokenLinks, rightBrokenLinks, distinctBrokenLinks, totalBrokenLinks) and new entry type - broken-link.
Details in Symbolic links.
- Typescript correction: new interface
Result
replaced Statistics
.
-
v1.8.0
- globstar patterns
- typescript corrections
- removed support for node 0.11, 0.12, iojs
-
v1.7.0 performance improvements
-
v1.6.0 typescript support
-
v1.5.0 added option to ignore line endings and white space differences
-
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 comparison
- 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