Play video

What are Git stash merge conflicts?

Git stash allows you to save a draft of your in-progress changes and revert your working directory back to a clean slate. If stashed changes are applied ontop of new commits or other in-progress changes, there’s a chance for merge conflicts to arise.

If stash fails with a merge conflict, the error message will tell you that “git stash needs merge” or something similar to the messages below:

CONFLICT (content): Merge conflict

or this

error: Your local changes to the following files would be overwritten by merge. Please commit your changes or stash them before you merge

Note: This guide is a companion document to the video above. Merge conflicts are easier to understand when understood visually, so I recommend watching the video first.

How to fix a git stash needs merge error

Apply the stash

git stash pop <stash-index>

Note: If you have un-staged changes in your working directory, ensure you stage them by running git add . before running git stash pop. If unstaged files have merge conflicts, Git will abort the stash operation. You’ll know this happened if the message you receive contains the phrase “error: Your local changes to the following files would be overwritten by merge”. You’ll know you’ve entered the merge workflow when you see this phrase: “CONFLICT (content): Merge conflict”.

When stash fails with a merge conflict note the file(s) that failed the merge. Open each of the failed files in a text editor of your choice and manually resolve the conflicts. After saving the files, stage them:

git add <file(s)-that-failed-merge>

At this point, you’ve resolved the conflicts and can continue development; however, you may want to consider commiting your changes before moving on for future readabily.

Lastly, when git stash pop fails with merge conflicts, the stash entry isn’t removed from the stash list. After fixing the merge conflict, remove the stash entry by running:

git stash drop <stash-index>

Workarounds

If you’d rather not fix a merge conflict right away, you can pop you changes out onto a new branch instead of the branch on which the stash was created:

git stash branch <branch-name> <stash-index>

This will allow you to continue development on a separate branch, then use merge/rebase to bring those branched changes back onto mainline at your leasure.