Git Stash Basics

Do you ever see this?

1
2
3
4
5
error: Your local changes to the following files would be overwritten by checkout:
  file.txt
  dir/file2.txt
Please, commit your changes or stash them before you can switch branches.
Aborting

This occurs when you run git pull, and your current branch has changes. git aborts the pull, because doing so would overwrite the changes in your current branch.

So what do you do?

The work you’ve done in file.txt and file2.txt, is important, and you don’t want to lose them.

git stash is a great way to save your work without running git commit.

NOTE: git stash is not meant to replace git commit. When you have stable changes you’ve made to your code, you should use git commit.

I’ve found git stash particularly useful when my team has pushed important updates in to the master branch when I was in the middle of something. Normally, I would git checkout master then git pull. But since I have made some changes that may or may not be fully functional, I run git stash to save my current progress so that I don’t introduce and unstable commit.

Basic Stash

1
git stash

This will stash all files that are unstaged or untracked.

Where does it go exactly?

List your stashes

1
git stash list

Unsurprisingly, this will show you a list of all of your stashes.

Note that I said “stashes.” So you can have multiple stashes? The answer is yes!

The next time you run git stash, that stash will pushed to the top of your git stash stack.

Looking inside a stash

Time passes. You forgot what you stashed. git stash list only shows you a list of stashes. What if you want to look inside of a stash?

1
git stash show -p stash@{0}

The last argument stash@{0} represents the name of the stash. This comes from git list. The -p option will run git diff on each file that is in the stash.

Retrieve a Stash

Ok, so you’ve stashed your important files. Now it’s time to get them back.

There’s more than one way to retrieve a stash. Let’s start with the simple one.

Apply

1
git stash apply stash@{0}

Again, stash@{0} is the name of the stash you want to apply. You can get it from the git list.

Pop

1
git stash pop stash@{0}

pop works just like apply. The only difference is it also drops (aka deletes) the stash from the stack.

Given the frequency with which I use git stash, I prefer pop over apply, because your git stash list will get very longer over time. Wouldn’t it suck to run git stash show every time I want to remind myself of a stashes contents? I would much prefer to find my stash from a smaller list than a bigger one.

When I pop, I’m pretty sure the files I work on will eventually lead to a commit. If not, I can always git stash again!

Choosing what files to stash

Ok, so git stash is great when you want to stash everything, but what if you want to stash just one file? What about a handful of files? I’m going to show you 2 different ways.

Stash with -patch

1
git stash -p

If you run git stash -p, will run in an interactive mode. Like a software wizard, git stash -p will show you an unstaged file (showing its git diff) and then ask you if you want to stash this file. This process repeats for all unstaged files.

The -p is short for -patch. I have no why it was named this way. But I find it easier to remember -p if I think of the word “picky.”

Stash what’s not staged

Another approach is to stage the files you don’t want to stash. Then stash everything else.

First, git add the files you want to stage for the commit.

1
2
git add file_you_want_to_commit.txt
git add file_you_want_to_commit2.txt

Then, git stash --keep-index. All unstaged files will get stashed. --keep-index is basically saying, “do not stash my staged files.”