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 names 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 summarize differences caused by symbolic links.
Handling permission denied errors
Unreadable files or directories are normally reported as errors. The comparison will be interrupted with an EACCES exception.
This behavior can be altered with Options.handlePermissionDenied.
Extension points
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.
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, // Ignore crlf/lf line ending differences ignoreWhiteSpaces: true, // Ignore white spaces at the beginning and end of a line (similar to 'diff -b') ignoreAllWhiteSpaces: true, // Ignore all white space differences (similar to 'diff -w') ignoreEmptyLines: true // Ignores differences caused by empty lines (similar to 'diff -B')};const path1 = '...';const path2 = '...';const res = dircompare.compareSync(path1, path2, options);console.log(res)dircompare.compare(path1, path2, options).then(res => console.log(res))
Globby library provides the functionality to parse and apply .gitignore rules.
This is a sample implementation that uses globby and dir-compare filter extension.
Usage:
import { Options, compareSync, Result} from 'dir-compare'import { getGitignoreFilter } from './gitignoreFilter.js'var d1 = '...';var d2 = '...';const options: Options = { compareSize: true, filterHandler: getGitignoreFilter(d1, d2), includeFilter: '*.js' // if present, regular filters are applied after .gitignore rules.}const res: Result = compareSync(d1, d2, options)
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, // compare only name by disabling size and content criteria compareContent: false, compareNameHandler: customNameCompare, // new name comparator used to ignore extensions ignoreExtension: true, // supported by the custom name compare below};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}`))})// Outputs// icon.svg icon.png equal// logo.svg logo.jpg equal
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.
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