How to Fix "Your Local Changes to the Following Files Would Be Overwritten by Merge"

Git refuses to merge or pull because you have uncommitted local edits that conflict with incoming changes. This is a safety check — Git won't silently discard work you haven't committed yet.

The Problem

You run git pull or git merge with uncommitted edits in your working directory, and Git stops before touching anything:

$ git pull origin main
error: Your local changes to the following files would be overwritten by merge:
	src/config.js
Please commit your changes or stash them before you merge.
Aborting

The same message appears with git checkout when switching branches:

$ git checkout develop
error: Your local changes to the following files would be overwritten by checkout:
	src/config.js
Please commit your changes or stash them before you switch branches.
Aborting

Why It Happens

Git compares the files you've modified against what the incoming merge, pull, or checkout would need to write to those same files. If both touch the same lines (or Git can't be sure they don't), it refuses rather than risk silently deleting your edits. Common triggers:

• You edited a config or code file locally without committing, and a teammate changed the same file upstream.
• You're switching branches and the target branch has a different version of a file you've modified but not committed.
• You have leftover debug edits (console logs, hardcoded test values) that were never meant to be committed but are still sitting in the working tree.

The Fix

First, see exactly what's changed and uncommitted:

git status
git diff src/config.js

If the changes are worth keeping, the safest option is to stash them temporarily:

git stash push -m "wip: config tweaks before pull"

Now the working directory is clean, so the merge or pull can proceed:

git pull origin main

Once that succeeds, bring your changes back:

git stash pop

If Git reports a conflict while popping the stash, resolve it manually in the listed files, then:

git add src/config.js
git stash drop

Alternatively, if the changes are actually complete and ready, just commit them first instead of stashing:

git add src/config.js
git commit -m "chore: update config defaults"
git pull origin main

If the local edits were accidental and worthless (leftover debug code, for example), discard them entirely instead:

git checkout -- src/config.js
git pull origin main

For newer Git versions, the equivalent discard command is:

git restore src/config.js

Still Not Working?

If git stash pop creates conflicts you don't want to deal with right now, you can leave the stash saved and keep working — it isn't lost:

git stash list

This lists every stash you've saved, and you can apply a specific one later with git stash apply stash@{0} once you're ready to merge it in manually, without deleting it from the stash list the way pop would.

It's worth understanding why Git is this cautious in the first place. Unlike a committed change, an uncommitted edit only exists in your working directory — it has no history, no hash, no way to be recovered through git reflog if it's overwritten. Once it's gone, it's genuinely gone, which is exactly why Git refuses to proceed rather than guessing what you meant. This is different from a merge conflict on committed changes, where both versions are preserved in history and Git can show you exactly what each side changed.

If this error shows up frequently during routine git pull operations, it's often a sign you're editing files directly on a shared branch instead of working in a feature branch. Consider adjusting your workflow so uncommitted experiments happen on a dedicated branch:

git checkout -b wip/config-tweaks
git add src/config.js
git commit -m "wip: experimenting with config"

That way, pulling updates to main never collides with in-progress work, since your experimental changes live safely on their own branch until you're ready to merge them back in deliberately.