Understanding git stash: A Beginners Overview

Understanding The Git Stash

You may have heard of the git stash, but what exactly is it? Let’s learn that today. Git can easily be considered as one of the most important technology in modern software development. It allows a lot developers to work simultaneously on the piece of software.

While the basic git commands like push, pull, add commit does the job for single maintainers, there are some other commands like stash and reabse which becomes absolutely important if you are collaborating with a lot of developers.

In this module we discuss about the stash command in git with special focus on how it works and its use cases.

What is git-stash?

According to the official git documentation,

Use git stash when you want to record the current state of the working directory and the index, but want to go back to a clean working directory. The command saves your local modifications away and reverts the working directory to match the HEAD commit.

For a new users, this usage instruction can be a bit difficult to digest. So let us take a layman approach to understand what git stash does.

According to the oxford dictionary, the verb stash means, “to store (something) safely in a hidden or secret place.”

Git stash as you would have guessed does a similar thing. But instead of hiding an object, it stores the changes to the git tracked files in a hidden place referred to as the stash list.

It makes the uncommitted changes hidden in the git tracking system. Now that we have the basic concept let’s understand the technical terms:

The directory with the uncommitted changes is referred to as dirty. The git stash stores/records this this changes in a hidden directory and deletes them from the actual directory, making it clean. Since there are unstaged changes, the HEAD pointer now points to the latest commit.

Why do we need git stash?

Git lets many developers work on different branches simultaneously. It may happen that you are working on one branch(say feature) where you made some changes and you need to quickly make some commits in another branch(say bug-fix).

If you have some uncommitted changes in the current branch, a weird thing will happen – the uncommitted changes are carried forward from your current branch to the branch you switch to.

For example, the uncommitted work from the feature branch would show up in the bug-fix branch. This is kind of undesirable and annoying! But hold on it has more to it.

You commit some changes in the bug-fix branch Git won’t let you push the changes, because the directory is dirty i.e. there are some uncommitted changes. So you are kind of forced to commit your unfinished code before you push your changes, which is again undesirable.

We see that these uncommitted changes can be a bit of a headache if you want to work on multiple branches simultaneously. Here git stash becomes the saviour, we can stash these uncommitted changes, making the repository look clean. We can reapply these stashed changes whenever we wish to. Now that we have learned how git stash helps us, it is time we learn how to use it.

How to use the stash command

Git stash has three basic functions to perform – stash the changes and apply the stashes and delete the stashes. In this section, we will be discussing the commands for doing so

1. Stash the current changes:

1. To stash the uncommitted changes (both staged and unstaged) we can just use git stash.

git stash

2. Git stashes can be confusing as they are represented by only a hash number. There is no particular way to know the changes it contains until we apply them again. To deal with such problems you can just tag/name the stash using the -m flag. This naming of the stash is very helpful for working with multiple stashes. The command for naming stash is:

git stash push -m "<stash name>"

2. Apply the stash:

Git provides a lot options in dealing with stashes-

1. The git stash apply command applies all the stashes to the current codebase.

git stash apply

2. The git pop applies all the stashes and deletes them from the stash list.

git stash pop

3. Git stash apply and pop might come in handy if you are having a single commit or set of commits that you want to apply altogether. To apply only a single stash we can use the following command

git stash apply stash@{n}

where n indicates the stash index. This command gives more granular control to the user.

4. Similar to the previous command, there is also a git command which allows you pop a single stash from the list. The command for pop stash with index n is

git stash pop stash@{n}

Note: The git stash indexing starts from 0 not 1.

3. Delete the stashes

Some stashes might not be useful anymore and you can remove them using the git stash drop.

1. To drop a single stash with index n use the command :

git stash drop stash@{n}

2. To delete the whole stash list, use the command:

git stash clear

4. Advanced notes:

Git stash stashes only the tracked files by default, this includes all the staged and unstaged changes made to the files. But git stash does not stash the following files:

  1. Untracked files – The files which were added to the user’s codebase, but are not yet staged.
  2. Ignored files – The files which are listed down in the gitignore file and ignored by git.

To add the untracked files to the git stash use the flag -u with the git stash command. This stash will not include the ignored files.

git stash -u -m "<stash-name>"

To include ignored files in the stash use the flag -a. The stash created using this flag will include the tracked, untracked and the ignored files.

git stash -a -m "<stash-name>"


This brings us to end of the article on git stash. Now you are all set to make your git-fu more effective. Stay tuned for more articles on git and other open-source software.