How to use Git stash

The git stash command temporarily shelves (or stashes) changes made to your working directory, reverting its state to match the HEAD. This is particularly useful when you need to quickly switch contexts without committing incomplete work, or need to pull in relevant upstream changes that would otherwise conflict with your local state.

This guide will explain the basics of how to use git stash and its various options to manage your stashes effectively.

Creating a stash

To stash your current changes run:

git stash

By default this will create an entry stored in refs/stash with the title “WIP on <your_branch_name***>”***, but you can also customize this message to make it easier to identify individual stash entries:

git stash -m "Your custom message here"

Listing all stashes

To view all your stashed changes run:

git stash list

Each stash is given an index, starting from stash@{0} for the most recent entry, in addition to the message referenced in the previous section.

Applying a stash

To apply the changes from the most recent stash run:

git stash apply

For applying changes from a specific stash, use its index:

git stash apply stash@{n}

Replace n with the index of the stash you want to apply.

git stash pop vs. git stash apply

• Pop: git stash pop applies the most recent stash and then removes it from the stash list.

• Apply: git stash apply applies the stash but keeps it in the stash list.

Applying stash to a different branch

To apply a stash to a branch different than the one you currently have checked out:

1. Check out the branch you want to apply the stash to.

2. Use git stash apply or git stash pop as needed.

Creating a branch from a stash

If the changes in a stash are extensive or complex, you might want to create a new branch for them:

git stash branch your_new_branch_name stash@{n}

This command creates a new branch, checks it out, and applies the specified stash. The stash is then dropped if applied successfully.

Stashing untracked files

By default, git stash does not include untracked files. To include them run:

git stash push -u

Or:

git stash push --include-untracked

Cleaning up stashes

To remove a specific stash:

git stash drop stash@{n}

To clear all stashes in the stack run:

git stash clear

Stashing specific files

git stash does not support stashing specific files directly. However, you can achieve this by selectively adding files to the staging area and then using git stash --keep-index to stash everything else:

1. Add specific files to the staging area with git add.

2. Run git stash --keep-index to stash changes not in the staging area.

3. Optionally, you can stash the staged changes as well by running git stash again.

Troubleshooting git stash

Aborting an in-progress stash pop/apply

When running git stash pop or git stash apply Git will attempt to apply the stashed changes directly on top of the current commit. This may result in merge conflicts. In the case you want to abort a stash that’s in progress instead of resolving the conflicts manually, run:

git reset --merge

This will discard all changes in the working directory but will not erase the stash.

• Stash apply error: If you encounter errors when applying a stash, it might be due to conflicts. Resolve the conflicts manually and then commit the changes, or abort the stash using the step above.

• Not a valid reference: Ensure you are referencing the stash correctly, e.g., stash@{n}.

Use cases

git stash is useful in various scenarios, such as:

• Switching branches to work on a different task without committing incomplete work.

• Keeping a clean working directory when pulling updates from the remote repository.

• Experimenting with changes that you may want to discard later.

For additional reading please see the official git documentation on git stash.