What is git stash

Suppose you are working on a feature, the work is still in progress and you are not ready to commit yet. However, you need to switch to another branch to fix a bug or make some other urgent change. You could commit your unfinished work and amend the commit later, but you don't want to do that. You want to keep your commit history clean. What do you do?

You can use git stash instead. It will save your current working directory and index state in a stack of unfinished changes that you can reapply later, and reset your current state to the point where it was before you started working on this feature, the point of your last commit.

How to use it

$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
(use "git add ..." to update what will be committed)
(use "git restore ..." to discard changes in working directory)
        modified: rebase-flow.md

no changes added to commit (use "git add" and/or "git commit -a")

The state is currently dirty, it has uncommitted changes. So now we run git stash and check the status again.

$ git stash
Saved working directory and index state WIP on master: 8f39344 added
a document explaining the rebase workflow

$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

The state is now clean, it has no uncommitted changes. We can now switch to another branch and make the urgent change if we want.

When you run git stash your current uncommitted changes are placed on a stack of unfinished changes. You can run git stash list to see the list of stashed changes. You can run git stash multiple times and each time a new entry will be added to the stack.

$ git stash list
stash@{0}: WIP on master: 8f39344 added a document ...
stash@{1}: WIP on master: 8f39344 added a document ...
stash@{2}: WIP on master: 8f39344 added a document ...

Once you are done with the urgent work and want to resume the work you were doing before you can run git stash apply to apply the topmost stash in the stack. If you want to apply a stash that is not the topmost one you can specify it by its index, for example git stash apply stash@{2}.

$ git stash apply
On branch master
Your branch is up to date with 'origin/master'.

Changes to be committed:
(use "git restore --staged ..." to unstage)
    new file: new-change.md

And things are again in the state they were before you ran git stash. You can now continue working on your feature and commit the changes when you are ready.

But even though you applied the stash, all the entries are still in the stack. To remove the entries from the stack you can run git stash drop to remove the topmost entry, or git stash drop <index> to remove a specific entry. Alternatively, you could run git stash pop instead of git stash apply. That will apply the topmost stash in the stack and also remove it.

Things to take into consideration

git stash will only save the changes that are already tracked by git. If you have new files that are not tracked by git, they will not be saved. You can run git stash -u to save untracked files as well, or simply stage them before stashing your changes. However if you have files that are ignored by git, they will not be saved. You can run git stash -a to save ignored files as well.

Finally, if you want to clear the entire stack of stashed changes and discard all of them you can run git stash clear.