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.