commit your changes or stash them before you can merge

Git’s “commit your changes or stash them” prevents merging when your working directory has uncommitted changes Git can’t safely navigate around.

What It Means

This error is similar to “Your local changes would be overwritten,” but slightly different: Git refuses the merge or pull because one or more uncommitted files would be overwritten or would prevent the operation from completing cleanly. Git’s priority is protecting your uncommitted work — it won’t let you proceed until you either save it (commit), temporarily set it aside (stash), or remove it (discard). The error message explicitly lists the files that are blocking the operation.

Why It Happens

• You have dirty files in your working directory and tried to merge/pull.
• A file you modified locally is also modified in the incoming branch.
• You ran git rebase or git checkout with uncommitted changes.
• You have staged (but not committed) changes that conflict with the merge.
• Git’s index (staging area) is out of sync with your working tree.
• A Git hook (pre-merge, pre-rebase) detected uncommitted changes.

How to Fix It

Step 1: Use git stash (fastest option)

Save changes, merge, then restore:

git stash
git pull
git stash pop

Check what you’re stashing first:

git stash list
git stash show -p stash@{0}

Step 2: Commit your changes

If your work is in a good state:

git commit -m "Save progress before merge"
git pull

Step 3: Discard changes (if you don’t need them)

# Discard working tree changes
git checkout -- file1.rb file2.rb

# Or discard everything
git reset --hard HEAD

Step 4: Move changes to a new branch

For complex work-in-progress:

git checkout -b feature/wip
git add .
git commit -m "WIP"
git checkout main
git pull
# Continue working on main or merge wip later

Step 5: Check exactly what’s blocking

git status
# Shows modified files
git diff --name-only
# Lists only filenames with changes

Check if the blocking files are actually important:

git diff filename.rb
# Review changes before deciding to stash or discard

Step 6: Use git worktree for parallel work

If you frequently need to work on multiple branches simultaneously:

git worktree add ../project-main main
# Work in ../project-main while keeping your current branch intact