Sometimes I have a situation that I am working on some feature on my own branch and suddenly someone comes to me and says that something really important has to be fixed or improved on the main branch. Usually it happens when I am in the middle of very important changes which are not ready to be committed for some reason.

Normally, I would have to save the changes (diff) into some file, switch to the main branch abandoning any changes, apply the fix or improvement and commit it. Then I could switch back to my own branch, apply the changes (patch) from the file and continue the work. While it is not something difficult, it can be done much easier with Git.

Basic stash usage

In Git you can store your uncommitted changes into special buffer (let’s call it stash) and at the same time undo them on the working copy:

$ git stash save [optional_message]
Saved working directory and index state WIP on master: f3b0924 Fixed title of book.
HEAD is now at f3b0924 Fixed title of book.

After this the working copy will be clean and you can easily switch to a different branch and apply the fix. You can make command shorter by omitting optional message and save command because it is assumed by default.

Once you are done with bug fixing, you can switch back to the original branch and apply the saved changes again:

$ git stash pop

It will remove the last saved changes from the stash and apply them back into your working copy. After this you can continue the work as if nothing happened.

That’s all what you will need in most cases but if you want more control read on.

Advanced stash usage

Actually, stash works almost like stack. Whenever you save your changes into stash, they are put at the top of the stack and whenever you pop them, the ones from the top of the stack are removed and applied into your working copy. If you want, you can list the contents of the stack:

$ git stash list
stash@{0}: WIP on master: f3b0924 Fixed title of book.
stash@{1}: WIP on master: f3b0924 Fixed title of book.
stash@{2}: WIP on master: f3b0924 Fixed title of book.

The latest stash entries are at the top of the list. If you forget what given stash entry contains, you can peek its contents:

$ git show 'stash@{0}'

You may also pass -p option to see full diff.

I wrote that stash is almost like a stack. It is because you are not forced to apply only the latest entry but you can apply any entry even if it is in the middle of the stack. You just have to pass its name to apply subcommand:

$ git stash apply 'stash@{1}'

If you apply it this way, it will not be removed from the list and will have to be removed manually:

$ git stash drop 'stash@{1}'

You may also run:

$ git stash pop 'stash@{1}'

which will apply the changes and then immediately drop them.

Finally, it is also possible to remove all the stash entries if you don’t need them any more:

$ git stash clear

Selecting files to stash

Command git stash save (or in short git stash) stores only the modifications made to the files tracked by Git in the stash and leaves untracked files intact. This is usually what you expect but if you want you can also include untracked files into stash by adding -u option:

$ git stash save -u [optional_message]

Creating branch from stash

At some point you may decide that stash is not enough for your needs and you may want to create a new branch from it. It is very easy:

$ git stash branch <new-branch-name> [stash-id]

The command above creates a new branch named new-branch-name, checks it out and applies the changes from specified stash to it. If the stash was not specified, the latest one is used.

As a good rule of thumb, if your stash is older than few hours and you may still need it in the future, you should create a branch from it. It is because the entries in stash are very volatile while the branches are persistent and can be also pushed into remote repository.

Conclusion

Although stash functionality is nothing advanced or complicated, it is very convenient and useful when working on multiple branches and switching between them often. If you need more information, you can always check out git-stash manual page.