# aura rewind *Surgically revert a single function to an earlier state without disturbing the rest of the file.* ## Synopsis ```bash aura rewind [--to ] [--file ] [--dry-run] [--interactive] ``` ## Description `aura rewind` is Aura's most-requested command after `save`. It reverts a single logic node — a function, method, class, or other AST-level unit — to an earlier recorded state, leaving every other node in the file untouched. Because the operation is AST-shaped, there are no text-level merge conflicts and no hand-editing of hunks. You name the function, you name the point in time, and Aura rewrites exactly that node. Every save and every snapshot records a content-addressed body for each node it touched. `aura rewind` walks backwards through those records, finds the most recent one that matches your target, and applies it. If the function was renamed between then and now, the rewind follows the rename; the rewound body is written under the function's current name so your callers still compile. The command is intentionally narrow. It does not rewind arguments of callers, it does not rewind tests that were updated to match the new behavior, and it does not revert the intent log. It just puts one function body back. This is exactly what you want at 2 a.m. when a deploy broke because one function regressed. ## How it differs from git checkout / git reset - **`git checkout -- `** reverts an entire file, clobbering every other change in that file. `aura rewind` is scoped to one function. - **`git reset --hard`** moves the branch and destroys work. `aura rewind` never moves the branch and never deletes commits. - **`git revert`** creates an inverse commit. `aura rewind` does neither a commit nor an inverse — it stages the restored body and leaves you to run `aura save` with an intent that explains *why* you rewound. - **File renames and function renames** are followed automatically; `git checkout` on a renamed file requires you to know the old path. - **No merge conflicts.** If the function has been edited locally since its last save, the local edits are snapshotted before the rewind so they are recoverable, then discarded from the working tree. ## Flags | Flag | Description | | --- | --- | | `` | The logic node to rewind. Usually a function name; disambiguate with `Type::method` or `module::function` if needed. | | `--to ` | Rewind to the body as of a specific save id, commit sha, or branch tip. | | `--to ` | Rewind to a specific snapshot id (see `aura snapshot list`). | | `--to ` | Rewind to the state at a given time, e.g. `--to 2026-04-20T14:00`. | | `--to previous` | Default. Rewind to the immediately previous recorded body. | | `--file ` | Disambiguate when the same function name exists in multiple files. | | `--dry-run` | Print the before/after bodies without modifying the working tree. | | `--interactive` | Show a picker of recent bodies for this function and let you choose. | | `--keep-local` | Stash current local edits to the node as a snapshot before overwriting. Default is on. | ## Examples ### 1. Undo the last change to one function ```bash aura rewind charge_card ``` Finds the function `charge_card` in the current branch, takes a snapshot of its current body, and replaces it with the previous saved body. The result is staged. Commit it with: ```bash aura save --intent "Rewind charge_card to pre-refactor behavior; the new impl regressed 3DS" ``` ### 2. Rewind to a specific commit ```bash aura rewind send_receipt --to 3d22f0e ``` Rewinds `send_receipt` to its body as of commit `3d22f0e`, even if the function has been renamed or moved since. Aura follows the identity, not the path. ### 3. Disambiguate when the name is duplicated ```bash aura rewind validate --file src/auth/token.rs ``` If multiple functions share the name `validate`, Aura would otherwise ask. `--file` narrows the search. ### 4. Interactive picker ```bash aura rewind parse_url --interactive ``` ```text History of fn parse_url (src/http/url.rs): 1. 2026-04-21 09:12 ashiq "Handle IPv6 zone identifiers" [current] 2. 2026-04-19 17:33 jamie "Strip default ports for canonicalization" 3. 2026-04-18 10:04 ashiq "Accept fragment-only URLs" 4. 2026-04-10 14:20 ashiq "Initial implementation" Select a version to restore [2-4]: ``` Choosing `3` rewinds `parse_url` to the 2026-04-18 body. Nothing else changes. ### 5. Preview without changing anything ```bash aura rewind calculate_tax --to previous --dry-run ``` ```text aura rewind (dry-run) fn calculate_tax (src/billing/tax.rs) current hash: c91a2 (save sv_019abc, 2026-04-21 11:40) target hash: a4017 (save sv_0198ff, 2026-04-20 18:02) --- current +++ target @@ - let rate = jurisdiction.rate_for(date); - let base = amount * rate; - base + surcharge(amount, jurisdiction) + let rate = jurisdiction.rate_for(date); + amount * rate No changes written. ``` ## When to use it - A recent change regressed behavior and you have a working older version. - You want to experiment with an older implementation without reverting the whole file. - A teammate's Mothership delta clobbered a function you were about to edit — rewind to your last snapshot, then reconcile. - A code-review comment asks *"why did we change this?"* — rewind to the version before the PR to compare. ## When not to use it - If you want to revert a whole feature, `git revert` a commit is clearer. - If you want to roll back a release, use `git reset` on a release branch or re-tag. - If the function's signature changed, rewinding the body will un-change the signature; callers may stop compiling. Review the diff. ## Exit Codes | Code | Meaning | | --- | --- | | `0` | Rewind succeeded. Changes are staged in the working tree. | | `1` | Generic failure. | | `2` | Function not found, or ambiguous and `--file` was not supplied. | | `3` | No earlier recorded body for this function. | | `4` | Target save/commit/timestamp predates the function's first record. | | `5` | Current working tree has uncommitted changes to the function and `--keep-local` is off. | ## How it works under the hood The semantic index stores, for every save and every snapshot, a content-addressed blob of each node's body. A node's history is therefore a sequence of hashes over time, and the bodies are recoverable as long as the blobs remain in the snapshot store (default retention: indefinite for committed saves, 30 days for ad-hoc snapshots). `aura rewind` resolves your target specifier (`previous`, a save id, a commit sha, a timestamp) to a specific blob hash, loads the blob, and splices it into the source file at the node's current location. The splice uses the AST positions, not line numbers, so it works even if the surrounding code has been reformatted or reorganized since. If the splice would produce a parse error (for example because surrounding types were renamed and the old body references the old names), the rewind aborts and reports the first offending identifier, leaving the working tree untouched. When following a rename, Aura maps the old name in the rewound body to the current name using the rename record. Rewriting identifiers inside a function body is not automatic beyond the function's own name; if the old body called `legacy_helper` and that helper was renamed to `helper`, you may need to update the call site. The dry-run output flags suspected cross-references for review. ## Rewinding across branches `aura rewind fn --to ` accepts a branch name as the target. Aura will find the most recent save on that branch that recorded this function and use that body. This is how you pick a function from a different line of development without merging the whole branch. The rewound body is attributed in the intent log as `from branch: ` so the trace stays honest. ## Rewinding multiple functions at once `aura rewind` accepts multiple function arguments and will rewind each independently to the specified target: ```bash aura rewind charge_card send_receipt calculate_tax --to v0.11.0 ``` All three are restored to their `v0.11.0` bodies, each tracked through its own rename history. This is occasionally useful when a feature touched several functions and you want to back out the whole feature selectively — although typically `git revert` of the feature's commit is a cleaner approach for that case. ## Rewind and the intent log Each rewind produces an implicit intent entry of the form `rewind() to ` so the trace tells the full story. You are still expected to write a descriptive intent on the `aura save` that commits the rewind; the implicit entry is there to make the mechanical operation auditable, not to replace your explanation. ## Safety Rewind never destroys data. Before overwriting, it takes a fresh snapshot of the current body. If the rewind was wrong, `aura rewind --to previous` a second time restores the state you had before the first rewind — snapshots are just more nodes in the trace. ## See Also - [aura trace](/aura-trace) — see the full history before picking a target - [aura snapshot](/aura-snapshot) — the underlying storage - [aura save](/aura-save) — used to commit the rewind - [aura diff](/aura-diff) — inspect the pending rewind