A git stash temporarily shelves your uncommitted changes, both staged and unstaged, and returns your working directory to a clean state, letting you switch context without committing half-finished work and reapply the changes later. It is ideal when you need to quickly pull, switch branches, or address an urgent fix mid-task. Stashes are stored locally as a stack of hidden commits, so you can hold several and restore them in any order.
Key takeaways
- Stashing shelves uncommitted work and cleans your working directory so you can switch context.
git stash popreapplies and removes a stash;git stash applyreapplies but keeps it.- Untracked files are not stashed by default; add the include-untracked option to capture them.
- Stashes form a stack, each identified like
stash@{0}, and are strictly local. - You can stash selected files or interactively choose hunks to stash.
- The stash is for temporary storage; use branches or commits for anything you want to keep.
What does git stash do and when should I use it?
When you run git stash, Git records the current state of your tracked, modified files and then reverts them to match the last commit, giving you a clean working tree. Your changes are not lost; they are saved on a stash stack you can restore later.
Typical situations where stashing shines:
- You are mid-feature and need to switch branches to handle an urgent bug.
- You want to pull upstream changes but have local edits that would conflict with a checkout.
- You started work on the wrong branch and want to move it elsewhere cleanly.
In short, stash is a quick pause button for uncommitted work when committing does not yet make sense.
How do I create and name a stash?
The simplest form stashes all tracked, modified files:
git stashBecause a bare stash is hard to identify later, give it a descriptive message:
git stash push -m "wip: refactor auth middleware"The push form is the current, explicit way to create a stash and also supports stashing specific paths. A message makes a big difference when you have multiple stashes, since git stash list shows each one with its description, letting you pick the right one instead of guessing from an index.
How do I view, apply, and pop stashes?
List the stash stack to see what you have saved:
git stash listEach entry is referenced like stash@{0}, with index 0 being the most recent. To restore, you choose between two commands with an important difference:
| Command | Reapplies changes | Removes from stack | Use when |
|---|---|---|---|
git stash pop |
Yes | Yes | You are done with the stash |
git stash apply |
Yes | No | You want to reuse it or apply to multiple branches |
You can target a specific stash, for example git stash apply stash@{2}. Inspect a stash before restoring with git stash show -p stash@{0}, which prints the diff so you can confirm it is the change you expect.
How do I stash untracked or specific files?
By default, stash only captures tracked files that Git already knows about. New, untracked files are left in place, which can be surprising. To include them:
git stash push -uThe -u or --include-untracked option shelves untracked files too, while -a or --all additionally includes files matched by .gitignore. Use --all sparingly, since ignored files are ignored for a reason.
To stash only certain files, name their paths:
git stash push -m "just the parser" src/parser.jsFor finer control, the patch mode walks you through each change hunk so you decide what to stash:
git stash push -pHow do I turn a stash into a branch, or clean up stashes?
If the base has moved since you stashed and reapplying would conflict, you can create a branch from the stash instead. This checks out a new branch at the commit where the stash was made and applies the stash there:
git stash branch feature-parser stash@{0}To manage the stack, remove entries you no longer need:
git stash drop stash@{1}deletes a single stash.git stash cleardeletes all stashes at once.
Be cautious with clear, since it removes everything and there is no confirmation prompt. Because the stash stack is local and easy to forget, periodically listing and pruning it keeps things tidy.
Where are stashes stored and are they shared?
Stashes live entirely in your local repository. Internally, each stash is recorded as one or more commit objects that capture your working tree and index state, referenced through a special stash ref rather than a normal branch. This is why a stash can hold both staged and unstaged changes.
Two consequences matter in practice:
- Stashes are not pushed: they never travel to a remote, so you cannot use stash to move work between machines. Use a branch and push for that.
- They are tied to the repository, not a branch: you can create a stash on one branch and apply it on another, which is how stash helps when you started on the wrong branch.
- They survive most operations: because the stash ref is separate from your branches, checking out, pulling, and switching branches do not disturb saved stashes, so they remain available until you explicitly pop, drop, or clear them.
This local-only nature is a feature for quick context switches but a trap if you treat stash as a backup. A machine failure or a stray git stash clear takes the work with it, and nothing on the remote can bring it back. When work matters, commit it to a branch and push, which is the only way to get an off-machine copy.
What are common git stash pitfalls?
Stash is convenient but has sharp edges:
- Forgetting untracked files: new files are not stashed by default and remain in your working tree, which can confuse a supposedly clean checkout. Use
-uwhen needed. - Losing track of stashes: unnamed stashes pile up and become mysterious. Always add a message.
- Conflicts on pop: if the base changed, popping can conflict; resolve it like any conflict, and note that a conflicting pop does not drop the stash, so you will not lose it.
- Treating stash as storage: the stash is for short-term shelving. For long-lived work, commit to a branch instead.
- Accidental drop or clear: a dropped stash may still be recoverable through the reflog or
git fsckfor a while, but do not rely on it.
Used with descriptive messages and prompt cleanup, stash is a safe, everyday tool. Used as a dumping ground, it becomes a source of lost work.
How does stash compare to committing or a work-in-progress branch?
Stash is not the only way to set work aside, and choosing the right tool avoids frustration. The alternatives are a throwaway commit or a dedicated branch, each with different trade-offs.
| Approach | Persists remotely | Survives long term | Best for |
|---|---|---|---|
| Stash | No | Not intended to | Quick local context switch |
| WIP commit on a branch | Yes, once pushed | Yes | Sharing or backing up unfinished work |
| Dedicated branch | Yes, once pushed | Yes | Parallel lines of work |
A reasonable rule of thumb: if the interruption is measured in minutes and stays on your machine, stash it. If you need the work on another machine, want a backup, or the pause could last days, make a commit on a branch and push it. You can always soften a work-in-progress commit later with an interactive rebase or by amending, so committing early costs little and is safer than leaving valuable changes in a stash you might forget.
Frequently asked questions
What is a git stash?
A git stash temporarily shelves your uncommitted changes and reverts your working directory to a clean state, so you can restore the changes later.
What is the difference between stash pop and stash apply?
Both reapply stashed changes, but pop removes the stash from the stack after applying it, while apply leaves the stash in place for reuse.
Does git stash include untracked files?
By default no. Use the include-untracked option to stash new untracked files, and the all option to also include ignored files.
Where are stashed changes stored?
Stashes are stored as special commits in your local repository referenced by a stack, and they are not pushed to remotes.
Can I stash only some files?
Yes. You can stash specific paths, or use the patch option to interactively choose which hunks to stash.
How do I recover a dropped stash?
A dropped stash commit may still exist unreferenced for a while, so you can often find it via the reflog or fsck and restore it before garbage collection.
Is git stash a good place for long-term storage?
No. The stash is meant for short-term, temporary shelving. For anything you want to keep, create a branch or commit instead.