Commanding the use of git stash is an necessary skill for any developer looking to efficiently manage their work-in-progress changes on Git.
In this comprehensive guide, we will research deep into the intricacies of git stash, exploring its core concepts, advanced usage, practical examples, and best practices.
By the end of this guide, you will have a solid understanding of how to leverage the git stash command effectively in your version control workflow.

What is stash ?

Before learning about how to use git stash command, it is necessary to understand the meaning of stash.
When you make local changes to some files, git considers those files as dirty.
Now, suppose you want to
1. Change(checkout another) branch.
2. Fix some urgent bug.
3. Pull latest branch changes.
And incoming changes are in the same files that you have modified, resulting in a conflict.

In this case, Git would not allow you to perform any of the above operations.
As a result, you are left with the following options
1. Checkout remote branch somewhere else and then do the changes.
2. Revert all your local changes.
3. Copy your local files with changes, overwrite them with remote files.

All these options seem to be workarounds and would be a waste of time.
Git provides you with a solution in the form of a stash.
Stash is an operation which saves all your local file changes into another area making your local working directory clean so that you can easily pull remote changes or switch branches.

How to git stash ?

To perform a stash operation with git, use the below command

git stash

This command will stash both staged and unstaged changes, allowing you to continue working on a clean slate without losing your progress.
Any changes you have made will be stored in the stash area for later retrieval if needed.

When you perform changes in your local files and they are ready for commit, you move them to the staging area with git add.
Before git add, the files are in unstaged area.

Adding stash message

One useful feature of git stash is the ability to add message to your stashes, providing context and clarity to your stored changes.
This can help you differentiate between stashes when managing multiple sets of alterations.
Names serve as labels for your stashes, making it easier to identify the purpose of each saved state.

To provide a message to stash, use -m flag followed with the message as shown below

git stash -m "Added loop in HTML template"

git stash push

push option with stash command is also used to create a stash.
Simply calling git stash is the same as calling git stash push.

Stash Untracked and Ignored Files

Untracked files are those which are present on your local working directory but not in local or remote git repositories.
These are the files which have never been committed or pushed.
To stash those files use -u flag

git stash -u

This command will stash all changes, including untracked and ignored files, ensuring that nothing is lost in the process.
Stashing untracked and ignored files can help you keep your working directory clean and organized.

Managing Multiple Stash Entries

Each time you use git stash command, git will create a new stash entry with all the files having local changes at that instant.
These stash entries are added to a list and so, it is possible that you have multiple stashes on the system.

To view all the stashes, use below command

git stash list

This command will display a list of all stash entries, allowing you to keep track of your stashed changes and effectively manage multiple stash entries at once.
The stash entries will be named as stash@{index}, with index starting from 0.

Stashing with Keeping the Index

As stated earlier, git stash command creates a new stash at a new index.
So, if you have 4 stashes already and you execute git stash command, it will create a new stash at 5th index.
git stash command provides an option to keep the changes in the top index while creating a stash.
This can be useful when you want to temporarily set aside changes that are already staged for the next commit.
To stash changes while keeping the index, you can use the following command:

git stash --keep-index

Applying git stash

Till now, we looked at various options to create a stash.
Now, let’s learn how to apply or restore changes in a stash using following command

git stash apply

This will apply the changes stored in the topmost stash.

This command not only applies the most recent stash but also keeps the changes in your stash list.
This means that even after the changes in the stash are applied, the stash will be preserved.

It is incredibly useful for when you want to keep the changes in your stash for future reference while applying them to your current working state.

git stash pop

pop option is also used to apply a stash.
The difference between apply and pop is that pop will remove the stash after applying it while apply keeps it.
Syntax of pop is

git stash pop

pop will also act on the topmost stash or the stash having maximum index.

Delete stash

You might want to delete or remove a stash, probably because you have applied it with git stash apply or it was created by mistake or it is no longer required.

A stash can be removed without affecting your current local changes with drop option as shown below

git stash drop

This will remove the topmost stash or the stash at maximum index.

Show stash contents

Many times, we need to know the files that were added in a stash, the files that were modified at the time the stash was created.
This can be done with show option as below

git stash show

This will list all the files and the changes inside them in the topmost stash as below

$ git stash show
build.gradle | 1 +
1 file changed, 1 insertion(+)

Navigating Through Stash Entries

There might be a case that you have multiple stashes and you want to apply or remove a particular stash.
You can do that be referring the stash by its index as stash@{index}.

All the previously discussed git stash options such as apply, pop, drop, show can be used with this syntax as shown below

# apply second stash
git stash apply stash@{1}

# pop 5th stash
git stash pop stash@{4}

# remove third stash
git stash drop stash@{2}

# show first stash
git stash drop stash@{0}

Clearing stashes

If your stash list grows unwieldy over time, it’s advisable to clean up old stashes to maintain a tidy repository and prevent clutter.

One option is to use git stash drop command. But this will remove 1 stash at a time and is not feasible if you have many stashes.

Another method to remove all stashes at once is clear option as below

# Remove specific stashes based on their index
git stash drop stash@{2}

# Clear all stashes at once
git stash clear

Creating branch from stash

You can also create a new branch from a stash with its branch option as shown below

# create branch from lastest stash
git stash branch <branchname>

# create branch from second stash
git stash branch <branchname> stash@{1}

This will create a branch from the commit from which the stash was created.
It will also apply the changes in the stash on the new branch and then drop the stash.

To wrap up

This guide to git stash command has provided a comprehensive understanding of how to effectively utilize this powerful feature in Git for managing changes in your projects.
By exploring the core concepts, learning about the git stash command, you have gained the knowledge and skills needed to leverage git stash efficiently.