dir-compare

library5.0.0jsnpmunverified

dir-compare is a Node.js library for comparing the contents and structure of two directories. It provides both synchronous (`compareSync`) and asynchronous (`compare`) comparison methods, supporting various strategies like size, content, and date comparison, along with advanced filtering options including glob patterns and `.gitignore` rules. The current stable version is 5.0.0, with regular updates addressing features, performance, and bug fixes. Key differentiators include its TypeScript support (since v4.0.0), significant performance improvements for large directory structures (e.g., 3x reduced heap usage and 2x faster content comparison since v4.0.0), and flexible extension points for custom comparators and result builders. The command-line interface (CLI) was moved to a separate package, `dir-compare-cli`, in v3.0.0.

testing devops

npm install dir-compare

github ↗package ↗

INSTALL

IMPORT

SIG · DIR-COMPARE

dir-compare

testingjavascriptv5.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

compare

✓ import { compare } from 'dir-compare';

✗ const dircompare = require('dir-compare'); dircompare.compare(...);

Asynchronous comparison function. Prefer named imports with TypeScript or modern JavaScript. CommonJS `require` works but requires accessing `dircompare.compare`.

compareSync

✓ import { compareSync } from 'dir-compare';

✗ const dircompare = require('dir-compare'); dircompare.compareSync(...);

Synchronous comparison function. Named imports are recommended, especially with TypeScript since v4.0.0.

Options

✓ import { Options } from 'dir-compare';

TypeScript interface for comparison options. Essential when writing strongly-typed comparison logic.

Result

✓ import { Result } from 'dir-compare';

TypeScript interface for the comparison result object. Provides strong typing for accessing comparison statistics and the diffSet.

This quickstart demonstrates both synchronous and asynchronous directory comparison using `dir-compare`. It creates temporary directories, populates them with files, and then compares them using options for size and content, while excluding a specific file. It logs the comparison summary and detailed differences.

import { compare, compareSync, Options, Result } from 'dir-compare'; import * as path from 'path'; import * * as fs from 'fs'; // Create dummy directories and files for demonstration const dir1 = path.join(__dirname, 'test-dir1'); const dir2 = path.join(__dirname, 'test-dir2'); fs.mkdirSync(dir1, { recursive: true }); fs.mkdirSync(dir2, { recursive: true }); fs.writeFileSync(path.join(dir1, 'fileA.txt'), 'Content A'); fs.writeFileSync(path.join(dir1, 'fileB.txt'), 'Content B'); fs.writeFileSync(path.join(dir2, 'fileA.txt'), 'Content A'); fs.writeFileSync(path.join(dir2, 'fileC.txt'), 'Content C'); const options: Options = { compareSize: true, compareContent: true, excludeFilter: 'fileB.txt' }; console.log('--- Synchronous Comparison ---'); try { const resSync: Result = compareSync(dir1, dir2, options); console.log('Directories are %s', resSync.same ? 'identical' : 'different'); console.log('Equal entries: %s, Distinct entries: %s, Left only: %s, Right only: %s', resSync.equal, resSync.distinct, resSync.left, resSync.right); resSync.diffSet.forEach(dif => { console.log(`- Path: ${dif.relativePath}, Name1: ${dif.name1}, Name2: ${dif.name2}, State: ${dif.state}`); }); } catch (error) { console.error('Synchronous comparison failed:', error); } console.log('\n--- Asynchronous Comparison ---'); compare(dir1, dir2, options) .then(resAsync => { console.log('Directories are %s', resAsync.same ? 'identical' : 'different'); console.log('Equal entries: %s, Distinct entries: %s, Left only: %s, Right only: %s', resAsync.equal, resAsync.distinct, resAsync.left, resAsync.right); resAsync.diffSet.forEach(dif => { console.log(`- Path: ${dif.relativePath}, Name1: ${dif.name1}, Name2: ${dif.name2}, State: ${dif.state}`); }); }) .catch(error => console.error('Asynchronous comparison failed:', error)) .finally(() => { // Cleanup dummy directories fs.rmSync(dir1, { recursive: true, force: true }); fs.rmSync(dir2, { recursive: true, force: true }); });

Debug

Known issues

breakingThe `skipSubdirs` option now behaves slightly differently, potentially affecting how comparisons handle subdirectories. Review issue #77 for specifics.

fix

Carefully test existing comparison logic if `skipSubdirs` is used and adjust expectations or options if necessary.

affects: >=5.0.0

breakingWhen using `dir-compare` to compare two individual files (not directories), the names of the files are now ignored in the comparison. This primarily affects scenarios where `dir-compare` was used for direct file-to-file comparison and relied on name matching.

fix

If file name comparison is critical when comparing two specific files, implement a separate name check or ensure the files are placed within temporary directories for a full directory comparison.

affects: >=4.0.0

breakingThe project was switched to TypeScript in v4.0.0. While existing JavaScript usage generally remains compatible, direct imports for types (`Options`, `Result`) are now available, and the internal structure is type-checked. This might implicitly affect type inference in certain editors for existing JavaScript projects.

fix

For TypeScript projects, update imports to use named imports (e.g., `import { compare, Options } from 'dir-compare';`). JavaScript projects should continue to function but may benefit from type definitions.

affects: >=4.0.0

breakingThe command-line interface (CLI) utility was extracted into a separate package, `dir-compare-cli`. The `dir-compare` package now only provides the library API.

fix

If you rely on the `dir-compare` CLI, install `dir-compare-cli` separately (`npm install -g dir-compare-cli`) and use its commands instead.

affects: >=3.0.0

gotchaThe `origin` field was added to the `Entry` interface (within `diffSet`) to distinguish whether an entry originated from the left or right directory. This provides more granular information but requires updating code that processed `diffSet` entries if `origin` is now relevant.

fix

Review code that processes `diffSet` entries to leverage the new `origin` field for more precise handling of left-only vs. right-only differences, if needed.

affects: >=4.1.0

gotchaSince v4.1.0, the library offers enhanced glob filter capabilities and the ability to implement `.gitignore` rules. If custom filtering logic was previously implemented manually, these new features can simplify the code.

fix

Consider refactoring custom filtering logic to utilize the new `glob filter` and `.gitignore` implementation features provided by the library, which can improve maintainability and robustness.

affects: >=4.1.0

Errors

Common errors & fixes

TypeError: dircompare.compare is not a function

Attempting to call `dircompare.compare` directly after a CommonJS `require('dir-compare')` on versions 4.0.0+ when the library might expose named exports more prominently, or if trying to call an async function synchronously.

fix

For CommonJS, try `const { compare, compareSync } = require('dir-compare');` or for modern ES Modules: `import { compare, compareSync } from 'dir-compare';`. Ensure you are calling `compare` (async) with `.then()`/`await` or `compareSync` (sync) appropriately.

Error: EACCES: permission denied, open 'path/to/file'

The Node.js process does not have sufficient read permissions for one or both of the directories or files being compared.

fix

Ensure the user running the Node.js application has read and execute permissions on all directories and files within the comparison paths. Alternatively, `dir-compare` added support for handling permission denied errors in v3.2.0; investigate options for graceful error handling within the comparison process if appropriate.

TypeError: Cannot read properties of undefined (reading 'diffSet')

This usually happens if the `compare` or `compareSync` function failed to execute or returned an unexpected value (e.g., `null` or `undefined`) instead of a `Result` object, and subsequent code tries to access properties like `diffSet`.

fix

Wrap the comparison call in a `try...catch` block (for sync) or add a `.catch()` handler (for async) to properly handle potential errors during the comparison process. Also, verify that the input paths are valid and accessible.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

minimatchrequiredUsed internally for glob pattern filtering (includeFilter, excludeFilter).

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/gliviu/dir-compare ↗

packagehttps://www.npmjs.com/package/dir-compare ↗