CLI Reference

Usage

symtrace [REPO_PATH] [COMMIT_A] [COMMIT_B] [OPTIONS]
symtrace git-diff-driver <PATH> <OLD_FILE> <OLD_HEX> <OLD_MODE> <NEW_FILE> <NEW_HEX> <NEW_MODE>

Positional Arguments

All positional arguments are optional and feature intelligent default resolution:

Argument	Default	Description
`REPO_PATH`	`.`	Path to local Git repository (defaults to current working directory)
`COMMIT_A`	`HEAD~1`	Older commit ref, tag, branch, or commit hash
`COMMIT_B`	Working Tree	Newer commit ref, tag, branch, or commit hash. Defaults to uncommitted working tree (or `HEAD` if `--staged` is used)

Options & Flags

Flag	Short	Default	Description
`--staged` / `--cached`		off	Compare staged index changes against `COMMIT_A`
`--path <GLOB>`	`-p`		Restrict diff analysis to file paths matching glob pattern (e.g. `"src/*/.rs"`)
`--color <WHEN>`		`auto`	Terminal ANSI color output mode (`auto`, `always`, `never`). Respects `NO_COLOR`
`--no-pager`		off	Disable piping terminal output to `$PAGER`
`--logic-only`		off	Filter out comments and formatting/whitespace AST nodes
`--json`		off	Emit machine-readable JSON report instead of colored text
`--no-incremental`		off	Disable incremental AST parsing and cache reuse
`--max-file-size <BYTES>`		`5242880` (5 MiB)	Skip files larger than specified byte size
`--max-ast-nodes <N>`		`200000`	Skip files exceeding specified AST node count
`--max-recursion-depth <N>`		`2048`	Maximum AST parsing recursion depth
`--parse-timeout-ms <MS>`		`2000` (2s)	Per-file Tree-sitter parse timeout in milliseconds (0 = disabled)
`--help`	`-h`		Print command help
`--version`	`-V`		Print version number

Subcommands

`git-diff-driver`

Native integration subcommand used when symtrace is configured as a git diff driver in .gitconfig and .gitattributes.

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

See Native Git Diff Driver Guide → for configuration instructions.

Configuration File Overrides

symtrace automatically reads configuration options from repository .symtracerc or symtrace.toml files, as well as ~/.config/symtrace/symtrace.toml.

CLI flags passed on the command line override configuration file values.

See Configuration File Guide → for full TOML schema details.

Examples

Zero-Argument Run (Working Tree vs HEAD)

symtrace

Staged Index Comparison

symtrace . HEAD --staged

Path Glob Filtering

# Filter for Rust files in src directory
symtrace . HEAD~1 HEAD -p "src/**/*.rs"

# Filter for C/C++ header files
symtrace . HEAD~1 HEAD -p "**/*.h"

Compare Specific Commits or Branches

symtrace /path/to/repo main feature/login-page

Machine-Readable JSON for CI Pipelines

symtrace . HEAD~1 HEAD --logic-only --json

Custom Resource Limits for Heavy Repositories

symtrace . HEAD~1 HEAD --max-file-size 10485760 --max-ast-nodes 500000 --parse-timeout-ms 5000