Native Git Diff Driver

Starting in v0.3.0, symtrace includes a dedicated git-diff-driver subcommand that allows Git to automatically use symtrace’s AST-based semantic analysis whenever you run standard git diff commands.

git diff ──► .gitattributes filter ──► symtrace git-diff-driver ──► Semantic AST Diff

Setup Instructions

Setting up symtrace as your Git diff driver takes two quick steps.

Step 1: Configure Git Driver Command

Run the following git config command to register symtrace git-diff-driver as a diff driver named symtrace:

# Global configuration (applies to all your Git repositories)
git config --global diff.symtrace.command "symtrace git-diff-driver"

# OR local configuration (applies only to the current repository)
git config diff.symtrace.command "symtrace git-diff-driver"

Step 2: Assign Driver in .gitattributes

In your repository root, add or update your .gitattributes file to map specific file extensions to the symtrace diff driver:

# Map supported language files to symtrace semantic diff
*.rs diff=symtrace
*.js diff=symtrace
*.jsx diff=symtrace
*.ts diff=symtrace
*.tsx diff=symtrace
*.py diff=symtrace
*.java diff=symtrace
*.c diff=symtrace
*.h diff=symtrace
*.cpp diff=symtrace
*.hpp diff=symtrace
*.go diff=symtrace
*.json diff=symtrace

How It Works Under the Hood

When you execute standard Git commands like git diff, Git inspects .gitattributes. When a file matches a rule with diff=symtrace, Git executes the configured driver command with 7 positional arguments:

symtrace git-diff-driver <path> <old-file> <old-hex> <old-mode> <new-file> <new-hex> <new-mode>

The git-diff-driver subcommand:

1. Parses the temporary files and path metadata passed by Git.
2. Performs 5-phase tree-sitter AST parsing and BLAKE3 node matching.
3. Renders ANSI-formatted semantic operation badges (INSERT, DELETE, MODIFY, MOVE, RENAME).
4. Outputs directly back to Git’s standard pager pipeline.

Usage Examples

Once configured, standard Git workflows automatically use semantic diffing:

# Show semantic diff of modified files in working tree
git diff

# Show semantic diff of staged files
git diff --staged

# Show semantic diff between two commits or branches
git diff main feature-branch

# Show semantic diff for a specific file
git diff src/main.rs

Disabling or Bypassing Temporary

If you want to view traditional line-based git diff for a single invocation without changing your .gitattributes:

# Bypass git-diff-driver and force raw line diff
git diff --no-ext-diff

To remove the driver completely:

git config --global --unset diff.symtrace.command