Directory Compare CLI

1.0.1 · maintenance · verified Wed Apr 22

dir-compare-cli is a command-line interface (CLI) utility built for Node.js that enables users to compare the contents of two directories. It functions as a wrapper around the `dir-compare` library, providing a convenient console interface for directory comparison tasks. Currently stable at version 1.0.1, its release cadence is generally tied to updates and maintenance of its underlying library or when specific CLI-focused enhancements are required. Key differentiators include its robust set of comparison options, allowing comparisons by file size (default), content, modification date, and symlink targets. It also supports powerful file and directory filtering using Minimatch glob patterns, and offers detailed reporting capabilities including CSV output and distinct exit codes for scripting automation.

Common errors

```
dircompare: command not found
```
cause The `dir-compare-cli` package was installed locally or not installed globally.

fix Install the package globally using `npm install -g dir-compare-cli` to make the `dircompare` command available in your system's PATH.
```
Error: ENOENT: no such file or directory, stat 'leftdir'
```
cause One of the provided directory paths (`leftdir` or `rightdir`) does not exist or is misspelled.

fix Verify that both directory paths provided to `dircompare` are correct and exist on your filesystem. Use absolute paths or ensure you are running the command from the correct working directory.
```
Exit code 1, but I expected identical directories.
```
cause The default comparison mode (by file size) might find differences even if content is identical, or vice-versa. Or, other criteria like dates or symlinks might differ.

fix Review the command options. Add `-a` or `--show-all` to see a detailed report of all entries and their differences. Explicitly use `-c` for content comparison, `-D` for date, or check for filters that might be excluding relevant files.

Warnings

gotcha By default, `dircompare` only compares files by size. To ensure a thorough comparison, especially for identifying subtle changes, always explicitly use the `-c` or `--compare-content` flag.
Fix: Always add `-c` or `--compare-content` to your command for content-based comparisons: `dircompare -c dir1 dir2`.
gotcha The CLI uses specific exit codes: `0` for identical directories, `1` for distinct directories, and `2` for errors. Scripts relying on `dircompare` should always check these exit codes for proper control flow.
Fix: In shell scripts, check the `$?` variable (or equivalent) after execution: `dircompare dir1 dir2; if [ $? -eq 1 ]; then echo 'Directories are different.'; fi`.
gotcha When comparing by date using `-D`, the `--date-tolerance` flag defaults to `1000` milliseconds (1 second). Files with modification dates differing by less than this tolerance will be considered identical. This can lead to false positives if precision is critical.
Fix: For stricter date comparison, set `--date-tolerance` to `0` or a very small value: `dircompare -D --date-tolerance 0 dir1 dir2`.
gotcha Filter and exclude patterns (`-f`, `-x`) utilize Minimatch glob patterns, which match against the *relative path* of entries. Absolute paths or incorrect pattern syntax can lead to unexpected filtering results.
Fix: Consult the Minimatch documentation for correct glob pattern syntax. Use relative paths for filters, e.g., `dircompare -x "**/node_modules" dir1 dir2`.

Install

npm install dir-compare-cli npm
yarn add dir-compare-cli yarn
pnpm add dir-compare-cli pnpm

Quickstart

This example demonstrates how to install the CLI globally and then use it to compare two directories by content, explicitly showing only distinct files and the reason for their differences.

# Install globally to make the 'dircompare' command available
npm install -g dir-compare-cli

# Create some dummy directories and files for demonstration
mkdir -p dir1/subdir
echo "Hello from file1" > dir1/file1.txt
echo "Hello from file2" > dir1/subdir/file2.js

mkdir -p dir2/subdir
echo "Hello from file1" > dir2/file1.txt
echo "Modified content" > dir2/subdir/file2.js
echo "New file" > dir2/new_file.txt

# Compare dir1 and dir2 by content, showing only distinct entries
# and include the reason for distinction.
# Exit code 1 indicates differences were found.
dircompare -c -d --reason dir1 dir2

# Clean up dummy directories
rm -rf dir1 dir2

view raw JSON →