Sometimes, when we are making changes to a project in git, we realise we suddenly need to revert back to the last clean working directory version of our project - that meaning the version with no local changes applied. For example, suppose you had recently cloned or pulled a version of a project to your local computer, and had made some local changes to three files. To revert your project to the version you cloned or pulled, you can run the following command:
git stash
This will both save your changes, by stashing them somewhere safe, and also revert back to a clean version of your project which you can then go about saving, editing, or doing whatever you like with. Most people are aware that they can do this using git stash, but there are a few other things git stash lets us do too. When it comes to git stash, there are a few really useful commands you should be aware of:
git stash listgit stash showgit stash applygit stash popgit stash pushgit stash cleargit stash drop
Listing or showing all git stash changes
While we can easily use git stash to clean up our working tree, we can also see all stashes using the following command:
git stash list
Interestingly, this will show multiple stashes that have occurred in the past. Git therefore stores all stashes, in case you want to retrieve them in the future. For example, here is a project with many stashes, after running git stash list:
stash@{0}: WIP on master: abf89a3 feat-ui: updated look and feel
stash@{1}: WIP on master: 39329d5 feat-ui: Updated CSS Quiz Button
stash@{2}: WIP on master: 46bc7aa feat-ui: Bug fix on article API
stash@{3}: WIP on master: 5dafc53 feat-ui: Fixed issue with secondary-navigation overflow
All stashes are stored in your ref/stash file, within the .git folder. A more detailed view of the most recent git stash can also be viewed with git stash show:
common.js | 405 +--------------------------------------------------------
public/quiz.js | 267 +------------------------------------
While this is fine for some, an even more detailed view including code level changes can be shown by running the following command:
git stash show -p
git stash show also has a few other useful options:
-
-uor--include-untracked, to show untracked files ingit showthat are in the stash, i.e.git stash show -u -
--only-untracked, to show only untracked files ingit show, that are in the stash, i.e.git stash show --only-untracked
Recovering a git stash with apply or pop
While knowing what has been stashed is in itself useful, it is also quite useful to be able to recover a stash. To recover your most recent stash of code, you can run the following command:
git stash apply
If you're like me, though, and you have tonnes of unused stashes, sometimes it's also useful to recover a previous stash, such as stash@{3}, or stash@{25}, like in the list we saw before. In these cases, we simply list the number of the stash after the command. For example, to recover stash@{25}, we would run the following:
git stash apply 25
As you'd expect, if you've modified files, and then try to run git stash apply on top, you may run into merge conflicts. So make sure those are taken care of before running this command.
git stash apply versus git stash pop
Just now, we've used git stash apply to recover a stash of code. This will take our stashed code, and apply it on top of our working tree. It will also leave the stashed copy of your code still in your list of stashed code - so you won't lose it. If you want to recover stashed code, and remove that stash from your stash list, you have to use pop instead:
git stash pop
Turning your stash into a branch
Another useful thing which git stash does which is under-utilised is that it allows us to make a new branch from our stashed code. If you have some stashed code, you can take your current project with the changes in it, apply your stashed code on top, and then make a new branch named as you like. For example, the following will create a branch called new-code:
git stash branch new-code
Other ways to save your stash and git stash push
While we've covered how you can use git stash to stash the most recent code, you may also see the following command in the wild:
git stash push
This command is actually the same as git stash, but can be a little confusing if you aren't aware of that. As well as this, git stash and git stash push come with a number of useful options, should you wish to use them:
-
-aor--all, will save the whole working tree to the stash, i.e.git stash push -a -
-Sor--staged, will save only staged changes added usinggit add, i.e.git stash push -S -
-por--patch, will allow you to go through each change and selectively decide whether you want to stash it, i.e.git stash -p -
-uor--include-untracked, to save all untracked files along with your stash, i.e.git stash push -u
Supressing messages with git stash
As a side note, at this point it makes sense to mention that pretty much all git stash commands come with the -q option, which suppresses any messages or errors:
git stash apply -q
Removing your stash
Finally, sometimes you want to remove your entire stash. This is a little dangerous, so use it with caution, but if you want to, all you have to run is:
git stash clear
If you don't want to do something like that, but still want to remove a specific stashed item, you can run git stash drop to drop the most recently stashed entry, or git stash drop 25 to drop the stash listed as stash@{25} in your git stash list result.
Top comments (1)
Nice article. I recently learned that you can also stash files individually, e.g.
git stash push -- CHANGELOG.md ..., which I find incredibly useful.