epoch_forge/docs/recovery.md

44 lines
1.7 KiB
Markdown

# Reversing changes
Epoch Forge edits the checked-out epoch immediately; there is no staging area
yet. The reliable workflow is therefore to create a checkpoint before a risky
session:
```bash
efo status
efo epoch next
# Make edits in the new epoch.
```
The former state remains in the prior epoch. Inspect it without destroying the
new work with `efo epoch switch <old-id-or-tag>`. Switch back if the changes are
good. To abandon them, remain on the older epoch, make an external backup, then
run `efo epoch reset`.
## Recovery matrix
| Mutation | Recovery before `epoch reset` | Recovery after destructive removal |
|---|---|---|
| Entity `add`, `edit`, `del` | Switch to the checkpoint epoch | Restore `.epoch` and `epoch/` from Git/backup |
| `epoch summary`, `epoch tag` | Switch to the checkpoint epoch | Restore from Git/backup |
| `epoch next` | Switch to the prior epoch; the new epoch remains available | Not applicable |
| `epoch switch` | Switch back to the previous ID/tag | Not applicable |
| `epoch reset` | No built-in undo | Restore deleted epoch directories and `.epoch` from Git/backup |
| `init` | Remove only the newly-created `.epoch` and `epoch/` after verifying their contents | Restore the containing directory from backup |
Before `epoch reset`, preserve the complete repository—not only the current
snapshot:
```bash
git add .epoch epoch/
git commit -m "checkpoint before abandoning future epochs"
efo epoch reset
```
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.
Native `restore`, `revert`, and pseudo-staging commands belong to the next
repository-format milestone and are specified in the roadmap.