Quick Start

Your First Run

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

symtrace

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).

Micro-Compact Output (--compact)

For single-line edits, small configuration updates, or micro-commits, force the micro-compact renderer:

symtrace --compact

Outputs ultra-dense 1–3 line inline token changes without heavy headers:

~ src/server.rs:L42  [MODIFY] port: 8080 -> 3000 (95%)

Declarative AST Semantic Linter (symtrace lint)

Run domain-specific .scm rule validation on your source code with automated CI failure thresholds:

# Lint current repository against .symtrace/queries rules
symtrace lint .

# Enforce zero warnings in CI pipelines
symtrace lint . --max-warnings 0

# Output findings as SARIF for GitHub Code Scanning
symtrace lint . --format sarif

AI / LLM Context Prompt Exporter (--format prompt)

Export ultra-dense semantic diffs optimized for LLM coding assistants (Gemini, Claude, GPT), reducing prompt token consumption by ~80%:

symtrace . HEAD~1 HEAD --format prompt

Interactive TUI Inspector (symtrace tui)

Launch the keyboard-driven interactive workspace to explore structural code changes, refactors, and call graphs:

symtrace tui

Use j/k to navigate files, Tab to switch between the Refactor Tree and AST diff pane, / to search symbols, and q to exit. See Interactive TUI Inspector Guide →.

Common Use Cases

High-Level Summary Table (--stat / -s)

Get an instant executive summary table of AST changes across files:

symtrace . HEAD --stat

Pre-Commit Linting & CI Guard (--check)

Returns exit code 1 if structural logic changes are detected. Perfect for pre-commit hooks and CI pipelines:

symtrace . HEAD --check

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 TypeScript/TSX files
symtrace . HEAD~1 HEAD -p "**/*.{ts,tsx}"

Output Formats (--format / -f)

Output semantic diffs in various machine-readable and human-readable formats:

# Markdown format for PR reports
symtrace . HEAD~1 HEAD --format markdown

# SARIF format for static analysis tools & security scanners
symtrace . HEAD~1 HEAD --format sarif

# JSON / JSONL format for CI scripting
symtrace . HEAD~1 HEAD --format json

# Standalone White-Mode HTML printable report
symtrace . HEAD~1 HEAD --format html > symtrace_report.html

Setup 3-Way AST Merge Driver

Resolve rebases and merges with zero false-positive conflict markers:

# 1. Register symtrace 3-way merge driver in Git
git config --global merge.symtrace.name "symtrace 3-way AST semantic merge driver"
git config --global merge.symtrace.driver "symtrace merge-driver %O %A %B %P"

# 2. Add merge driver rule in your repo's .gitattributes
echo "*.rs merge=symtrace" >> .gitattributes

See 3-Way AST Merge Driver Guide →.

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

━━━ symtrace Semantic Diff ━━━
Repository: symtrace | Comparing: HEAD~1 → HEAD

━━━ 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 | Modifies: 1

━━━ Downstream Blast Radius ━━━
  Target: fn parse_body (src/handler.rs) | Total Callers Impacted: 3 [Severity: MEDIUM]
    ▸ Depth 1: fn execute_request (src/server.rs:L84)
    ▸ Depth 2: fn main_loop (src/main.rs:L12)

See CLI Reference for full argument specifications.