history
Trace every historical version of a code symbol to inspect signature or body changes over time, find when a bug was introduced, or recover a deleted symbol.
Instructions
Every historical version of a symbol reachable from a chosen tip. With vex index --history previously run, queries hit a persistent FST sidecar (~ms); without it, shells out to git log (~seconds). Indexed mode also finds symbols whose name has been DELETED from HEAD — the walker can't. Use this to inspect how a function's body / signature changed over time, find when a bug was introduced, or recover a deleted symbol's last definition. NOTE: omitting limit returns the full history (walker mode is unbounded by default — set limit to cap latency on long-lived repos). exact_presence: true adds seconds-scale latency per file — only pass when you specifically need the exact commit set, not the convex-hull span. v1.20.0 (D5) surface — the CLI subcommand has existed since v1.15.0 but was MCP-invisible.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| diff | No | Render unified diffs between consecutive historical versions of the same `(symbol, kind)` pair instead of repeating the full body for each entry. Cuts output noise on deep histories. Mutually exclusive with `exact_presence`. | |
| kind | No | Keep only entries whose symbol kind matches exactly (lowercase: `function` / `struct` / `impl` / …). | |
| name | No | DEPRECATED alias for `symbol`; still accepted, emits a deprecated_args notice in _meta. | |
| depth | No | Max commits to walk per file (walker mode). Unbounded by default; bump down on long-lived repos to keep latency in check. | |
| limit | No | Cap the total result set. Omit for unbounded (walker mode) — set explicitly on long-lived repos to keep latency in check. The walker stops as soon as the limit is reached. | |
| since | No | Keep only entries whose commit date is `>= YYYY-MM-DD` (inclusive). | |
| until | No | Keep only entries whose commit date is `<= YYYY-MM-DD` (inclusive). | |
| author | No | Keep only entries whose commit author contains this substring (case-insensitive). Walker-only — the indexed path rejects this with an error pointing at `no_index: true`. | |
| branch | No | Restrict the walk to this revision (`refs/heads/foo`, `origin/main`, a SHA). Defaults to `HEAD`. | |
| symbol | Yes | Symbol name to walk through history. Matched whole-word via `git grep --word-regexp`, then filtered post-parse to exact `name == query`. | |
| no_index | No | Force the v1.16 query-time walker even when a `git_history` section is present. Default (`HistoryMode::Auto`) picks the indexed path when available and falls back to the walker otherwise. Use for regression-checking the walker against the indexed path. | |
| project_root | No | Absolute path to the project root (defaults to the MCP working directory) | |
| exact_presence | No | For each entry, list the exact set of commits where its blob lived in the file. Defeats the convex-hull span representation (LIMITATIONS §4c #4). Adds latency. |