GIT: How to Save Your Changes Temporarily

There are lots of situations where a clean working copy is recommended or even required: when merging branches, when pulling from a remote, or simply when checking out a different branch.

The "git stash" command can help you to (temporarily but safely) store your uncommitted local changes - and leave you with a clean working copy.

git stash: a Clipboard for Your Changes

Let's say you currently have a couple of local modifications:

$ git status
  modified:   index.php
  modified:   css/styles.css

If you have to switch context - e.g. because you need to work on an urgent bug - you need to get these changes out of the way. You shouldn't just commit them, of course, because it's unfinished work.

This is where "git stash" comes in handy:

$ git stash
Saved working directory and index state WIP on master:
   2dfe283 Implement the new login box
HEAD is now at 2dfe283 Implement the new login box

Your working copy is now clean: all uncommitted local changes have been saved on this kind of "clipboard" that Git's Stash represents. You're ready to start your new task (for example by pulling changes from remote or simply switching branches).

Continuing Where You Left Off

As already mentioned, Git's Stash is meant as a temporary storage. When you're ready to continue where you left off, you can restore the saved state easily:

$ git stash pop

The "pop" flag will reapply the last saved state and, at the same time, delete its representation on the Stash (in other words: it does the clean-up for you).

GIT: Saving Changes Temporarily

A commit wraps up changes and saves them permanently in the repository. However, in your day-to-day work, there are a lot of situations where you only want to save your local changes temporarily. For example, imagine you're in the middle of some changes for feature X when an important bug report comes in. Your local changes don't belong to the bugfix you're going to make. You have to get rid of them (temporarily, without losing them!) and continue working on them later.

Situations like this one happen all the time: you have some local changes in your working copy that you can't commit right now - and you want or need to start working on something else. To get these changes out of your way and have a "clean" working copy, Git's "Stash" feature comes in handy.

CONCEPT

The Stash

Think of the Stash as a clipboard on steroids: it takes all the changes in your working copy and saves them for you on a new clipboard. You're left with a clean working copy, i.e. you have no more local changes.

Later, at any time, you can restore the changes from that clipboard in your working copy - and continue working where you left off.

You can create as many Stashes as you want - you're not limited to storing only one set of changes. Also, a Stash is not bound to the branch where you created it: when you restore it, the changes will be applied to your current HEAD branch, whichever this may be.

Let's stash away these local changes so we have a clean working copy before starting to work on our new feature:

$ git stash
Saved working directory and index state WIP on master: 
   2dfe283 Implement the new login box
HEAD is now at 2dfe283 Implement the new login box

$ git status
# On branch master
nothing to commit (working directory clean)

The local changes in "imprint.html" are now safely stored on a clipboard, ready to be restored any time we want to continue working on them.

You can easily get an overview of your current Stashes:

$ git stash list
stash@{0}: WIP on master: 2d6e283 Implement the new login box

The newest Stash will always be at the top of the list, named "stash@{0}". Older Stashes have higher numbers.

When you're ready to restore a saved Stash, you have two options:

• (a) Calling "git stash pop" will apply the newest Stash and clear it from your Stash clipboard.
• (b) Calling "git stash apply <stashname>" will also apply the specified Stash, but it will remain saved. You can delete it later via "git stash drop <stashname>".

You can choose to not specify the Stash when using any of these commands. Then, Git will simply take the newest Stash (always "stash@{0}").

CONCEPT

When to Stash

Stashing helps you get a clean working copy. While this can be helpful in many situations, it's strongly recommended...

• ...before checking out a different branch.
• ...before pulling remote changes.
• ...before merging or rebasing a branch.

Finally, it's time to get our hands dirty with our new feature!

GIT: Stashing changes in Git

22.1. The git stash command

Git provides the git stash command which allows you to record the current state of the working directory and the staging area and to revert to the last committed revision.

This allows you to pull in the latest changes or to develop an urgent fix. Afterwards you can restore the stashed changes, which will reapply the changes to the current version of the source code.

22.2. When to use git stash

In general using the stash command should be the exception in using Git. Typically, you would create new branches for new features and switch between branches. You can also commit frequently in your local Git repository and use interactive rebase to combine these commits later before pushing them to another Git repository.

Even if you prefer not to use branches, you can avoid using the git stash command. In this case you commit the changes you want to put aside and amend the commit with the next commit. If you use the approach of creating a commit, you typically put a marker in the commit message to mark it as a draft, e.g., "[DRAFT] implement feature x".

22.3. Example: Using the git stash command

The following commands will save a stash and reapply them after some changes.

# create a stash with uncommitted changes
git stash

# do changes to the source, e.g., by pulling
# new changes from a remote repo

# afterwards, re-apply the stashed changes
# and delete the stash from the list of stashes
git stash pop

It is also possible to keep a list of stashes.

# create a stash with uncommitted changes
git stash save

# see the list of available stashes
git stash list
# result might be something like:
stash@{0}: WIP on master: 273e4a0 Resize issue in Dialog
stash@{1}: WIP on master: 273e4b0 Silly typo in Classname
stash@{2}: WIP on master: 273e4c0 Silly typo in Javadoc

# you can use the ID to apply a stash
git stash apply stash@{0}

# or apply the latest stash and delete it afterwards
git stash pop

# you can also remove a stashed change
# without applying it
git stash drop stash@{0}

# or delete all stashes
git stash clear

22.4. Create a branch from a stash

You can also create a branch for your stash if you want to continue to work on the stashed changes in a branch. This can be done with the following command.

# create a new branch from your stack and
# switch to it
git stash branch newbranchforstash