Snapshots, and where they live

A snapshot is a copy of your working tree, taken locally, that is not a commit. It has no parent, no message worth writing, no place in your history and no way to reach a remote. It exists so the next destructive thing you do is reversible.

Why not a commit

Git already has three answers to "let me save this for a second": a WIP commit, a stash, and the reflog. Each has a tax. A WIP commit pollutes the history you will later have to clean. A stash is a single stack with no names, and applying the wrong entry is a coin flip. The reflog is not a save at all — it records where refs pointed, so it recovers a branch, not the uncommitted file you just overwrote.

A snapshot is the missing one: named, listed, restorable by id, and invisible to everyone else.

Where they live, and the bug that decided it

Snapshots are written to <gitdir>/torii/snapshots — inside .git, not beside it.

They did not start there. They started in a directory next to the working tree, which is fine right up until someone runs torii save -a. add_all walks the working tree, finds the snapshot directory, and stages it. One repository produced a 681 MB commit that way and a push that would not finish.

Inside .git the problem cannot recur, because staging never walks in there. It is worth stating plainly rather than quietly fixing: the safety mechanism was, for a while, the thing that broke the repository.

What takes one automatically

Every torii history rewrite. save --reset --reset-mode hard. worktree remove. reauthor and mailmap apply. In each case the snapshot is taken before the first object is touched, so torii snapshot restore <id> puts the tree back exactly as it was.

You can also have them on a timer:

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

The interval can live in .torii/auto-interval instead, which travels with the project rather than with your machine — useful when the project is the kind where thirty minutes of lost work matters.

The one that is still broken

torii snapshot stash sometimes reports success without saving anything. It is known, it is not fixed at 0.13.0, and until it is, torii snapshot create -n "wip" is the path that always works. A safety net with an intermittent hole in it is worth documenting louder than a feature.