What is a stash?

Uncommitted work put aside as a commit of its own, so the working copy is clean until you take it back.

A stash is uncommitted work, saved and set aside. You use one when the working copy has changes you are not ready to commit and you need it clean anyway: to switch branches, to pull, to try something else for ten minutes. Stashing records the changes, staged and unstaged alike, and puts the files back the way the last commit left them. Restoring puts the changes back.

Under the surface a stash is a commit, one that no branch points at, kept on a list of its own, so it never appears in the history and is never pushed. That is why the diagram can draw it as one: a commit off to the side, with the commit you were on as its parent.

  1. Work in progress on main, not ready to commit, and something else needs doing first.

  2. Stash. The changes are saved as S, a commit off to the side with C as its parent, and the working copy is back to C: clean.

  3. With the working copy clean you can pull, switch, or do the other thing. Here main gains a commit, D.

  4. Restore the stash. The saved changes are applied on top of D and the entry is dropped from the list, so nothing reaches S any more.

Stash or branch?

A stash is for the next hour; a branch is for anything longer. A stash has no name of its own beyond its place in the list, it is not pushed, and it does not travel with a clone. Work that will take days, or that anyone else needs to see, wants a branch and a commit, however rough. Restoring a stash onto a commit other than the one it was taken from is a small merge, and can conflict the way a merge does.

On the command line

git stash             # save the changes and clean the working copy
git stash list        # stash@{0} is the newest
git stash pop         # put the newest back and drop it from the list
git stash apply       # put it back and keep it on the list

Git’s own reference: git-stash.

In Innesta

Saving a stash is the three scopes Innesta offers, and reading a stash first is how to see what one holds before restoring it. The stash Innesta makes on its own when a switch would lose your changes is on switching with uncommitted work.

The Playground is a repository made for trying this on.