Introduction

symtrace is a deterministic, AST-based semantic diff engine for Git, written in Rust. Instead of comparing lines of text like standard git diff, it parses code structure with Tree-sitter and tells you what semantically changed — which functions were moved, renamed, modified, inserted, or deleted.

━━━ 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%)

Why not just use git diff?

git diff operates at the plain text line level. It’s fast, but structurally blind:

• Formatting & Whitespace Noises — Code reformatting or comment edits generate noisy line diffs, masking real changes.
• Relocated Functions — Moving a function to another position or file shows up as a complete deletion and insertion.
• Renames — Renaming a variable or method looks identical to rewriting the implementation.
• Refactor Blindness — Extracting a method or moving code across files cannot be verified automatically.

What symtrace does instead

symtrace parses source code into Concrete Syntax Trees (CST/AST), computes 4-hash BLAKE3 fingerprints for node identity, and executes a 5-phase matching algorithm to isolate structural operations:

Operation	Symbol	What it means
MOVE	↔ [MOVE]	Code block or entity was relocated without logical modification
RENAME	✎ [RENAME]	An entity name was changed while preserving structure
MODIFY	~ [MODIFY]	The body or structure of an entity was modified
INSERT	+ [INSERT]	A new syntactic entity was introduced
DELETE	- [DELETE]	An existing syntactic entity was removed

Each operation includes similarity metrics (structural and token similarity percentages) and change intensity levels (low, medium, high).

Key Capabilities in v0.3.0

• 9 First-Class Languages & Formats — Full AST parsing support for Rust, JavaScript, TypeScript, Python, Java, C, C++, Go, and JSON.
• Native Git Diff Driver — Direct integration into git config and .gitattributes via symtrace git-diff-driver.
• Path Glob Filtering — Filter comparisons to specific files using --path <GLOB> (-p).
• Interactive Shell Pager — Automatic paging via $GIT_PAGER / $PAGER (less -RFX) for TTY execution.
• Configuration File — Hierarchical .symtracerc / symtrace.toml loader for repo-wide settings and limits.
• Dual-Path Git Rename Tracking — Retains both old_path and new_path across Git file rename events.
• Refactor Pattern & Symbol Tracking — Automatic detection of cross-file moves, renames, and extract method patterns.
• Commit Classification — Automatic commit tagging (feature, bugfix, refactor, cleanup, formatting_only) with confidence scoring.

Guarantees & Security

• Deterministic — Identical code inputs always produce identical diff operations.
• Zero Unsafe Rust — Strictly enforced via #![deny(unsafe_code)].
• Fully Offline — Zero network calls, zero telemetry, zero analytics.
• Signed Release Attestations — Build artifacts are keylessly signed via Sigstore/Cosign OIDC with SPDX SBOMs and GitHub Artifact Attestations.