Introduction
symtrace is a semantic diff tool for Git, written in Rust. Instead of comparing lines of text like git diff, it reads the actual code structure and tells you what changed — which functions were moved, renamed, modified, added, or removed.
Why not just use git diff?
Section titled “Why not just use git diff?”git diff works at the text level. It’s fast, but it doesn’t understand code:
- Reformatting code looks like a huge diff, even though nothing actually changed.
- Moving a function shows up as a delete + insert, not a move.
- Renaming a variable looks the same as rewriting a function.
- Comment edits are mixed in with real logic changes.
What symtrace does instead
Section titled “What symtrace does instead”symtrace parses your code into a syntax tree, then compares the trees between two commits. The result is a list of clear, meaningful operations:
| Operation | What it means |
|---|---|
| MOVE | Code was relocated but not changed |
| RENAME | A name changed, but the structure is the same |
| MODIFY | The body of something was changed |
| INSERT | New code was added |
| DELETE | Code was removed |
Each operation includes a similarity score (how much changed) and an intensity level (low, medium, high) so you can quickly gauge the scope of a change.
Key properties
Section titled “Key properties”- Deterministic — same input always gives the same output.
- Offline — no network calls, no telemetry, no data collection.
- Fast — files are processed in parallel with caching and incremental parsing.
When to use it
Section titled “When to use it”- Code review — quickly understand the intent of a changeset.
- CI/CD — use JSON output (
--json) to classify and gate commits automatically. - Refactor checks — verify that a refactor didn’t change behavior (look for 100% similarity, low intensity).
- Auditing — track when public APIs change across files.