What you can do after this lesson
You will be able to park unfinished work, switch to something urgent, and come back without making a messy commit or losing edits. Stash is a safety shelf for the working tree. The examples use a tiny page file; hashes in your output will differ.
The situation
You are halfway through editing page.txt when a teammate asks you to look at a bug on another branch. Git will not let you switch if your uncommitted changes would be overwritten, and you do not want to commit broken work. Stash solves it:
echo "half done" >> page.txt
echo "idea" > ideas.txt
git status -s M page.txt
?? ideas.txtNow stash:
git stash
git status -s
git stash listSaved working directory and index state WIP on main: 861ab87 Add page
?? ideas.txt
stash@{0}: WIP on main: 861ab87 Add pageThe modification to page.txt is saved and the tracked file is back to its committed state. The untracked ideas.txt stayed. The default message WIP on main: 861ab87 Add page names the branch and the commit you were on.
Getting the work back
git stash pop reapplies the newest stash and removes it from the list:
git stash popIf you want to keep the stash around (for instance, to apply the same edit to several branches), use git stash apply, then git stash drop when you are finished:
git stash apply
git stash list
git stash dropOn branch main
Changes not staged for commit:
...
modified: page.txt
stash@{0}: WIP on main: 861ab87 Add page
Dropped refs/stash@{0} (d0f204c913feb231d616e4486611f82df5efa27c)(Part of the status text is elided with ....) You may switch branches between stashing and popping; the stash is not tied to the branch it came from. It applies to whatever you have checked out, so check the branch before you pop.
Including untracked files and naming stashes
-u includes untracked files. -m gives a message you will recognise later:
git stash push -u -m "ideas in progress"
git stash listSaved working directory and index state On main: ideas in progress
stash@{0}: On main: ideas in progress
stash@{1}: WIP on main: 861ab87 Add pageThe list is a stack, newest first, so older stashes get higher numbers. Name stashes whenever you keep more than one; WIP on main tells you nothing in a week. Look inside one without applying it:
git stash show -p 'stash@{1}'diff --git a/page.txt b/page.txt
index c0d0fb4..74b529b 100644
--- a/page.txt
+++ b/page.txt
@@ -1,2 +1,3 @@
line1
line2
+half done(Quote stash@{1} in some shells, because braces are special to them.) Apply a specific entry by naming it, for example git stash pop 'stash@{1}', and delete one with git stash drop 'stash@{0}'. git stash clear removes all of them, so use it only when you are sure.
When the stash conflicts
If the code you stashed changed lines that someone since changed in a commit, applying it can conflict. This is the important safety feature. In a test where file2.txt was edited both in the stash and in a later commit:
git stash popAuto-merging file2.txt
CONFLICT (content): Merge conflict in file2.txt
...
The stash entry is kept in case you need it again.Git did not drop the stash. Resolve the markers exactly as you would in a merge (previous section of the course), git add the file, and then remove the entry yourself with git stash drop. If you would rather abandon the attempt, run git restore --staged . and git restore . to undo the half-applied changes, then try another approach.
A stash is a commit in disguise
Under the hood, Git stores each stash as a pair of commits kept on a special reference, which is why it is safe. It is also not a good long-term home. Stashes are local, they are not pushed, and they are easy to forget about. For work you want to keep for days, make a branch and commit, perhaps with a message like "WIP: login form" that you tidy later.
There is a handy shortcut when you realise your stashed work deserves its own branch:
git stash branch rescue-workThis creates a new branch starting from the commit where you stashed, applies the stash, and drops it if it applied cleanly. It is verified output in our test: Switched to a new branch 'rescue-work' followed by the status with modified: page.txt and Dropped refs/stash@{0}.
Stash in a real day
A typical use: you are partway through a feature when a colleague reports a typo on the live page. You stash, switch to main, fix the typo in a small branch, push, and switch back. Then git stash pop returns you to your unfinished work as if nothing happened. The key habit is to name your stash and pop it soon, because a stash you forget about is simply unfinished work you have lost track of.
Common mistakes
- Forgetting untracked files. New files are not stashed without
-u. - Leaving stashes to rot. Review
git stash listnow and then. - Popping on the wrong branch. The changes apply to whatever you are on.
- Believing a stash is a backup. It lives only in your clone.
- Using
git stash clearcarelessly. It deletes all entries in one command; they are recoverable only with advanced tools.
Exercise
- Edit a tracked file and create a new untracked file.
- Stash only the tracked change, check the status, and pop it.
- Stash both with a message, switch to another branch and back, list the stash, and apply it without dropping.
- Create a conflict by editing the same line in a later commit, and see that
popkeeps the entry.
Show one possible answer
echo extra >> page.txt && echo note > note.txt
git stash
git status -s
git stash pop
git stash push -u -m "page edit and note"
git switch -c other && git switch -
git stash list
git stash apply
git stash dropFor the conflict, stash an edit to line 1, commit a different edit to line 1, then git stash pop: the conflict message appears and git stash list still shows the entry.
Key points
- git stash saves your uncommitted changes to tracked files and restores a clean working tree.
- git stash pop reapplies the latest stash and removes it; git stash apply reapplies it and keeps it.
- Use -u to include untracked files and -m to give the stash a name.
- git stash list shows entries as stash@{0}, stash@{1} and so on, newest first.
- If applying causes a conflict, Git keeps the stash so nothing is lost; resolve the conflict like any other.