Git "Your Local Changes Would Be Overwritten by Merge" Without Losing Uncommitted Work

This error is Git protecting you — it refuses to merge in remote changes that would overwrite uncommitted local modifications, and the safe path forward always involves either committing or stashing your work first, never simply forcing through and losing it.

The Problem

Trying to pull or merge fails with:

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

You have genuine, uncommitted work in progress that you don't want to lose, but you also need to bring in the latest remote changes.

Why It Happens

Git detects that the incoming merge would need to modify a file you've also modified locally without committing those changes — rather than guessing how to reconcile this (which could silently discard your work), Git stops and asks you to explicitly decide what should happen to your uncommitted changes first. This is fundamentally a safety mechanism, not an obstacle to work around carelessly.

The Fix

If your uncommitted changes represent genuine, finished work you want to keep as part of your history, commit them first, then pull:

git add .
git commit -m "WIP: save progress before pulling"
git pull

After pulling, Git will either merge cleanly, or, if the same lines were also changed remotely, present you with a normal merge conflict to resolve — which is a much safer, more visible situation than the original error, since your work is now safely committed regardless of how the conflict resolution goes.

If you'd rather not create a commit yet (the changes aren't ready, or you want to keep your commit history cleaner), stash your changes instead, pull, then reapply them:

git stash
git pull
git stash pop

This temporarily sets your uncommitted changes aside, lets the pull proceed cleanly, and then reapplies your stashed changes on top of the newly updated code — if the stashed changes conflict with what was just pulled, you'll get a normal stash-apply conflict to resolve, with your original work still safely preserved in the stash until you explicitly resolve and drop it.

If you only want to keep uncommitted changes in specific files, not everything, stage and commit (or stash) selectively rather than all at once:

git add src/config.js
git commit -m "Save config changes before pull"
git pull

Avoid using git checkout -- . or git reset --hard as a way to "clear the error" unless you've genuinely confirmed you don't need the uncommitted changes at all — these commands discard uncommitted work permanently, with no stash or commit safety net, and are appropriate only when you're certain the local changes are disposable.

Still Not Working?

If you've committed or stashed your changes but the pull still reports conflicts or unexpected behavior, check whether you have both staged and unstaged changes to the same file, since a stash sometimes behaves subtly differently depending on the mix of staged versus unstaged modifications present when it's created:

git status

Reviewing the full output here, distinguishing between "Changes to be committed" and "Changes not staged for commit," clarifies exactly what state your working directory is in before deciding whether a commit or a stash is the more appropriate next step for your specific situation.

It's also worth understanding why this particular error appears specifically during a merge or pull rather than being a general Git restriction — Git is perfectly happy to have uncommitted changes sitting in your working directory indefinitely under normal circumstances. The error only surfaces at the specific moment an incoming merge would need to touch the same lines your uncommitted changes have already modified, since that's the one situation where Git genuinely cannot determine how to proceed without risking silently discarding something you might still need.

If this keeps happening repeatedly during your normal workflow, it's often a sign that your local branch diverges from the remote for longer stretches than ideal — pulling more frequently, even before you have a complete piece of work ready, tends to produce smaller, easier-to-manage divergences than letting local and remote drift apart for an extended period before finally trying to reconcile everything at once.