Lesson 08 beginner

Git Stash

Put unfinished work aside with git stash, list and inspect stashes, apply versus pop, include untracked files, stash only part of your changes, turn a stash into a branch, resolve stash conflicts and move stashes between machines with export and import from Git 2.51.

You are halfway through the search feature, nothing compiles yet, and an urgent bug report arrives: production logins time out. You need a clean working tree now, but your half-done work is not worth a commit. git stash saves your uncommitted changes on a shelf, gives you a clean tree and lets you bring the changes back later.

Stash and get them back

$ git status -s
 M search.js
 M server.js
$ git stash push -m "search: half-done ranking"
Saved working directory and index state On feature/search: search: half-done ranking
$ git status -s
$                                   # clean

Now fix the bug on its own branch, commit, push, and come back:

$ git switch -c fix/login-timeout main
$ git commit -am "Raise login timeout to 30 seconds"
$ git switch feature/search
$ git stash pop
On branch feature/search
Changes not staged for commit:
	modified:   search.js
	modified:   server.js
Dropped refs/stash@{0} (4be1a2c...)

git stash without arguments does the same as git stash push, but always add a message with -m: in two weeks, “WIP on feature/search” tells you nothing.

Looking at the shelf

Stashes form a stack. The newest is stash@{0}:

$ git stash list
stash@{0}: On feature/search: search: half-done ranking
stash@{1}: On main: try nginx gzip settings
$ git stash show stash@{1}          # files changed
$ git stash show -p stash@{1}       # full diff

apply versus pop

CommandRestores the changesRemoves the stash
git stash applyYesNo
git stash popYesYes, if it applied cleanly
git stash dropNoYes
git stash clearNoRemoves all stashes

apply is useful when you want the same changes on two branches, or when you are not sure the changes will apply cleanly. Use git stash drop stash@{1} afterwards to clean up.

What gets stashed

By default, stash saves changes to tracked files, both staged and unstaged. New files that were never added stay where they are. Use options to change that:

OptionAlso stashes
(none)Modified tracked files, staged or not
-u, --include-untrackedPlus new untracked files
-a, --allPlus ignored files (rarely what you want)
--stagedOnly what is staged (Git 2.35)
-p, --patchOnly the hunks you pick
-- <path>Only these files
$ git stash push -u -m "search: with new test file"
$ git stash push -m "only the config" -- config/
$ git stash push --keep-index -m "test what is staged"

--keep-index stashes everything but leaves the staged changes in place, which lets you test exactly what you are about to commit.

When pop conflicts

If the branch changed the same lines since you stashed, applying conflicts like a merge:

$ git stash pop
CONFLICT (content): Merge conflict in server.js
The stash entry is kept in case you need it again.

Resolve the markers as in lesson 5 and git add the file. Because the pop failed, the stash was not dropped; once you are happy, remove it with git stash drop. If you would rather start over, git restore server.js and try again on a different branch.

Turning a stash into a branch

If the stash no longer applies cleanly, or you realise this “quick experiment” deserves its own branch, create a branch from the commit you were on when you stashed and apply the stash there:

$ git stash branch experiment/gzip stash@{1}
Switched to a new branch 'experiment/gzip'
Dropped stash@{1}

This always applies cleanly, because the branch starts exactly where the stash was made.

Moving stashes between machines (Git 2.51)

Stashes are local: they are never pushed. Git 2.51 added a way to export them as ordinary commits that you can push and import elsewhere, which helps when you switch from a laptop to a desktop mid-task:

$ git stash export --to-ref refs/stashes/ana
$ git push origin refs/stashes/ana

On the other machine:

$ git fetch origin refs/stashes/ana:refs/stashes/ana
$ git stash import refs/stashes/ana
$ git stash list

Delete the ref on the server when you are done with git push origin --delete refs/stashes/ana.

When not to stash

Stash is a short-term shelf, not storage. Stashes are easy to forget, they are not backed up and old ones apply badly. If work will be paused for more than a day, commit it on a branch, even as a “wip” commit you squash later (lesson 6), and push it. Another option for parallel work is git worktree (lesson 12): a second working folder with a different branch checked out, so you do not need to put anything aside.

Quick reference

TaskCommand
Stash with a messagegit stash push -m "message"
Include untracked filesgit stash push -u
Stash part of the changesgit stash push -p / -- <path>
Listgit stash list
Show a stash’s diffgit stash show -p stash@{n}
Restore and removegit stash pop
Restore and keepgit stash apply stash@{n}
Remove one / allgit stash drop stash@{n} / git stash clear
Stash to a new branchgit stash branch <name> stash@{n}
Export to share (2.51)git stash export --to-ref refs/stashes/<name>

Exercise

You created a new file notes.md and modified server.js. You run git stash. What is left in your working tree?

  1. Nothing, both changes are stashed
  2. server.js is still modified, because only new files are stashed
  3. Both changes stay; stash only saves a copy
  4. notes.md is still there, because untracked files are not stashed by default
Show answer

Answer: D. Plain git stash only saves changes to tracked files. New, never-added files stay unless you use -u. Stashing then pulling a branch that also has notes.md would cause a surprise.

Exercise

git stash pop stops with a conflict. After you resolve the file, what is the state of the stash?

  1. It was dropped when pop started
  2. It was converted into a commit automatically
  3. It is still in the list, because pop only drops a stash that applied cleanly
  4. It was moved to stash@{1}
Show answer

Answer: C. When pop hits a conflict, Git keeps the stash entry so nothing is lost. After resolving and checking the result, remove it yourself with git stash drop.

Exercise

An old stash no longer applies cleanly to the branch, which moved a lot. What applies it without conflicts?

  1. git stash apply –force
  2. git stash branch new-branch stash@{n}
  3. git stash pop –theirs
  4. git rebase stash@{n}
Show answer

Answer: B. git stash branch creates a branch at the commit where the stash was made and applies it there, so the changes always fit. You can then merge or rebase that branch normally.

Key takeaways

  • git stash push -m shelves uncommitted changes and leaves a clean working tree.
  • pop restores and removes, apply restores and keeps; a conflicted pop keeps the stash.
  • Untracked files need -u; -p, --staged and paths stash only part of your changes.
  • git stash branch turns a stash into a branch when it no longer applies cleanly.
  • Stashes are local and short-lived; Git 2.51’s export and import move them between machines, but for longer pauses commit on a branch.

FAQ

Are stashes pushed with git push?

No. They live in your local repository only. Use git stash export (Git 2.51) to turn them into a ref you can push, or commit the work on a branch.

I dropped a stash by mistake. Can I recover it?

Often yes. git stash drop prints the commit ID of the dropped stash; run git stash apply <id>. Without the ID, git fsck --unreachable | grep commit lists orphaned commits, and stashes are among them until garbage collection removes them.

What is the difference between git stash and a wip commit?

A stash is not attached to any branch and is easy to forget. A wip commit sits on your branch, can be pushed as a backup and is cleaned up later with an interactive rebase. For anything longer than a quick interruption, the commit is safer.

Can I stash only staged changes?

Yes, since Git 2.35: git stash push --staged. The reverse, stashing everything except what is staged, is git stash push --keep-index.

Does git stash save files listed in .gitignore?

No, not even with -u. Only -a (--all) includes ignored files, which usually drags in build output and dependencies, so use it carefully.

↑ ↓ navigate Enter open Esc close