git stash: put unfinished work aside

git stash takes your unfinished edits off the working directory, files them in a separate list and brings your files back to the state of the last commit. It saves you when you have to switch to another branch in the middle of a task and do not want to commit something half done.

$ git stash
Saved working directory and index state WIP on main: 375d973 Revert "fixed the typos"

$ git status
On branch main
nothing to commit, working tree clean

The working directory is clean, and nothing is lost. The stashed sets sit in a stack, the newest one being stash@{0}:

$ git stash list
stash@{0}: WIP on main: 375d973 Revert "fixed the typos"
stash@{1}: On main: pricing edit

There are three ways to get the work back. git stash pop applies the top set and removes its entry from the list. git stash apply applies it and keeps the entry, which is handy when the same draft has to go onto two branches. git stash drop throws the entry away without applying anything.

$ git stash pop
Dropped refs/stash@{0} (d2d1066f68f1307096165b380bf6fde3561c01b5)

Untracked files are left alone by default: a file that has never been through git add stays on disk. The -u flag takes those into hiding as well:

$ git stash -u                       # untracked files included
$ git stash push -m "pricing edit"   # stash it under a name you will recognize

A stashed set is not tied to the branch it came from: hide it on one branch, take it out on another.

Common mistakes

The stack grows without you noticing. A bare git stash writes the same WIP on main line every time, and a week later the list holds five sets nobody remembers anything about. Give them names with git stash push -m, and when you forget, look inside with git stash show -p stash@{0}.

The other place people trip is a conflict on the way back. If the file changed in a commit meanwhile, git stash pop runs into a merge conflict and keeps the entry in the list:

$ git stash pop
CONFLICT (content): Merge conflict in report.txt
The stash entry is kept in case you need it again.

You resolve it by hand like any other merge conflict, then remove the entry with git stash drop.

Where this is in the book

Working with the stash is covered in chapter 8.

Chapter 8. First aid: when something goes wrong

To practise it by hand, open the Sandbox: a real terminal with git and step checks.