Snapshots: Your Git Safety Net

The most honest pattern in day-to-day version control is the "I will commit something half-baked just in case" commit. You are about to rebase a long-lived branch, or run a migration script against your working copy, or let an AI agent refactor six files at once. You know you should have a rollback point. So you type git commit -am "wip", and a minute later you are trying to hide it with git commit --amend or squash it in a rebase.

Snapshots are the missing primitive. They capture your working tree the way a commit would — but they live outside your branch history, they never get pushed, and restoring one is a single command.

The model

A snapshot is a named reference to a tree and index, stored in .git/torii/snapshots/. It does not touch HEAD, does not show up in git log, and does not appear in torii log either. It is invisible to everyone except you, on this machine, until you restore it.

Automatic snapshots

Explicit snapshots are great when you remember. The real win is when Gitorii remembers for you. Enable auto-snapshots and you get one every N minutes whenever your working tree changes:

Think of it as the Time Machine of your working directory. It costs nothing in disk (trees are content-addressed, snapshots share storage with commits), it is local, and it is always there.

When to reach for them

• Before interactive rebases on a long-lived branch. If you mess up the conflict resolution, restore.
• Before letting an agent loose. Multi-file refactors by LLMs should always be fronted by a snapshot.
• Before torii history remove-file and other destructive history rewrites.
• When pausing experiments. Snapshot your current attempt, start another from a clean tree, switch between them freely.

Stash vs. snapshot

• git stash removes your changes from the working tree. You get a clean checkout and your changes live on a stack.
• torii snapshot create copies your changes without touching the working tree. You keep working immediately.

Gitorii still has torii snapshot stash for the classic "save and clean" workflow. But the default — create — is non-destructive, which turns out to be what you actually want 90% of the time.

The undo command

Related: torii snapshot undo reverts the last Gitorii operation, using the auto-snapshot that was taken right before it. That is the command you want after a bad rebase, a bad merge, or a bad save --reset. You do not even need to have created a manual snapshot — auto-snapshots kick in around every state-changing operation.