Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 78 ยท Branching and Merging

Stashing Work in Progress

Learn git stash: shelve uncommitted changes, include untracked files, stash parts with -p, apply or pop, handle conflicts, see how stashes are stored and when to use alternatives.

You are halfway through a change when your colleague asks: "Can you quickly look at the bug on main?" Your files are half-edited, so you cannot just switch branches, and the work is not ready for a commit. Git's answer is the stash: a shelf where you can put your uncommitted changes, get a clean working directory, do the urgent thing, and then take your changes back.

This lesson explains how git stash works, its everyday commands (push, list, show, apply, pop, drop), how to include untracked files, stash only part of your changes, resolve a conflict when restoring, start a branch from a stash, and how stashes are stored (they are just commits). We finish with the alternatives and when they are better.

The basic cycle

git stash (or git stash push) takes all tracked files that have changes, staged or not, saves them, and then resets those files to the last commit. Your working directory is clean again. git stash pop restores the changes and removes the stash.

Bash Stash, switch around, then pop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git stash prints Saved working directory and index state WIP on main: <hash> Add notes (that line is the stash's automatic description: "WIP on" + branch + the commit you were on). After it, notes.txt was back to two lines. git stash pop brought the third line back and printed Dropped refs/stash@{0}, and the list is empty again.

The pop command is "apply, then drop". If you want to keep the stash after applying (to apply it to several branches, say), use git stash apply, and drop it yourself later with git stash drop.

Several stashes, with names

Stashes stack up. The newest is stash@{0}, the one before is stash@{1} and so on. Unnamed stashes quickly become mysterious, so give each one a message with -m.

Bash A stack of named stashes: list, show, apply, drop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git stash show summarizes a stash as a --stat; add -p for the full diff. In a shell, quote 'stash@{1}' because the braces have special meaning. git stash clear deletes every stash at once and is not undoable in normal use, so be sure. A dropped single stash can sometimes be recovered; Git prints its commit hash when you drop it, and git fsck --unreachable can find it (see The Reflog and Recovering Lost Work).

Always use git stash push -m "why" when you plan to leave a stash for more than a few minutes. A list full of WIP on main: 4f3c2b1 ... entries tells you nothing a week later.

Untracked and ignored files

By default stash saves only changes to files Git tracks. A brand-new file you have not added is left in place, which is a common surprise: you stash, switch branches, and the new file is still there.

  • git stash -u (--include-untracked) also stashes new files.
  • git stash -a (--all) also stashes files that .gitignore hides, such as build output. It is rarely what you want.
Bash Stashing untracked files with -u

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

After the plain stash, new.txt still showed up as ?? (untracked). With -u the status was empty, and ls showed only a.txt. When you pop, the untracked file comes back along with the tracked edits.

Stashing only some of your changes

You can limit a stash to chosen files by listing paths after --, and to chosen hunks with -p, which uses the same prompts as git add -p (see Staging Changes). Another useful switch is --keep-index, which stashes everything but leaves staged changes in place, so you can test exactly what you are about to commit.

Bash Stash one file, then one hunk

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

First -- one.txt limited the stash to that path, so two.txt stayed modified. Then the patch mode saved only the hunk we accepted (line 2) and left line 29 modified in the working tree, as the final git diff lines show. With --keep-index, one.txt is still staged (M ) while the unstaged two.txt change went into the stash.

Conflicts when restoring

A stash is applied like a merge: Git compares your stash with the commit it was made from and the current state. If the same lines changed in both places you get a conflict, and pop will not drop the stash when that happens, so you cannot lose it.

Bash Popping into a conflict keeps the stash

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The output says CONFLICT (content): Merge conflict in c.txt and The stash entry is kept in case you need it again. The file now has the familiar markers, but labelled Updated upstream (your current files) and Stashed changes (the stash) instead of HEAD and a branch name. Resolve it as in Resolving Merge Conflicts, run git add c.txt (and git restore --staged c.txt if you prefer the change unstaged), and then drop the stash yourself with git stash drop.

If you would rather start from the commit the stash was made on, there is a command that does it with no conflicts possible:

TEXT
git stash branch new-feature            # newest stash
git stash branch new-feature stash@{1}  # an older one

It creates new-feature at the commit the stash came from, checks it out, applies the stash there and drops it. This is the perfect cure for "my stash conflicts because main has moved on".

A stash is just commits

A stash is not magic storage: it is made of ordinary commits, referenced by refs/stash. One stash is a merge commit with two or three parents: the commit you were on, a commit recording the index, and (with -u) one more for untracked files. This is why stashes can be shown, diffed and rebuilt using regular tools.

Bash Look inside a stash

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The stash has two parents (the base commit and the index commit), its subject is On main: my work, and stash@{0}:f.txt reads the file as it was when stashed. Because stashes live in the reflog of refs/stash, an old stash that has been dropped is found with git fsck --unreachable | grep commit. Stashes are local: they are never pushed or fetched.

When not to stash

Stash is a convenience, not a storage system. Three alternatives are often better:

  • A WIP commit. git commit -am "WIP: login form" on your branch is safer than a stash because it lives in a branch's history, shows in git log, and can be amended or squashed later. Many professionals commit WIP and never stash.
  • A new branch. If the interruption is long, commit to a branch (git switch -c wip-login) and come back later.
  • A worktree. If you need to work on another branch while your edits stay put, git worktree add ../hotfix main gives you a second directory without touching your current files. See Worktrees.

Use stash for short interruptions: "pull in the latest changes first", "run the tests on a clean tree", "try this on another branch".

Pitfalls professionals know

  • Forgotten stashes pile up. Run git stash list now and then, and clean out old ones.
  • Stashes record the branch only in the message. Popping on a different branch works, but you may apply code to the wrong place. Check the description first.
  • Staged state is lost by default. pop restores the changes as unstaged. Use git stash pop --index to restore staged vs unstaged exactly (it fails if the index no longer matches).
  • Binary files and big edits make large stashes. A commit would be no bigger, though.
  • git stash with no changes prints No local changes to save. Not an error; nothing happens.
  • Submodules are not stashed with the parent repository.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does plain git stash save?

    By default stash saves modifications to tracked files. Use -u for untracked files and -a for ignored files too.
  2. 2. What is the difference between git stash pop and git stash apply?

    pop is apply followed by drop. With apply the stash stays on the list until you drop it.
  3. 3. A git stash pop runs into a conflict. What happens to the stash entry?

    Git keeps the stash when the apply conflicts. Resolve the conflict and drop it yourself with git stash drop.
  4. 4. How do you give a stash a descriptive name?

    git stash push -m records a message that appears in git stash list.
  5. 5. What are stashes made of internally?

    A stash is a merge commit (with parents for the base commit and the index) kept alive by refs/stash and its reflog.

Summary

  • git stash push -m "msg" shelves tracked changes and cleans the working tree; git stash pop restores and removes, apply restores and keeps.
  • Use -u for untracked files, -- path for specific files and -p to choose hunks; --keep-index leaves staged changes in place.
  • git stash list, show -p, drop and clear manage the stack; address entries as 'stash@{n}'.
  • A conflicting pop keeps the stash; git stash branch name avoids conflicts by starting at the original commit.
  • A stash is just commits under refs/stash; it is local and never pushed.
  • For longer interruptions, prefer a WIP commit, a branch or a worktree.

Next: Cherry-Pick and Applying Commits