You're in the middle of building a feature. Half your files are edited, nothing is committed, and it's not in a state you'd want to save as a real commit yet. Then someone pings you: "Can you quickly check something on main?" Or worse, you need to pull the latest changes from your team, and Git refuses because your uncommitted edits would get overwritten.
Committing half-finished work just to switch away feels wrong. Deleting it and starting over later is worse. This is exactly the situation git stash was built for.
Welcome to BytebaseX. I'm Suptojit Modak, and in this guide, I'll walk through what git stash actually does, how to use it beyond the basic command, and a few habits that will save you from the one mistake almost everyone makes with it eventually: forgetting a stash exists.
What Git Stash Actually Does
Think of git stash as a shelf next to your project, separate from your commit history entirely. When you stash your changes, Git takes your current uncommitted edits, both staged and unstaged, and tucks them away on that shelf. Your working directory goes back to looking exactly like your last commit, clean and untouched, as if you never started editing anything.
Nothing about a stash is a commit. It doesn't show up in git log, it doesn't get pushed anywhere, and it lives only on your local machine.
This matters because it means stashing is genuinely low-risk and low-effort compared to the alternatives. You're not creating a messy "WIP" commit you'll need to clean up later, and you're not deleting work you might still need.
The Basic Command
Let's say you've been editing a file and you need to switch branches right now:
git statusOn branch feature-login
Changes not staged for commit:
modified: login.jsStash it with one command:
git stashSaved working directory and index state WIP on feature-login: a1b2c3d Add login formRun git status again, and your working directory is clean. login.js shows no changes at all. You can now switch branches, pull updates, or do whatever you needed to do, without Git complaining about uncommitted work in the way.
When you're ready to bring your changes back:
git stash popOn branch feature-login
Changes not staged for commit:
modified: login.js
Dropped refs/stash@{0}Your edits to login.js are back exactly as you left them, and the stash entry is removed since pop applies it and deletes it from the shelf in one step.
A Live Demo: Where Your Changes Actually Go
Reading about a "shelf" is one thing, watching it happen is another. Click through the buttons below to see how your working directory and the stash relate to each other.
Working Directory (login.js)
Stash Shelf
Click a button above to see how the changes move.
Naming Your Stashes
The plain git stash command works fine when you're only juggling one stash at a time. The moment you have more than one, you'll immediately regret not naming them, because they all default to the same generic label. Fix this by adding a message:
git stash push -m "half-done validation logic for login form"Note the command here is git stash push, not just git stash. Plain git stash is actually shorthand for git stash push with no extra options, but once you want to add a message or target specific files, you need to spell out push explicitly.
Working With Multiple Stashes
See everything currently on the shelf:
git stash liststash@{0}: On feature-login: half-done validation logic for login form
stash@{1}: On main: quick css tweak before demo
stash@{2}: On feature-login: WIP on feature-login: a1b2c3d Add login formEach entry gets a number, starting at 0 for the most recent stash. This is exactly why naming them matters: without the message, all you'd have to go on is the branch name and a commit hash, which tells you almost nothing three days later.
To apply a specific stash instead of the most recent one:
git stash apply stash@{1}apply, not pop. That distinction is the single most common point of confusion with stashing, and it's worth its own section.Apply vs Pop: The Difference That Actually Matters
Both commands bring your stashed changes back into your working directory. The difference is what happens to the stash entry afterward.
git stash popapplies the changes and removes that entry from the stash list. Use this when you're confident you're done with that stash.git stash applyapplies the changes but keeps the entry on the shelf. Use this when you want to apply the same stash to more than one branch, or when you're not fully sure the apply will go cleanly and want a safety net still sitting there.
A genuinely useful pattern: if you're not sure whether a stash will merge cleanly into your current state, use apply first. If it applies without conflicts, you can manually drop it afterward. If something goes wrong, the stash is still safely sitting on the shelf and nothing was lost, unlike a pop that already removed the entry before you knew there'd be a problem.
Stashing Only Part of Your Changes
Sometimes you've edited three files, but you only want to stash one of them and keep working on the others. Target specific files by listing them after --:
git stash push -m "just the css changes" -- styles.cssEverything else in your working directory stays exactly as it was. Only styles.css gets reset to its last committed state and moved to the stash.
What About New Files That Aren't Tracked Yet?
By default, git stash only stashes changes to files Git is already tracking. If you created a brand new file and haven't run git add on it yet, a plain git stash will leave that new file sitting in your working directory, untouched.
Most of the time this is fine, but if you need a truly clean working directory, including new files, add the -u flag:
git stash -uThis includes untracked files in the stash too. There's also -a (or --all), which goes a step further and includes files your .gitignore would normally exclude, though you'd rarely want that unless you have a specific reason to stash ignored files as well.
Looking Inside a Stash Without Applying It
Before you commit to popping a stash, especially an old one you half-remember, it's worth checking what's actually inside it:
git stash show -p stash@{0}This prints a full diff of everything in that stash, exactly like git diff would, without touching your working directory at all. If you just want a quick summary of which files changed rather than the full diff, drop the -p flag:
git stash show stash@{0} login.js | 12 ++++++++++--
1 file changed, 10 insertions(+), 2 deletions(-)Cleaning Up: Dropping and Clearing Stashes
If you decide you don't actually need a stash anymore, remove it without applying it:
git stash drop stash@{1}If you want to wipe every stash entry at once, which is worth doing occasionally if you've built up a pile of old ones you no longer need:
git stash cleargit stash clear deletes every stash immediately, and unlike most Git operations, there's no simple undo command for it. Run git stash list first and actually read through it before clearing, especially if you haven't touched your stash list in a while.Recovering a Stash You Accidentally Dropped
Dropped a stash by mistake and immediately regretted it? Since a stash is really just a special kind of commit under the hood, it isn't gone the instant you drop it, the same way regular commits stick around briefly after you think you've lost them. Run:
git fsck --unreachable | grep commitThis lists dangling commit objects, which will often include your recently dropped stash. You can inspect any of the resulting hashes with git show <hash> to find the right one, then recover it with git stash apply <hash>. This is the same underlying recovery approach covered in more detail in How to Undo Almost Any Git Mistake, if you want the fuller picture of how Git holds onto data longer than people expect.
When Stashing Isn't the Right Tool
Stashing is meant to be short-lived, a few minutes to a few hours, not a long-term parking spot for unfinished work. If you find a stash sitting around for more than a day or two, it usually means the work deserves its own branch instead. Creating a branch keeps the work visible in your normal Git history and easy to come back to, rather than buried in a stash list you might forget about entirely. If branching itself is still a bit fuzzy, our beginner's guide to Git branching covers that from the ground up.
Quick Reference
| What you want | Command |
|---|---|
| Stash your current changes | git stash |
| Stash with a description | git stash push -m "message" |
| Stash including untracked files | git stash -u |
| Stash only specific files | git stash push -- file.js |
| See all stashes | git stash list |
| Preview a stash's contents | git stash show -p stash@{0} |
| Apply and remove the latest stash | git stash pop |
| Apply but keep it on the shelf | git stash apply stash@{0} |
| Delete one stash | git stash drop stash@{0} |
| Delete every stash | git stash clear |
Frequently Asked Questions
Does git stash work across different branches?
Yes. A stash isn't attached to the branch you created it on. You can stash changes on one branch, switch to another, and apply or pop the stash there. Git will try to merge the stashed changes into your current state and will show a normal merge conflict if the same lines were changed on both sides.
What happens if popping a stash causes a conflict?
Git will mark the conflicting lines in your files, the same way it does for a regular merge conflict, and leave the stash entry in place rather than dropping it. Resolve the conflict manually, then run git stash drop yourself once you're satisfied everything merged correctly.
Can I stash changes that are already staged with git add?
Yes, by default git stash captures both staged and unstaged changes together. If you specifically want to keep your staged changes in place and only stash the unstaged ones, use git stash push --keep-index.
Is there a limit to how many stashes I can have?
No hard limit, but there's a practical one: past a handful of stashes, it becomes genuinely hard to remember what each one contains, even with good messages. If you're regularly sitting on more than two or three stashes at once, that's usually a sign some of that work should become a proper branch instead.
Do stashes get pushed to GitHub or GitLab along with my commits?
No. Stashes are entirely local and never get pushed anywhere. They exist only in your own repository's local Git data, which also means switching to a different computer or cloning the repo fresh gives you zero access to stashes made elsewhere.
Should I use git stash or just create a new branch?
Use a stash for a quick interruption you expect to return to within minutes or hours, like switching branches briefly or pulling updates. Use a branch for anything you'd want tracked in your normal Git history, anything you might need to come back to days later, or anything you'd want a teammate to be able to see and pick up.
Conclusion
Git stash solves a specific, narrow problem well: you have work you're not ready to commit, but you need a clean working directory right now. Learn push with a message, pop versus apply, and list, and you'll cover the vast majority of situations where reaching for a stash actually makes sense.
The one habit worth building from day one: name your stashes. Future you, three stashes deep on a Friday afternoon, will not remember which one was "quick css tweak" and which one was "WIP."
