Compare Examples¶

Practical recipes for comparing directory structures. For an overview, see the Compare guide.

Basic Comparisons¶

# Side-by-side in the terminal
recursivist compare dir1 dir2

# Save as HTML (writes comparison.html)
recursivist compare dir1 dir2 --save

# Choose a location and filename
recursivist compare dir1 dir2 --save --output-dir ./reports --prefix dir-diff

Items unique to the first directory are highlighted in green; items unique to the second, in red.

Comparing GitHub Repositories¶

Either side of a comparison can be a GitHub repository URL:

# Local checkout against the upstream repository
recursivist compare ./my-fork https://github.com/owner/repo

# Two GitHub repositories
recursivist compare https://github.com/owner/repo-a https://github.com/owner/repo-b

# Two branches of the same repository, saved as HTML
recursivist compare \
  https://github.com/owner/repo/tree/main \
  https://github.com/owner/repo/tree/develop \
  --save --prefix main-vs-develop

Set GITHUB_TOKEN (or GH_TOKEN) to raise rate limits and reach private repositories. When both sides are GitHub repositories, the Git-status, modification-time, and ignore-file options are skipped; in a mixed comparison they still apply to the local side.

Comparisons with Statistics¶

recursivist compare dir1 dir2 --sort-by-loc
recursivist compare dir1 dir2 --sort-by-size
recursivist compare dir1 dir2 --mtime               # show mtime, keep default order
recursivist compare dir1 dir2 --sort-by-loc --size  # sort by LOC, show LOC and size

Filtered Comparisons¶

# Exclude directories and extensions
recursivist compare dir1 dir2 --exclude node_modules --exclude .git --exclude-ext .pyc --exclude-ext .log

# Focus on a file type by name
recursivist compare dir1 dir2 --include-pattern "*.js"

# Respect a gitignore-style file
recursivist compare dir1 dir2 --ignore-file .gitignore

# Limit depth
recursivist compare dir1 dir2 --depth 2

Real-World Uses¶

Compare Two Versions¶

recursivist compare project-v1.0 project-v2.0 \
  --exclude node_modules --exclude .git \
  --save --prefix v1-vs-v2 --sort-by-loc

Compare Two Git Branches¶

git clone -b main repo main-branch
git clone -b feature/new-feature repo feature-branch

recursivist compare main-branch feature-branch \
  --exclude node_modules --exclude .git \
  --save --prefix branch-comparison --sort-by-loc

Source vs. Build¶

recursivist compare src dist --include-pattern "*.js" --save --sort-by-size

Backup Verification¶

recursivist compare original-files backup-files --full-path --save --sort-by-size

In Continuous Integration¶

A GitHub Actions step that compares a pull request against main and uploads the result:

- name: Compare structures
  run: |
    recursivist compare main-branch pr-branch \
      --exclude node_modules --exclude .git \
      --save --prefix structure-diff --sort-by-loc

- uses: actions/upload-artifact@v4
  with:
    name: structure-comparison
    path: structure-diff.html