Git is an amazingly vast tool for developers to manage development workflows, and it goes without saying that there's more to git than the basic commands that we use generally to collaborate on or contribute to team projects.
For instance, there might be a situation where you are mid-way in implementing a new feature for your product and suddenly a severe bug report pops in. Because of this, you have to keep aside your feature and focus on resolving the bug, but you can't commit the partial code and also can't throw away the progress until now. This highlights the need for a temporary space where you can store your partial changes and later on commit them. Well, guess what - git already has it solved for you via git stash.
This article requires basic knowledge of git.
What is a stash?
Git has an area called the stash where you can temporarily store a snapshot of your changes without committing them to the repository. It’s separate from the working directory, the staging area, or the repository. Furthermore, there can be more than one stash. The stashes could be understood as temporary shelves to put your data in until you're sure where to put it.
Note: The stash is local to your Git repository; stashes are not transferred to the server when you push.
Learn more about what is stash here.
This functionality is useful when you’ve made changes to a branch that you aren’t ready to commit to, but you need to switch to another branch without losing those changes.
Now, that we know what is a stash, let's see how to stash your work.
Stashing changes
To save your changes in the stash, you can use:
git stash
or
git stash save "optional message for yourself"
This will take your changes, record them internally, then clear the working directory. This allows you to switch to a new branch and develop other features without worrying about your partial commit messing anything up.
By default, running git stash will stash:
- changes that have been added to your index (staged changes)
- changes made to files that are currently tracked by Git (unstaged changes)
But it will not stash:
- new files in your working copy that have not yet been staged
- files that have been ignored
So the changes you want to stash need to be on tracked files. If you created a new file and try to stash your changes, you may get the error No local changes to save.
However, adding the -u option (or --include-untracked) tells git stash to also stash your untracked files, and you can include changes to ignored files as well by passing the -a option (or --all) when running git stash.
View Stashed Changes
To see what is in your stash, run the command:
git stash list
This returns a list of your saved snapshots in the format stash@{0}: BRANCH-STASHED-CHANGES-ARE-FOR: MESSAGE. The stash@{0} part is the name of the stash, and the number in the curly braces ({ }) is the index of that stash. If you have multiple changesets stashed, each one will have a different index. For example -
$ git stash list
stash@{0}: On main: add style to our site
stash@{1}: WIP on main: 5002d47 our new homepage
stash@{2}: WIP on main: 5002d47 our new homepage
By default, stashes are identified simply as a WIP – work in progress – on top of the branch and commit that you created the stash from.
Applying Stashed Changes
To retrieve and apply the changes out of the stash to the current branch, there are two options:
git stash apply STASH-NAME
The above command applies the changes and leaves a copy in the stash. This is useful if you want to apply the same stashed changes to multiple branches.
git stash pop STASH-NAME
The above command applies the changes and removes the files from the stash.
Note: If you skip the STASH_NAME in the above commands, git will basically perform the asked action with the latest stashed change.
Delete Stashed Changes
If you want to remove stashed changes without applying them, run the command:
git stash drop STASH-NAME
To clear the entire stash, run the command:
git stash clear
Conclusion
While git stash isn't exactly a common command, it can be a useful tool for making meaningful commits. Keep this in mind the next time you wish you could put something on hold and return to it later.
That’s all for this article. I hope that it would have helped you understand the basics of git stash. Please comment with your valuable suggestions and feedback.
In case you want to connect with me, follow the links below:
Top comments (9)
Great article it may be worth adding in an example of calling the
git stash applywith an actual name as it can be confusing syntax (it's not the message text for eg)It would look like
git stash apply stash@{0}Thank you so much for reading the article and sharing your valuable feedback. 😁
I will make the amends soon.
Nicely explained. A lot of the developers when starting out are not aware of this gift among many others that git offers. It can also be used to keep a compiled version of the changes that you made local to your machine to be able to run the project. This way you can reapply the stash to different branches and in different instances at will. You can even share it to a teammate by creating a patch from it. I have also used this to keep different spin off versions of a feature in the memory while working on the selected one in my main working tree. I was lucky that my then mentor introduced me to it early on. Now I introduce this to new developers from the get go. :)
Thank you so much for reading the article and sharing your valuable feedback. 😁
Great writeup.
Some of the downfalls to
git-stashinclude:To avoid these issues altogether, I wrote
git-shelf, which I recommend to colleagues and other industry professionals as an alternative solution to saving works-in-progress.Thank you so much for sharing this Ben, I read so many articles before compiling this one, but I never came across these points. I am grateful for these insights and the introduction to a new command
git-shelf.Great article, I loved it.
I know I sound like a grammar nazi, but I'd change "Now, that we know what is a stash" => "Now, that we know what a stash is". Also, it might be helpful for someone to know that "git stash" without any arguments does the same as "git stash save".
I really liked the article otherwise. It's concise, meaningful and complies with the standards
I Love this, I never really understood what exactly stash did until now. I'm going to start using it at it is meant for now.
Thank you so much 😁