Git Stash: Save Unfinished Work Before Switching Branches
Use Git stash to park unfinished changes, switch branches, and restore the right work without dropping it too early. See how untracked files, conflicts, commits and worktrees change the choice.
6 min read
- Author
-
-
- Published
- Reading time
- 6 min
An urgent bug appears while half-finished edits sit on another branch. Git will stop a switch if it would overwrite local changes, but that does not mean your work is lost. A stash is a temporary shelf: it records the working-tree and index state, then restores them to the current commit. For a short interruption, make a named stash, switch to the urgent task, then apply your saved changes when you return. Git describes this behaviour in its `git stash` manual .
A stash is useful for a brief, local interruption. It is not a normal branch commit, and a regular stash is not automatically copied to a remote or another computer.
Check what needs saving
From the repository, check the branch and working-tree state:
git status --short --branch
git diff
git diff --cached git status shows the current branch and reports staged, unstaged and untracked paths. git diff shows unstaged changes to tracked files; git diff --cached shows what is staged in the index. A new file can appear in git status without appearing in either diff until it is staged. Git's status and diff manuals describe these views.
You do not need to stash before every branch switch. Git can carry local edits across when they do not conflict with the target branch. It refuses when switching would lose local changes. If that happens, first confirm the branch and files you intend to keep. Avoid git switch --discard-changes: that option tells Git to replace the index and working tree with the target branch's state. See the `git switch` manual .
Create a named stash, including new files
Use git stash push with a short description. Add -u when you also need to save untracked files:
git stash push -u -m "wip: settings panel"
git stash list
git status --short --branch With no path restriction, git stash push saves changes to tracked files, including the index state. The -u option adds untracked files. Git stores those changes and removes them from the working tree so you can switch cleanly. The message helps you find the entry later. After a successful stash, the saved paths should no longer appear as local changes; check the final git status output before switching.
Ignored files are different. The command above does not include them. The -a or --all option also stashes ignored files and removes them from the working tree. Use it only when you deliberately want those files moved too; ignored folders can contain build output or local configuration you may not want to clear. The stash options document the distinction between -u and -a.
Switch branches and bring the work back
Switch to the branch for the interruption:
git switch bugfix/login-timeout Replace bugfix/login-timeout and feature/settings-panel below with your actual branch names. Finish the urgent change on its own branch. When you are ready to resume, return to the original branch and inspect the stash list:
git switch feature/settings-panel
git stash list
git stash show --stat 'stash@{0}' stash@{0} means the newest entry, not necessarily the one you just made if you have created other stashes since. Use the description shown by git stash list to select the right entry. To inspect its full patch before restoring it, run:
git stash show -p 'stash@{0}' For a cautious restore, use apply:
git stash apply 'stash@{0}'
git status --short --branch
git diff
git diff --cached apply puts the saved changes on the current branch but leaves the stash entry in the list. Review the files and run the checks that fit your project. Once the restored work is confirmed, remove that one entry:
git stash drop 'stash@{0}' This lets you keep a safety copy while you check the result. The single quotes around stash@{0} also keep the reference intact in shells such as PowerShell. Recheck git stash list before dropping anything if you have more than one entry.
Choose apply or pop
git stash pop applies an entry and removes it from the list if the application succeeds. If it conflicts, Git keeps the stash entry so you can resolve the files and drop it later. apply never removes the entry by itself. Use apply when you want a review step before cleanup; use pop when you are comfortable letting Git remove the entry after a clean application. The `pop` and `apply` reference spells out this difference.
A stash records both the working tree and the index. If you want Git to try to restore which changes were staged, add --index when applying:
git stash apply --index 'stash@{0}' This is an attempt, not a guarantee: Git documents that restoring the index can fail when there are conflicts. Check git status afterward rather than assuming the staged state was restored.
Avoid git stash clear as routine cleanup. It removes every stash entry, and Git warns that cleared entries may become impossible to recover. Drop one named entry only after you have checked the restored files.
If applying the stash conflicts
A conflict usually means the branch changed in the same area as the saved work. Do not discard either side just to make the command finish. Run git status, open each conflicted file, and resolve it in the context of both changes. Stage a resolved file with git add -- path/to/file, then review the staged diff and test the result. The original stash remains available after a conflicted pop; do not apply it again until you know what is already in the working tree.
If the original branch has changed enough that applying the stash there is difficult, git stash branch can create a new branch from the commit where the stash began and apply the saved state there:
git stash branch resume-settings-panel 'stash@{0}'Choose a branch name that does not already exist. If the application succeeds, Git removes that stash entry. This recovery route is documented in the stash manual .
When a stash is the wrong place for work
- You only need a short interruption in the same checkout: use a named stash, then apply it when you return.
- You want a durable checkpoint attached to a branch: make a temporary commit instead. A commit records the staged index on the current branch; use your normal review process before sharing it. See `git commit` .
- You need to work on two tasks at once in separate folders: consider
git worktree, which checks out another branch into another working directory. See `git worktree` .
The safe default is: inspect the state, stash with -u if you have new files, switch branches, restore with apply, and drop the entry only after reviewing the recovered work. If you need the work to be shareable or to outlast this local checkout, keep it in a branch commit instead.
Sources and date
This guide reflects information available by 21 March 2026. Its command examples follow the versioned Git 2.51.0 manuals, whose documented behavior predates that date:
