Git’s stash might be one of the most underused features of git from my observations in the field.

I do see the stash used a lot since it actually is a handy tool but most people I know (and that included me for the longest time!) only use it in a very basic way: git stash and git stash pop.

In case you have never used the stash before, here is a quick explanation: Sometimes you are busy working on something when another change comes up that you need to make more urgently. Of course you do not want to lose the changes that you have made already. One option that you have now is to create a new branch and commit your changes as a work in progress there and then continue on your base branch. Since this is an issue that comes up often though, there also is the dedicated stash command. You can run git stash which will take all of your uncommited changes and put them on “the stash”. You can then make your more urgent changes and once you are done with those, you can pop (git stash pop) the item from the stash again which will reapply those uncommited changes and let you continue where you left off.

This is the way that I used stash for the longest time - as a simple Last In First Out stack. The stash can be much more flexible though. Let me give you some examples:

Inspecting the stash

Say you have stashed two times (because maybe you started working on the more important topic when something even more important came up). Your stash is now going to look like this (which you can see by doing git stash list):

stash@{0}: WIP on master: 24d752c initial commit
stash@{1}: WIP on master: 24d752c initial commit

You can see that there are two items on the stash. It is not very easy to tell though, which change is responsible for what. Luckily, we can take a peek at the entries by doing git stash show -p 'stash@{1}'. This will give you the same view at your stash content that your are used to from doing a git diff. By specifying the reference here (stash@{1}), we can pick a specific item on the stash that we are interested in.

Naming your stash items

One level up from this is to write down what changes you are making in the moment that you are stashing. You can do this by supplying a message when adding a new item to the stash. Instead of doing git stash, you could do a git stash push -m <message> . git stash list will now look like this (after I called git stash push -m 'add type hints') which is much easier to scan:

stash@{0}: On master: add type hints
stash@{1}: WIP on master: 24d752c initial commit

Keeping changes on the stash

There are some more tricks: Instead of always popping the last item via git stash pop you can also pop a specific stash item. This looks very similar to the inspecting example from above: git stash pop 'stash@{1}' (or the short version git stash pop 1). If you want to reapply changes but don’t want to remove them from the stash, you can use git stash apply instead of pop. This will also reapply your changes but will not remove the entry from the stash. Of course apply also lets you apply any item from the stash by passing the reference.

Stashing only what you want

Coming back to what we learned about last week, you can pass the -p flag to git stash to select individual hunk/lines that you would like to stash.

One last thing: By default, git only stashes files that are already tracked. If you also want the stash to take away any new files you can call git stash --include-untracked. Curiously, these new files will not be shown when you do a git stash show -p though and I’m not sure why. If you do know or have any more tips, let me know on twitter.

PS: When preparing this article I reread the man page for git stash. It is actually very well written. You should also give it a try and see if you can learn something new. Just execute man git-stash in the terminal of your choice and enjoy.