Docs

Snapshots

A snapshot is a local save of your working tree that is not a commit. It never enters your history, never reaches a remote, and exists so that the next risky operation is reversible.

Taking and restoring one

torii snapshot create -n "before-refactor"
torii snapshot list
torii snapshot restore <id>
torii snapshot delete <id>

Snapshots live in <gitdir>/torii/snapshots, inside .git. That location is deliberate: they used to sit next to the working tree, where add_all swept them into a commit — one repository ended up with a 681 MB commit and a push that would not complete. Inside .git, staging cannot reach them.

Stash, but reversible

torii snapshot stash          # set the working tree aside
torii snapshot stash -u       # include untracked files
torii snapshot unstash
torii snapshot unstash <id> --keep    # apply it and keep the snapshot

Known bug: snapshot stash occasionally reports success without saving. Until it is fixed, snapshot create -n "wip" is the reliable path.

Undo

torii snapshot undo

Reverses the last torii operation that took a snapshot. That is most of the destructive surface: hard resets, rebases, every torii history rewrite, and removing a worktree.

Automatic snapshots

torii config set snapshot.auto_enabled true
torii config set snapshot.auto_interval_minutes 30

The interval can also be set per repository in .torii/auto-interval, which travels with the project rather than with your machine.

When the reflog is not enough

A snapshot covers the working tree. For objects that were committed and then orphaned — a branch deleted, a rebase abandoned, a reflog entry expired — the object database still holds them until it is packed:

torii history orphans      # walk unreachable objects
torii history compact      # pack and expire; run this only when you are sure

Run orphans before compact, not after.