You are halfway through a change when another task needs attention. The working directory contains edited files, a new component, and perhaps a few generated files. Git stash can help create a temporary stopping point, but only if you understand what the stash includes.
The most useful habit is to inspect the working directory before saving anything. A stash should represent a known set of changes, not an assumption that every visible file has been captured.
Check what you are about to save
Start with:
git status --shortReview the tracked modifications and newly created files. By default, stashing does not include untracked files. The -u option includes them, while ignored files remain a separate category. Git’s documentation distinguishes this from -a, which also includes ignored files.
If the new component belongs to the work being paused, an example command is:
git stash push -u -m "WIP: search filter layout"The message should identify the work in terms you will recognize later. A stack of entries called “temporary changes” becomes difficult to navigate surprisingly quickly.
Do not include ignored output indiscriminately. First determine whether those files are necessary to resume the work or can be reproduced.
Inspect the saved entry
After creating the stash, inspect both the working directory and the stash list:
git status --short
git stash listA stash can then be inspected using an entry reference:
git stash show --stat 'stash@{0}'This check confirms which entry you are about to use. Be aware that numbered stash references describe positions in the current list; they are not descriptive project names.
Git documents stash as saving local working-directory and index changes so the tracked working state can be returned toward HEAD. Its list and inspection commands help make that temporary state visible.
Before switching tasks, verify that any files left behind are expected. An unexplained file is a reason to investigate, not a reason to assume the stash has handled it.
Understand apply versus pop
git stash apply restores an entry without removing it from the stash list. A successful git stash pop applies an entry and removes it. If popping encounters conflicts, the entry is retained.
For cautious recovery, applying first gives you time to inspect the restored work:
git stash apply 'stash@{0}'Check the diff and run the relevant validation before removing the saved entry. This makes the decision to discard the temporary copy explicit.
If conflicts occur, inspect the repository state and resolve them deliberately. Repeatedly applying the same stash without understanding the first result can make the working tree harder to reason about.
Keep stash temporary and understandable
Stash is useful for short interruptions. For work that needs review, collaboration, or a durable project history, consider an appropriately named branch and commits instead.
Leave enough context for your future self. Record what remains unfinished, especially when the code currently fails a test or depends on an uncommitted local assumption.
The goal is to resume with confidence. Know what was saved, identify the correct entry, restore it into an understood working state, and verify the result before cleaning up.
- Git: git-stash documentation
- Pro Git: Stashing and Cleaning
