Compare¶

The compare command allows you to compare two directory structures side by side with highlighted differences. This guide explains how to use it effectively.

Basic Comparison¶

To compare two directories:

recursivist compare dir1 dir2

This will display both directory trees side by side in the terminal, with highlighted differences between them.

Understanding the Output¶

The comparison output uses color highlighting to show differences:

• Items that exist in both directories are displayed normally
• Items unique to directory 1 are highlighted in green
• Items unique to directory 2 are highlighted in red

A legend explains the color coding at the top of the output.

Including File Statistics¶

You can include file statistics in the comparison:

# Include lines of code
recursivist compare dir1 dir2 --sort-by-loc

# Include file sizes
recursivist compare dir1 dir2 --sort-by-size

# Include modification times
recursivist compare dir1 dir2 --sort-by-mtime

# Combine multiple statistics
recursivist compare dir1 dir2 --sort-by-loc --sort-by-size

This makes it easy to see not just structural differences but also differences in file content size, modification time, or other metrics.

Exporting Comparison Results¶

By default, the comparison is displayed in the terminal. To save it as an HTML file:

recursivist compare dir1 dir2 --save

This creates an HTML file named comparison.html in the current directory.

To specify a different output directory:

recursivist compare dir1 dir2 --save --output-dir ./reports

To customize the filename prefix:

recursivist compare dir1 dir2 --save --prefix project-diff

This creates a file named project-diff.html.

Filtering the Comparison¶

All of the filtering options available for other Recursivist commands also work with compare:

Excluding Directories¶

recursivist compare dir1 dir2 --exclude "node_modules .git"

Excluding File Extensions¶

recursivist compare dir1 dir2 --exclude-ext ".pyc .log"

Pattern-Based Filtering¶

# Exclude with glob patterns (default)
recursivist compare dir1 dir2 --exclude-pattern "*.test.js"

# Exclude with regex patterns
recursivist compare dir1 dir2 --exclude-pattern "^test_.*\.py$" --regex

# Include only specific patterns
recursivist compare dir1 dir2 --include-pattern "src/*" "*.md"

See the Pattern Filtering guide for more details.

Using Gitignore Files¶

recursivist compare dir1 dir2 --ignore-file .gitignore

Depth Control¶

For large directories, limit the comparison depth:

recursivist compare dir1 dir2 --depth 3

Full Path Display¶

To show full paths instead of just filenames:

recursivist compare dir1 dir2 --full-path

Use Cases¶

The comparison feature is particularly useful for:

Project Evolution¶

Compare different versions of a project:

recursivist compare project-v1.0 project-v2.0

Code Reviews¶

Compare branches or pull requests:

# Clone the branches to compare
git clone -b main repo main-branch
git clone -b feature/new-feature repo feature-branch

# Compare directory structures
recursivist compare main-branch feature-branch

Deployment Verification¶

Compare local development and production environments:

recursivist compare local-build production-build

Backup Validation¶

Compare original files with backups:

recursivist compare original-files backup-files

Examples¶

Basic Comparison¶

recursivist compare project-v1 project-v2

Compare with Exclusions¶

recursivist compare project-v1 project-v2 \
--exclude "node_modules .git" \
--exclude-ext ".pyc .log"

Compare with Depth Limit and HTML Export¶

recursivist compare project-v1 project-v2 \
--depth 3 \
--save \
--output-dir ./reports \
--prefix version-comparison

Compare Source Directories Only¶

recursivist compare project-v1/src project-v2/src \
--include-pattern "*.js" "*.css" "*.jsx"

Compare with File Statistics¶

recursivist compare project-v1 project-v2 \
--sort-by-loc \
--sort-by-size

HTML Output Features¶

When exporting to HTML (--save option), the generated file includes:

• Interactive, side-by-side comparison
• Color-coded highlighting of differences
• Responsive layout that works on different screen sizes
• Proper styling for directories and files
• File statistics display when enabled
• Detailed metadata about the comparison settings
• Visual legend explaining the highlighting scheme

This is useful for sharing comparison results with team members or keeping records of structural changes.

Terminal Compatibility¶

The terminal comparison view works best in terminals with:

• Unicode support for special characters
• ANSI color support
• Sufficient width to display side-by-side content

For narrow terminals, the comparison may not display optimally. In these cases, using the HTML export option (--save) is recommended.