epoch_forge/docs/recovery.md

42 lines
1.8 KiB
Markdown

# Reversing changes
Epoch Forge keeps committed HEAD, a staging index, and an editable worktree.
Inspect each recovery operation before choosing the destructive one:
```bash
efo diff # worktree versus index
efo diff --staged # index versus HEAD
efo restore --worktree --all # discard only unstaged changes
efo restore --staged --all # unstage everything
```
## Recovery matrix
| Mutation | Built-in recovery | After `reset --hard` |
|---|---|---|
| Unstaged entity or metadata edit | `restore --worktree` | Restore the complete repository from Git/backup |
| Staged change | `restore --staged`, then optionally restore the worktree | Restore from Git/backup |
| Commit or `epoch next` | `revert`, or switch to an older epoch | Restore from Git/backup if its epoch was destroyed |
| `revert ID` | `restore --worktree --all` | Restore from Git/backup |
| `revert ID --commit` | Revert the inverse commit | Restore from Git/backup |
| `switch` | Switch back to the previous ID/tag | Not applicable |
| `prune-future --yes` | Use the printed `prune-future --restore … --yes` command; epochs, tags, and allocator are restored | Not applicable |
| `reset --hard ID --yes` | None | Restore the complete repository from Git/backup |
Before a hard reset, preserve the complete repository—not only the current
snapshot. Run the preview first:
```bash
efo reset --hard <target>
git add .epoch .efo/ epoch/
git commit -m "checkpoint before abandoning future epochs"
efo reset --hard <target> --yes
```
Never reconstruct UUIDs or tag maps manually when a known-good backup exists.
`efo epoch fsck` is read-only and can identify damage, but deliberately does not
guess repairs.
For a recoverable history rewrite, use `efo switch <target>` followed by
`efo prune-future --yes`; the latter prints the exact restoration command.