# aura trace *Show the full history of a function across renames, moves, and refactors.* ## Synopsis ```bash aura trace [--file ] [--limit ] [--since ] [--format=text|json] [--show-bodies] ``` ## Description `aura trace` is the semantic counterpart to `git log --follow`. Given a function name, it prints every recorded change to that function — across saves, across branches, across renames, and even across moves between files. Because Aura tracks each logic node by a stable identity rather than by `file:line`, renaming `authenticateUser` to `logIn` does not break the trail; the history continues. Each entry in the trace represents one save that touched the function. The fields are: save id, commit sha, author and agent, timestamp, the `--intent` string that accompanied the save, the operation (created / modified / renamed / moved / deleted / restored), and a pointer to the stored body. With `--show-bodies` the full function body for each entry is printed inline, turning the trace into a readable archaeology report. The history is drawn from the logic graph, so a function that existed in a branch that was later merged is still traceable, and a function that existed on a rewound commit is still traceable. If you deleted a function last month and want to see the last known version, `aura trace ` finds it. ## Flags | Flag | Description | | --- | --- | | `` | Name of the logic node. Use `Type::method` to scope to a type, or the fully qualified path if the short name is ambiguous. | | `--file ` | Disambiguate when the same name exists in multiple files. | | `--limit ` | Show only the last `n` entries. | | `--since ` | Show entries newer than the given date (ISO 8601 or relative: `2w`, `24h`). | | `--format=text` | Default. Human-readable. | | `--format=json` | Machine-readable, one entry per line. | | `--show-bodies` | Include full function bodies. | | `--authors ` | Filter by comma-separated author emails or agent names. | | `--branches ` | Restrict to saves on the listed branches. | ## Output format The default text output is a vertical log: ```text fn PaymentGateway::charge (src/payments/gateway.rs) ● sv_019abc 3d22f0e 2026-04-21 11:40 ashiq@naridon.io (claude-opus-4.6) │ Modified. Intent: "Add retry_on_network_error and log_audit_trail" │ body: +14 lines, -2 lines │ ● sv_0198ff 9b7a221 2026-04-18 17:02 jamie@naridon.io (human) │ Renamed from `run_charge` -> `charge`. Intent: "Rename for consistency with capture/refund" │ body: unchanged │ ● sv_018c21 c4a19e0 2026-04-10 14:20 ashiq@naridon.io (human) │ Created. Intent: "Initial payments gateway — single-currency, no 3DS" │ body: 38 lines │ ● (previously) 1 entry on branch feat/legacy-gateway, last seen 2026-03-02 (run with --branches feat/legacy-gateway to expand) ``` The circle markers indicate operation kind: `●` modified, `◆` renamed, `▲` moved, `✕` deleted, `✦` restored. ## Comparison to git log --follow | | `git log --follow -- ` | `aura trace ` | | --- | --- | --- | | Tracking unit | File | Function | | Follows file renames? | Yes, heuristically | Yes, by identity | | Follows function renames? | No | Yes | | Follows function moves between files? | No | Yes | | Shows intent? | Commit message only | Dedicated intent field | | Sees deleted functions? | Only if you know the old path | Yes, from the semantic index | | Cross-branch? | Requires `--all` and still path-based | Yes, by default | | Output per entry | Commit metadata | Commit metadata + semantic op + body pointer | ## Examples ### 1. Basic trace ```bash aura trace charge ``` Shows every recorded modification to the function `charge`, newest first. ### 2. Bodies inline ```bash aura trace validate_email --show-bodies --limit 3 ``` Prints the three most recent versions of `validate_email` with their full source. Handy when you want to eyeball what changed without checking out old commits. ### 3. Scope to a type ```bash aura trace User::save ``` Matches only the `save` method on the `User` type. The free function `save` elsewhere is excluded. ### 4. JSON for tooling ```bash aura trace parse_url --format=json --since 30d ``` ```text {"save_id":"sv_019abc","commit":"3d22f0e","ts":"2026-04-21T09:12:00Z","author":"ashiq@naridon.io","agent":"claude-opus-4.6","op":"modify","intent":"Handle IPv6 zone identifiers","body_hash":"c91a2"} {"save_id":"sv_0198ff","commit":"9b7a221","ts":"2026-04-19T17:33:00Z","author":"jamie@naridon.io","agent":"human","op":"modify","intent":"Strip default ports for canonicalization","body_hash":"a4017"} ... ``` Pipe into `jq` or your preferred analysis tool. Each line is one save. ### 5. Find who last touched a function before a bug ```bash aura trace calculate_tax --since 2026-04-01 --authors jamie@naridon.io,ashiq@naridon.io ``` Filters to two authors' saves in April. Combined with `--show-bodies`, this is often enough to locate the regression without opening a single file. ## Exit Codes | Code | Meaning | | --- | --- | | `0` | Trace printed (may be empty if filters matched nothing). | | `1` | Generic failure. | | `2` | Function not found in the semantic index. | | `3` | Ambiguous name and `--file` was not supplied. | ## Cross-branch traces By default, `aura trace` walks every branch the node has ever appeared on. If a function was created on `feat/A`, merged into `main`, modified on `main`, and also modified independently on `feat/B`, the trace shows all three lineages interleaved by timestamp. The branch of each entry is annotated. To restrict, use `--branches main` to see only the main-line history, or `--branches feat/A,feat/B` to compare two feature branches side by side. A merged branch's entries are kept under the merge commit they landed through; after a merge, the entries flow naturally into the parent branch's lineage. This gives you a continuous story of the function without needing to know the branch graph. ## Answering common questions `aura trace` is the canonical answer to a handful of recurring questions. *"When did this function change last?"* — the first entry in `aura trace `. *"Who wrote this?"* — the final entry (the creation), or, for authorship of the current body, the most recent entry whose op is `modified` or `created`. *"What was this function before the refactor?"* — `aura trace --limit 2 --show-bodies` shows the current and previous bodies inline. *"Did this function ever exist in another form?"* — full trace, possibly with `--show-forks`, reveals alternate lineages. *"Why does this function exist at all?"* — the intent on the creation entry. ## Useful trace-based workflows **Bisecting a regression.** Trace the misbehaving function, read the intents in order, and identify the save whose intent most plausibly relates to the regression. This is usually faster than bisecting commits because intent descriptions are richer than commit messages. **Onboarding to unfamiliar code.** `aura trace --show-bodies` on a new codebase is a fast way to understand how the function got to its current shape, who has worked on it, and what the authors thought they were doing at each step. **Reviewing your own work.** Before opening a PR, `aura trace ` on each function you touched gives you a compact summary of your own changes across the branch, which is often clearer than reading `git log -p`. ## Performance `aura trace` reads only index metadata for its default output; bodies are fetched lazily when `--show-bodies` is set or when an entry is requested interactively. On a 10k-node repository with 10k saves, a full-history trace returns in well under a second. `--show-bodies` across the full history of a hot function takes a few seconds because blobs are read and formatted. ## Identity, not paths Aura assigns each logic node a stable identity on first observation. The identity is derived from the node's signature plus a structural fingerprint of its body, not from its name or file. Renames — whether of the function, of its enclosing type, or of the containing file — do not mint a new identity; they append rename records to the existing one. This is why `aura trace` can follow a function through a project-wide rename that would lose `git log --follow`. When two candidates could match (for example, when a file is copied and modified on one branch), Aura prefers the one whose body is more similar, and records the other as a fork in the history with the annotation `(forked from)`. Forks appear in the trace as a sidebar entry you can expand with `--show-forks`. ## Deleted nodes A deleted node is still in the trace. Its final entry carries op `deleted` and an intent; entries before the delete are preserved indefinitely. This is what makes `aura rewind` able to resurrect a function months after its removal: the identity and the bodies are still in the index. ```bash aura trace legacy_check ``` ```text fn legacy_check (src/legacy/cvv.rs) [DELETED] ✕ sv_019abc 2026-04-21 11:40 ashiq "Remove legacy CVV path; 3DS supersedes" ● sv_0195aa 2026-03-02 09:12 jamie "Final patch before deprecation" ● (history truncated; 14 earlier entries — run with --limit 20) ``` Running `aura rewind legacy_check --to sv_0195aa` would restore it. ## Integration with reviews `aura trace --since ` gives a reviewer the exact per-commit evolution of a function within a pull request, independent of which files it lived in. Reviewers often prefer this to reading the combined diff, because the story of the function is continuous. ## See Also - [aura rewind](/aura-rewind) — restore a specific version from the trace - [aura diff](/aura-diff) — compare two recorded bodies - [aura prove](/aura-prove) — verify that a goal is still implemented across the history - [aura save](/aura-save) — adds new entries to the trace