Synopsis

git stash [push [-m <msg>] [-u]]
git stash pop [<stash>]
git stash list
git stash drop [<stash>]

Description

The git stash command shelves uncommitted changes (in both working tree and index) and reverts the working tree to a clean state. The shelved changes are stored on a stack you can re-apply later. Stash is perfect for situations like "I need to switch branches but my work isn't ready to commit."

By default, untracked files are not stashed; pass -u (or --include-untracked) to include them, and -a to include even ignored files. Each stash entry is a regular commit object, addressable as stash@{0}, stash@{1}, etc.

In day-to-day use, git stash integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git stash --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.

Understanding how git stash interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git stash's side effects helps avoid all three.

Common Options

Examples

git stash push -m "WIP: refactor parser"
# Save current work with a label

git stash list
# stash@{0}: On main: WIP: refactor parser

git stash pop
# Re-apply the most recent stash and remove it

git stash branch temp-branch stash@{1}
# Create a new branch from a stash that conflicts

Common Mistakes

Forgetting that stash doesn't include untracked files by default, then losing them when running git clean. Use -u. Popping a stash that conflicts can leave a complicated state — consider apply first so the stash isn't dropped if things go wrong. Long-lived stashes accumulate; review with git stash list regularly.

Related Commands

git commit, git switch, git restore, git clean