How to Use Git Stash Restore to Work Multiple Projects

Software development is rarely so kind as to be linear. It would be great if we could work continuously on a single feature without distractions, and only move to something else when the previous job was done. In reality, however, even single developers who work on a project don’t have the luxury of working on just one thing at a time. Let’s say, for example, that while you’re working on a new feature, a critical bug is revealed that needs fixing now. You have little choice but to put what you’re doing aside, and attend to the more urgent job. And this is where restoring a git stash is invaluable.

In this article, I’ll explain what git stash is, and how you can use it with either the “apply” or the “pop” command so that you can put away the changes you’re currently working on and return to it later. I’ll also explore the various philosophies behind using the “apply” command as opposed to the “pop” command after invoking git stash.

How to Use Git Stash and Restore It

For this example, I’ve created a git repo and modified the file “example.txt” by adding a new line with the text “Line 5”. So far, I haven’t yet committed the change, so the repo is still in the previous state. When I run “git status”, you can see that I have uncommitted changes:

Now let’s say an urgent task comes up and I need to “stash” my changes away for a while to work on them later. I use:

git stash

The system will take my uncommitted changes, store them safely away, and clean the working directory so that it no longer has any uncommitted changes. Here’s a screenshot:

As you can see, the “git status” after I issue the “git stash” command shows that there are no uncommitted changes. So I’m free to work on the new job as if whatever I was doing previously didn’t exist.

Seeing the Git Stash

If you use the git stash functionality a lot, you might forget how many things are stored in the stash and what you were working on before. To refresh your memory, you can use the following command:

git stash list

This will show an output like this:

Each stash you create is assigned a unique identifier, which looks like this:

stash@{0}

The “git stash list” command shows all the stashes you have. You can use the stash identifier to perform operations on a specific stash. Let’s say you don’t remember what the stashes contain, you can use the following command:

git stash show

For each stash, git will give you an overview of the changes. You can also request git to show you the details of a specific stash like this:

git stash show stash@{0}

The above only gives you an overview of the changes. If you want, you can delve deeper and see details using the following command:

git stash show -p stash@{0}

This gives the following output:

As you can see, it shows that the stash we just created has an uncommitted change that included the addition of a newline with the text “Line 5”. Using this command is the best way to quickly remind yourself of what exactly you were working on before you stashed away your changes.

Git Stashes are Invisible to the Commit History

An important point is that git stashes are not part of the official record of a git project. They’re a separate system entirely, and their absence from the git logs reflects their temporary nature. So feel free to use them without worrying about how they’ll look on the project reports.

Restoring a Git Stash

Let’s say you’ve finished working on the bug that distracted you from what you were working on before, and now it’s time to continue where you left off. You can use the following command to restore a specific stash:

git stash apply stash@{0}

Here, stash@{0} refers to the specific stash in the stack that you want to restore. We already saw how to retrieve the details of a specific stash so that you know what you’re restoring. When you run this, git will take the uncommitted changes that you stored in the specific stash, and apply them to your working directory. Here’s a screenshot of how it works in action:

You can see that before I restored the stash, the “example.txt” file contained only four lines. After I restore the stash with “apply”, it has five lines. This is because I had added an extra line to “example.txt” before restoring the stash. Now you can continue where you left off!

“Git Stash Restore” is Not a Valid Command

There appears to be some confusion regarding the proper way to restore a git stash. In particular, some sources claim that the way to do this is to use the command “git stash restore”. However, there is no such command in the documentation. The only way to restore a git stash in a non-destructive way is to use “git stash apply”. If in doubt, you can always consult the git-stash documentation to verify this.

Git Stash Apply is Non-Destructive

An important point to note is that when you apply a git stash to restore it, it retains the stash in the stack and memory. This means that you can apply the stash multiple times, though this is still local to the user that created the stash. If you want, you can share the git stash with other users in a couple of ways:

First, you can create a new branch with the changes in the stash using the following command:

git stash branch [branchname]

The above command will use the most recent stash to create a separate branch that will then be available to all users of the repository.

Second, the user can save the changes in the stash to a file like this:

git stash show -p > patchfile.diff

They could then share this “patchfile.dff” file with users so that they can see the changes.

Either way, applying a stash doesn’t destroy it. This has the benefit of being able to revert back to the patch in case something goes wrong. You can also restore the stash to multiple branches at the same time.

Git Stash Pop to Destroy the Stash

If you just want to restore the stash, “pop” the stack using the last in, first out sequence, and destroy the stash that was just applied, you can use the following command instead of “apply”:

git stash pop

Here’s what it looks like:

You can see that after the pop, the “git stash list” doesn’t return any results. The situation is now reverted to what it was before any stash was created in the first place. Generally, you should be careful about popping a stash because you lose everything, and since you probably haven’t worked on the previous project in a while, it’s easy for things to go wrong. It’s nice to have a backup with “git stash apply”, for a risk-free restoration.

But if you need to, you can use “git stash pop” to restore your working directly and remove the stash entirely.

I hope you found this quick tutorial on creating and restoring stashes useful!