Git Stash - A Quick Primer

This was originally posted on my blog and is being re-posted here for reach. Please share it and let me know if you liked it or have any questions!

Interruptions are fairly common when working on a large project. Heck they’re even common for me when I’m working by myself. For me these interruptions often come in the form of: Please switch to working on this other thing. What happens when this comes at a point that I'm not ready to commit? git stash to the rescue! Just as the name indicates git stash allows changes to be stashed away for later use. Once the changes have been saved the source tree is returned to the state of the latest commit. At this point I can work on the other set of necessary changes. When I'm ready to come back to the changes I stashed I can simply pull them out of the stash using git stash pop and continue my work.

TL;DR - What are the commands I need to know for git stash?

• git stash - This will store your current changes and clean your working directory. This is the same as git stash push
• git stash -m <message> - Same as above but attach the message to the stash instead of the commit ID
• git stash list - Show the list of stashes for this repository
• git stash apply <stash id> - Apply the changes from the stash and leave the stash in the list of stashes.
• git stash pop <stash id> - Same as apply but remove the stash from the list
• git stash drop <stash id> - Delete the stash from the list

While there are more options available for git stash this list contains the majority of what is needed for normal usage. The documentation shows the full list of options for git stash.

Let's see some examples

I've created a simple repository with a single file to show some examples of how to use git stash. Here I've got a change to the file ready to be staged or stashed.

The next screen shot shows using git stash without any arguments. You'll see that the default comment will be a portion of the commit id and the commit message.

This is the output of git stash list showing a single stash with its stash id and the default comment.

If only the previous commit message is present it doesn't reflect the actual changes that were made and stashed. It would be better to have a message that reflects the changes made and the reason for stashing them. Here we can see an example of stashing a change with a message.

Now we can see there is a second commit and that it has been pushed on to the top of the list. Notice that our initial commit that was originally stash@{0} is now stash@{1}. The change we just stashed has taken its place in position 0.

If you were to run git stash pop you would get the changes that we just committed. What if, however you'd like to start working on a set of changes that aren't at the top of the list? That's as simple as calling git stash pop <id>. In this case I've provided 1 as the ID. You can see at the bottom of the git output that it says it has dropped the ref to stash@{1}.

Running git stash list we can see that there is only one change remaining in the list. The initial change that we stashed has been removed from the list since we popped the first change.

Here we use the push option along with a message. The listing shows both changes are stored again.

Now we'll use the apply option to show that we can apply a stash without deleting it from the list of stashes.

To wrap things up let's show what happens when we want to delete a specific stash.

Conclusion

git stash is a handy way to save a set of changes you're working on. There are, of course, other ways to handle saving your changes (i.e. branching). My usual use case for git stash is when I need to merge a set of changes from another branch and am not ready to commit what I'm currently working on.

Let me know if this post was helpful and/or if you have questions on this topic. For more reading on git check out my post on git merge strategies.