Configuration File

symtrace automatically loads configuration options from TOML files, enabling team-wide standards for diffing rules, parse limits, and output settings without requiring explicit CLI flags on every run.

File Locations & Precedence

symtrace searches for configuration files in the following order:

1. CLI Flags (highest precedence — overrides all configuration file settings)
2. Repository Local Config: .symtracerc or symtrace.toml in the repository root directory
3. User Global Config: ~/.config/symtrace/symtrace.toml (Unix) or %USERPROFILE%\.config\symtrace\symtrace.toml (Windows)
4. Built-in Defaults (lowest precedence)

If both .symtracerc and symtrace.toml exist in the repository root, .symtracerc takes precedence.

Sample Configuration File

Create a file named .symtracerc or symtrace.toml in your repository root:

[default]
logic_only = false          # Skip comments and whitespace-only nodes
json = false                # Emit JSON output by default
no_incremental = false      # Force full AST re-parse (disable cache reuse)
no_pager = false            # Disable piping output to $PAGER

[limits]
max_file_size = 10485760    # Skip files larger than 10 MiB (default: 5 MiB = 5242880)
max_ast_nodes = 500000      # Skip files with more AST nodes than specified (default: 200000)
max_recursion_depth = 2048  # Maximum AST parsing recursion depth (default: 2048)
parse_timeout_ms = 3000     # Per-file tree-sitter parse timeout in ms (default: 2000)

[output]
color = "auto"              # Terminal color controls: "auto", "always", or "never"

Section Reference

[default] Section

Controls standard execution behavior:

Option	Type	Default	CLI Equivalent	Description
logic_only	boolean	false	--logic-only	Filters out comments and formatting/whitespace nodes
json	boolean	false	--json	Emits structured JSON output instead of ANSI text
no_incremental	boolean	false	--no-incremental	Disables incremental AST parsing and cache reuse
no_pager	boolean	false	--no-pager	Prevents piping terminal output into $PAGER

[limits] Section

Guards against excessive memory usage or parse hangs on large or adversarial files:

Option	Type	Default	CLI Equivalent	Description
max_file_size	integer	5242880 (5 MiB)	--max-file-size <BYTES>	Maximum file size in bytes; larger files are skipped
max_ast_nodes	integer	200000	--max-ast-nodes <N>	Maximum allowed AST nodes per file
max_recursion_depth	integer	2048	--max-recursion-depth <N>	Maximum recursion depth allowed during AST traversal
parse_timeout_ms	integer	2000 (2s)	--parse-timeout-ms <MS>	Timeout in milliseconds per file parse (0 = disabled)

[output] Section

Controls formatting and terminal rendering:

Option	Type	Default	CLI Equivalent	Description
color	string	"auto"	--color <auto|always|never>	ANSI color mode. "auto" respects TTY state and NO_COLOR env var

Overriding Configuration via CLI

Any setting configured in .symtracerc or symtrace.toml can be overridden directly on the command line:

# Enable logic-only and JSON output regardless of .symtracerc defaults
symtrace . HEAD~1 HEAD --logic-only --json

# Override parse timeout for large refactor reviews
symtrace . HEAD~1 HEAD --parse-timeout-ms 10000 --max-file-size 20971520