GitHub - Teycir/DiffCatcher: A Rust CLI tool that recursively discovers Git repositories, captures state changes, generates diffs, extracts code elements with full snippets, and produces security-focused reports for code review and audit workflows.

Support Development

If this project helps your work, support ongoing maintenance and new features.

ETH Donation Wallet
0x11282eE5726B3370c8B480e321b3B2aA13686582

Scan the QR code or copy the wallet address above.

A Rust CLI tool that recursively discovers Git repositories, captures state changes, generates diffs, extracts code elements with full snippets, and produces security-focused reports for code review and audit workflows.

🎯 Key Features

Repository Discovery: Recursively scan directories for Git repos with configurable filters
State Tracking: Capture pre/post-pull state with commit hashes, messages, and dirty detection
Diff Generation: Automatic N vs N-1 and historical diff creation with file manifests
Element Extraction: Parse diffs to identify functions, structs, classes, imports, and more across 10+ languages
Code Snippets: Extract full before/after code with boundary detection and context windows
Security Tagging: 18 built-in security patterns (crypto, auth, secrets, SQL injection, XSS, etc.)
Multi-Format Reports: JSON, Markdown, text, and SARIF outputs with cross-repo security overview
Branch-Diff Mode: Diff any two refs (branches, tags, commits) in a single repo — ideal for PR reviews
Performance: Parallel processing with progress bars, LRU caching, and incremental mode

Why not just use bash?

A one-liner like ls | while read line; do git -C "$line" diff HEAD~1 HEAD || true; done only shows raw diffs. DiffCatcher adds recursive discovery, code element extraction, security pattern detection, SARIF output for CI/CD, parallel processing, and cross-repo security aggregation. See full comparison below.

🚀 Installation

From Source

git clone https://github.com/Teycir/DiffCatcher.git
cd DiffCatcher
cargo build --release
./target/release/diffcatcher --help

Requirements

Rust 1.70+
Git 2.0+

⚡ Quick Start

# Scan all repos in a directory (fetch-only, no modifications)
diffcatcher ~/projects

# Pull updates and generate security report
diffcatcher ~/projects --pull -o ./report

# Diff two branches in a single repo (PR review mode)
diffcatcher ./my-repo --diff main..feature/auth -o ./pr-report

# Generate SARIF output for GitHub Code Scanning
diffcatcher ~/projects --summary-format sarif,json -o ./report

# Dry run to see what would be scanned
diffcatcher ~/projects --dry-run

# Fast scan with 8 parallel workers
diffcatcher ~/projects -j 8 --quiet

📖 Usage

Basic Scanning

# Scan with default settings (fetch-only)
diffcatcher <ROOT_DIR>

# Custom output directory
diffcatcher ~/projects -o ./my-report

# Include nested repos and follow symlinks
diffcatcher ~/projects --nested --follow-symlinks

# Skip hidden directories
diffcatcher ~/projects --skip-hidden

Pull Modes

# Fetch only (default - no working tree changes)
diffcatcher ~/projects

# Actually pull changes
diffcatcher ~/projects --pull

# Force pull with stash/pop for dirty repos
diffcatcher ~/projects --pull --force-pull

# Use rebase strategy
diffcatcher ~/projects --pull --pull-strategy rebase

# Skip fetch/pull entirely (historical diffs only)
diffcatcher ~/projects --no-pull

Extraction Options

# Skip element extraction (raw diffs only)
diffcatcher ~/projects --no-summary-extraction

# Extract elements but skip code snippets
diffcatcher ~/projects --no-snippets

# Adjust snippet context and limits
diffcatcher ~/projects --snippet-context 10 --max-snippet-lines 300

# Limit elements per diff
diffcatcher ~/projects --max-elements 1000

Security Tagging

# Skip security tagging
diffcatcher ~/projects --no-security-tags

# Include test files in security analysis
diffcatcher ~/projects --include-test-security

# Use custom security patterns
diffcatcher ~/projects --security-tags-file ./custom-patterns.json

Configuration File

DiffCatcher can auto-load project-local configuration from:

<ROOT_DIR>/.diffcatcher.toml (default)
a custom file via --config <FILE>
disabled with --no-config

Example:

output = "reports-local"
no_pull = true
history_depth = 2
summary_formats = ["json", "txt"]
no_security_tags = false

[plugins]
security_pattern_files = ["plugins/security-extra.json"]
extractor_files = ["plugins/extractors.json"]

CLI flags still override config values when explicitly set.

Plugin System

DiffCatcher supports two plugin types:

Security pattern plugins via --security-plugin-file <FILE> (repeatable)
Extractor plugins via --extractor-plugin-file <FILE> (repeatable)

Security plugin format matches --security-tags-file JSON (version, mode, tags).

Extractor plugin format:

{
  "version": 1,
  "extractors": [
    {
      "name": "policy-rule",
      "kind": "Config",
      "regex": "^policy\\s+([A-Za-z_][A-Za-z0-9_]*)"
    }
  ]
}

Branch-Diff Mode (PR Review)

# Diff two branches in a single repo
diffcatcher ./my-repo --diff main..feature/auth

# Diff specific commits
diffcatcher ./my-repo --diff abc123..def456

# Diff with SARIF output for CI integration
diffcatcher ./my-repo --diff origin/main..HEAD --summary-format sarif -o ./pr-report

The --diff BASE..HEAD flag skips repository discovery and fetch/pull — it directly diffs two refs (branches, tags, or commit SHAs) and runs the full extraction + security tagging pipeline on the result.

SARIF Output

# Generate SARIF alongside other formats
diffcatcher ~/projects --summary-format sarif,json,md

# SARIF-only for CI/CD upload
diffcatcher ~/projects --summary-format sarif -o ./report

When sarif is included in --summary-format, a results.sarif file is written to the report root. This file follows the SARIF 2.1.0 standard and integrates with GitHub Code Scanning, VS Code SARIF Viewer, Azure DevOps, and other SARIF-compatible tools.

Advanced Features

# Incremental mode (skip unchanged repos)
diffcatcher ~/projects --incremental -o ./report

# Filter by branch pattern
diffcatcher ~/projects --branch-filter "main"

# Adjust history depth
diffcatcher ~/projects --history-depth 5

# JSON output for CI/CD
diffcatcher ~/projects --quiet --json > result.json

# Verbose output with discovered paths
diffcatcher ~/projects --verbose

📁 Report Structure

<report_dir>/
├── summary.json                    # Global summary
├── summary.md                      # Markdown summary
├── results.sarif                   # SARIF 2.1.0 output (when --summary-format sarif)
├── security_overview.json          # Cross-repo security aggregation
├── security_overview.md
├── <repo-name>/
│   ├── status.json                 # Repo state
│   ├── pull_log.txt
│   └── diffs/
│       ├── diff_N_vs_N-1.patch     # Raw unified diff
│       ├── changes_N_vs_N-1.txt    # File manifest
│       ├── summary_N_vs_N-1.json   # Element extraction
│       ├── summary_N_vs_N-1.md
│       └── snippets/
│           ├── 001_validate_token_ADDED.rs
│           ├── 002_check_permissions_BEFORE.rs
│           ├── 002_check_permissions_AFTER.rs
│           └── 002_check_permissions.diff
└── ...

⚙️ Configuration

CLI Flags

Flag	Default	Description
`-o, --output`	`./reports/<timestamp>`	Report output directory
`-j, --parallel`	`4`	Concurrent repo processing
`-t, --timeout`	`120`	Git operation timeout (seconds)
`-d, --history-depth`	`2`	Historical commits to diff
`--snippet-context`	`5`	Context lines around changes
`--max-snippet-lines`	`200`	Max lines per snippet
`--max-elements`	`500`	Max elements per diff
`--diff`	—	Diff two refs in a single repo (`BASE..HEAD`)
`--summary-format`	`json,md`	Output formats: `json`, `md`, `txt`, `sarif`

See diffcatcher --help for all options.

Custom Security Patterns

Create a JSON file with custom patterns:

{
  "version": 1,
  "mode": "extend",
  "tags": [
    {
      "tag": "pii-handling",
      "description": "PII data processing",
      "severity": "High",
      "patterns": ["ssn", "social_security", "passport"]
    }
  ]
}

Use with --security-tags-file ./patterns.json

🏗️ Architecture

src/
├── cli.rs              # Argument parsing
├── scanner.rs          # Repository discovery
├── git/                # Git operations
│   ├── commands.rs     # Git wrappers
│   ├── state.rs        # State capture
│   ├── diff.rs         # Diff generation
│   └── file_retrieval.rs
├── extraction/         # Element extraction
│   ├── parser.rs       # Unified diff parser
│   ├── elements.rs     # Element detection
│   ├── snippets.rs     # Code snippet extraction
│   ├── boundary.rs     # Bracket/indentation tracking
│   └── languages/      # Language-specific patterns
├── security/           # Security tagging
│   ├── tagger.rs       # Pattern matching
│   ├── patterns.rs     # Built-in patterns
│   └── overview.rs     # Cross-repo aggregation
└── report/             # Report generation
    ├── writer.rs       # Directory structure
    ├── json.rs         # JSON serialization
    ├── sarif.rs        # SARIF 2.1.0 output
    ├── markdown.rs     # Markdown formatting
    └── snippet_writer.rs

Bash Comparison

A simple bash one-liner can list diffs:

ls | while read line; do git -C "$line" diff HEAD~1 HEAD || true; done

This works for quick checks, but DiffCatcher adds significant capabilities:

Capability	Bash One-Liner	DiffCatcher
Recursive discovery	Top-level items only	Nested repos, symlinks, filters
State tracking	None	Commit hashes, dirty detection, pull logs
Code understanding	Raw diff only	Extracts functions/structs/classes across 10+ languages
Code snippets	None	Full before/after with context windows
Security analysis	None	18 built-in patterns (auth, crypto, secrets, SQLi, XSS)
Output formats	Terminal only	JSON, Markdown, SARIF (GitHub Code Scanning)
Cross-repo view	Per-repo only	Aggregated security report across all repos
Performance	Sequential	Parallel workers, LRU caching, incremental mode
CI/CD integration	None	SARIF upload to GitHub/Azure DevOps
Error handling	`
Path handling	Fails on spaces	Handles all path names correctly
Historical context	Fixed `HEAD~1`	Configurable depth, state tracking

The bash one-liner is ~100 bytes. DiffCatcher is a security-focused audit tool with full code element extraction.

🧪 Testing

# Run all tests
cargo test

# Run specific test suite
cargo test security_tagger

# Run with output
cargo test -- --nocapture

Test coverage includes:

Unit tests for extraction, security tagging, boundary detection
Integration tests for state capture, diff generation, reports
Golden-file tests for extraction accuracy
Edge case tests (detached HEAD, bare repos, single-commit)

Performance Benchmarks

# Compile benchmark binaries
cargo bench --no-run

# Run benchmark harness
cargo bench --bench core_bench

Benchmark source lives in benches/core_bench.rs and tracks parser/extraction throughput.

CI/CD

GitHub Actions workflows are included:

.github/workflows/ci.yml: format check, clippy, tests, bench build
.github/workflows/release.yml: tag-based release packaging and GitHub release publishing

📚 Documentation

Project Documentation

Plan.md - Full specification (v1.2)
Roadmap.md - Implementation roadmap and progress
Security patterns reference (see src/security/patterns.rs)

Code Documentation

All modules include comprehensive inline documentation. Key modules:

src/extraction/parser.rs - Unified diff parser with hunk extraction
src/extraction/elements.rs - Language-aware code element detection
src/extraction/snippets.rs - Full code snippet extraction with boundary detection
src/security/tagger.rs - Security pattern matching engine
src/git/commands.rs - Git operation wrappers

Generate full API docs:

cargo doc --open

🏷️ Tags

#rust #git #security #code-review #diff-analysis #static-analysis #devops #cli-tool #audit #vulnerability-detection #code-quality #snippet-extraction #parallel-processing #security-scanning

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure cargo test passes
Submit a pull request

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github/workflows		.github/workflows
assets		assets
benches		benches
presentation		presentation
src		src
tests		tests
.gitignore		.gitignore
Cargo.toml		Cargo.toml
LICENSE		LICENSE
Plan.md		Plan.md
README.md		README.md
Roadmap.md		Roadmap.md
publiceth.svg		publiceth.svg

Folders and files

Latest commit

History

Repository files navigation

Support Development

🎯 Key Features

📋 Table of Contents

🚀 Installation

From Source

Requirements

⚡ Quick Start

📖 Usage

Basic Scanning

Pull Modes

Extraction Options

Security Tagging

Configuration File

Plugin System

Branch-Diff Mode (PR Review)

SARIF Output

Advanced Features

📁 Report Structure

⚙️ Configuration

CLI Flags

Custom Security Patterns

🏗️ Architecture

Bash Comparison

🧪 Testing

Performance Benchmarks

CI/CD

📚 Documentation

Project Documentation

Code Documentation

🏷️ Tags

🤝 Contributing

📄 License

📧 Contact

🔗 Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages