Output Formats

symtrace offers two primary output modes: interactive ANSI terminal output (default) and machine-readable JSON (--json).

Terminal Output (Default)

When run in an interactive terminal, output is rendered with ANSI color styling and routed automatically to your shell pager ($PAGER or $GIT_PAGER, defaulting to less -RFX).

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

Summary
  Files: 1 | Moves: 1 | Renames: 1 | Inserts: 1 | Deletes: 1 | Modifications: 1

Commit Classification
  Class: refactor | Confidence: 85%

Performance
  Files processed   : 1
  Nodes compared    : 312
  Parse time        : 2.14 ms
  Diff time         : 0.38 ms
  Total time        : 12.05 ms

Color Control Modes

The --color <auto|always|never> flag or [output] color config setting controls ANSI color rendering:

auto (default): Enables ANSI colors if stdout is connected to a TTY and the NO_COLOR environment variable is unset.
always: Forces ANSI color formatting even when output is piped or redirected.
never: Disables ANSI colors completely.

Machine-Readable JSON Output (`--json`)

Passing --json emits structured JSON ideal for CI/CD gates, automated code review tools, or metrics collection:

{
  "repository": "/path/to/repo",
  "commit_a": "HEAD~1",
  "commit_b": "HEAD",
  "files": [
    {
      "file_path": "src/handler.rs",
      "old_path": "src/handler.rs",
      "new_path": "src/handler.rs",
      "operations": [
        {
          "type": "MODIFY",
          "entity_type": "function_item",
          "name": "parse_body",
          "old_location": "L10",
          "new_location": "L10",
          "details": "function_item 'parse_body' modified",
          "similarity": {
            "structure_similarity": 0.84,
            "token_similarity": 0.61,
            "node_count_delta": 3,
            "cyclomatic_delta": 1,
            "control_flow_changed": true,
            "similarity_percent": 75.2,
            "change_intensity": "medium"
          }
        }
      ],
      "refactor_patterns": [
        {
          "pattern_type": "rename",
          "description": "'process' renamed to 'execute'",
          "confidence": 1.0
        }
      ]
    }
  ],
  "summary": {
    "total_files": 1,
    "moves": 1,
    "renames": 1,
    "inserts": 1,
    "deletes": 1,
    "modifications": 1
  },
  "cross_file_tracking": [],
  "commit_classification": {
    "classification": "refactor",
    "confidence": 0.85
  },
  "performance": {
    "total_files_processed": 1,
    "total_nodes_compared": 312,
    "parse_time_ms": 2.14,
    "diff_time_ms": 0.38,
    "total_time_ms": 12.05,
    "incremental_files_reused": 0
  }
}

Key JSON Fields

old_path / new_path: Retains original and renamed file paths across Git file rename events.
operations[].type: INSERT, DELETE, MODIFY, MOVE, or RENAME.
operations[].similarity: Contains numerical similarity_percent (0–100%) and categorical change_intensity (low, medium, high).
commit_classification: Auto-detected commit type (feature, bugfix, refactor, cleanup, formatting_only, etc.) with decimal confidence.
performance: Execution metrics including parse time, diff time, total time, and incremental cache hits.

Output Formats

Terminal Output (Default)

Color Control Modes

Machine-Readable JSON Output (--json)

Key JSON Fields

Machine-Readable JSON Output (`--json`)