You are halfway through a refactor when a production bug arrives. You cannot commit the half-finished work, and you cannot switch branches with uncommitted changes in the way. git stash moves the changes aside, gives you a clean tree, and lets you restore them later.

The basic loop

git stash push -m "wip: checkout refactor"
git checkout main
# fix the bug, commit, push
git checkout feature/checkout
git stash pop

push saves tracked modifications and staged changes, then reverts the working tree to HEAD. pop applies the most recent stash and removes it from the list. apply applies it but keeps the stash.

Use apply when you are unsure. If the apply goes wrong, the stash is still there. pop is a convenience that deletes the safety copy.

Inspect before applying

git stash list
git stash show -p stash@{0}

list shows the stack, newest first. show -p prints the diff. A stash created weeks ago may no longer apply cleanly, and reading the diff first tells you what you are about to reintroduce.

Include untracked files

By default, stash ignores untracked files. New files stay in the working tree and may block a checkout. Include them:

git stash push -u -m "wip with new files"

-u includes untracked files; -a also includes ignored files. -a is rarely what you want, because it can stash build artifacts and dependencies.

Partial stash

To stash only some changes:

git stash push -p -m "only the parser changes"

Git prompts for each hunk. This is useful when one file contains both a finished fix and unrelated work in progress. It is interactive, so it does not fit every terminal, but it is the cleanest way to isolate a change.

Restore into a new branch

If the branch you stashed from has moved a lot, apply the stash on a fresh branch:

git stash branch fix/restore stash@{0}

This creates a branch at the commit the stash was based on, applies it there, and drops it on success. It is the safest way to recover an old stash.

Conflicts

A stash is a set of diffs against a specific base. If the base has changed, applying can conflict:

git stash apply
# CONFLICT (content): Merge conflict in src/parser.ts

Resolve the files, git add them, and then drop the stash manually:

git stash drop stash@{0}

Do not drop before you are satisfied. The stash is the only copy if the changes were never committed.

Stash versus WIP commit

A stash is local, easy to forget, and not included in backups or pushes. A temporary commit is visible, can be pushed to a draft branch, and survives a disk failure.

For a short interruption, stash is fine. For work that will span days or move between machines, commit to a wip/ branch and push it. A stash list with fifteen unnamed entries is a sign that the workflow has outgrown the tool.

Cleaning up

git stash drop stash@{2}    # remove one
git stash clear             # remove all

clear is irreversible. Check git stash list twice before running it.

Common mistakes

  • Stashing with a dirty index and expecting the staged/unstaged distinction to survive. It does survive, but pop --index is needed to restore the index state.
  • Forgetting -u, then wondering why the new files are still there.
  • Applying a stash on a completely different branch and treating the conflicts as a code review.
  • Using stash as long-term storage. It is a clipboard, not a filing cabinet.

The stash reference covers --index, --keep-index and the full option list. If you need to undo a commit rather than set work aside, see the undo commit guide.