Quick Start

Your First Run

Run symtrace inside any Git repository with no arguments to compare your current working tree against HEAD:

symtrace

That’s it! symtrace automatically resolves positional defaults (REPO_PATH defaults to ., COMMIT_A to HEAD~1, COMMIT_B to working tree) and pipes ANSI color output directly to your terminal pager ($PAGER).

---

Common Use Cases

Compare Staged Index Against HEAD

Compare staged changes ready to be committed:

symtrace . HEAD --staged

Compare Specific Commits or Branches

# Compare commit HEAD~1 against HEAD in current directory
symtrace . HEAD~1 HEAD

# Compare feature branch against main in another repo
symtrace /path/to/repo main feature/my-feature

# Compare two commit SHA hashes
symtrace . a1b2c3d 9f8e7d6

Path Glob Filtering (--path / -p)

Restrict diff analysis to specific files or directories:

# Only analyze Rust files in src/
symtrace . HEAD~1 HEAD -p "src/**/*.rs"

# Only analyze C/C++ files
symtrace . HEAD~1 HEAD -p "**/*.{c,cpp,h,hpp}"

# Only analyze JSON config files
symtrace . HEAD~1 HEAD -p "**/*.json"

---

Common Flags & Formatting Options

Filter Out Comments & Formatting (--logic-only)

Ignore non-functional changes such as comment edits, docstrings, and whitespace formatting:

symtrace . HEAD~1 HEAD --logic-only

Output Machine-Readable JSON (--json)

Pipe structured JSON into jq or CI/CD pipelines:

# Output JSON report
symtrace . HEAD~1 HEAD --json

# Extract commit classification via jq
symtrace . HEAD~1 HEAD --json | jq '.commit_classification'

Force Color Output or Disable Pager

# Force ANSI colors even when redirecting to a file or script
symtrace . HEAD~1 HEAD --color always > diff.txt

# Disable interactive $PAGER piping
symtrace . HEAD~1 HEAD --no-pager

---

Setup Native Git Diff Driver

To run symtrace automatically whenever you type git diff:

# 1. Register symtrace diff driver in Git config
git config --global diff.symtrace.command "symtrace git-diff-driver"

# 2. Map files in your project's .gitattributes
echo "*.rs diff=symtrace" >> .gitattributes
echo "*.ts diff=symtrace" >> .gitattributes

Now running standard git diff outputs semantic AST diffs directly! See Native Git Diff Driver Guide →.

---

Output Sample Walkthrough

━━━ src/handler.rs
  + [INSERT] function_item 'handle_request' inserted (L42)
  ~ [MODIFY] function_item 'parse_body' modified (L10 → L10) [75% similarity, medium]
  ✎ [RENAME] function_item renamed from 'process' to 'execute' (L5 → L5) [98% similarity, low]
  - [DELETE] function_item 'deprecated_fn' deleted (L88)
  ↔ [MOVE]   function_item 'helper' moved (L20 → L35) [100% similarity, low]

  ── Refactor Patterns ──
    ▸ 'process' renamed to 'execute' (confidence: 100%)

Summary
  Files: 1 | Moves: 1 | Renames: 1 | Inserts: 1 | Deletes: 1 | Modifications: 1

Commit Classification
  Class: refactor | Confidence: 85%

Performance
  Files processed   : 1
  Nodes compared    : 312
  Parse time        : 2.14 ms
  Diff time         : 0.38 ms
  Total time        : 12.05 ms

See CLI Reference for full argument specifications.