Git: 'Your Local Changes Would Be Overwritten by Merge' - How to Fix It

This error means you have uncommitted edits to a file, and the git pull you just ran would have to overwrite them to bring in the remote version. Git refuses rather than silently destroy your work. The fix is to get those edits out of the way first: either commit them, or stash them, pull, then restore them. Nothing is lost; Git stopped exactly so nothing would be.

Here is the message in full:

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

What the error actually means

When you run git pull, Git fetches the new commits from the remote and then merges them into your current branch (git pull does a merge under the hood, and you can choose whether that step merges or rebases). To merge, it needs to update the files in your working directory to match the incoming changes.

The problem: you have edited src/app.js but have not committed that edit. The remote also changed src/app.js. If Git went ahead with the merge, it would have to write the remote version over the top of your uncommitted edit, and your edit would be gone with no commit to recover it from. Git will not do that. It aborts the pull and leaves everything exactly as it was, so you can decide what to do.

The key word is uncommitted. Committed work is safe; Git can merge committed changes and tell you about any conflicts. It is the work sitting in your working directory (or staged in the staging area but not yet committed) that Git cannot reconcile automatically, so it stops.

Fix 1: commit your changes, then pull

If your edits are finished, or finished enough to record, the cleanest fix is to commit them. Once they are a real commit, Git can merge the remote work alongside yours.

git add src/app.js
git commit -m "Adjust app startup logging"
git pull

If your first pull then asks you to reconcile divergent branches, that is a separate prompt about how to combine your new commit with the remote ones; I cover it in if your first pull then asks you to reconcile divergent branches.

After the pull, one of two things happens:

• The changes do not overlap, and Git merges them cleanly.
• Both sides changed the same lines, and you get a merge conflict. That is normal and recoverable. Open the file, pick the right lines, and finish the merge. I cover the whole process in how to resolve merge conflicts in Git.

Use this fix when the work is in a committable state. Do not commit half-broken code just to clear the error; reach for the stash instead. If you already did commit prematurely, you can undo that commit before pulling and keep the edits in your working tree.

Fix 2: stash your changes, pull, then pop them back

If your edits are mid-flight and you are not ready to commit, git stash is the right tool. It tucks your uncommitted changes away on a stack, leaving you a clean working directory, lets the pull go through, and then puts your changes back on top.

git stash
git pull
git stash pop

git stash saves both staged and unstaged changes and reverts your working tree to match the last commit. The pull now has nothing to overwrite, so it succeeds. git stash pop reapplies your saved changes on top of the freshly pulled code and drops them from the stash.

If the pulled code touched the same lines you had stashed, git stash pop can raise its own conflict. Same drill as a merge conflict: edit the file, resolve, and you are done. There is a full walkthrough of the stash workflow in how to use git stash.

Which fix should I use?

Commit when the work is a real unit of history. Stash when you just need a clean tree for a moment and want the same edits back afterward. They are not competing tools; they solve slightly different versions of the same "clear the working tree" problem.

Fix 3: you actually want to throw the edits away

Sometimes the uncommitted changes are junk: a debug console.log, a config tweak you no longer want, an accidental edit. If you are certain you do not need them, discard them and the error disappears because there is nothing left to overwrite.

git checkout -- src/app.js
git pull

On Git 2.23 and newer you can use the clearer git restore:

git restore src/app.js
git pull

This is destructive: the uncommitted edit is gone for good, with no stash to recover it from. Be sure before you run it. If you want the full set of discard options, including resetting the whole working tree, see how to discard local changes in Git.

Why does Git stop instead of merging anyway?

This is Git protecting you. Committed history is recoverable; you can almost always get a committed state back, even after a bad reset, using the reflog. Uncommitted working-directory edits have no such safety net. They exist only as the current bytes on disk. If Git overwrote them during a merge, there would be no record of them anywhere, and no command could bring them back.

So Git draws a hard line: it will never clobber uncommitted changes to satisfy a merge. The abort is the feature, not the failure. Once you understand that, the error stops being alarming and becomes a simple prompt: deal with the working tree first, then pull.

Avoiding the error in the first place

A few habits keep this from showing up:

• Commit or stash before you pull. Make a clean working tree your default state before syncing with the remote. The cleaner your tree, the less friction every pull has.
• Understand what a pull does. git pull is a fetch plus a merge in one step. If you fetch first and inspect the incoming changes, you keep more control over when the merge happens. I lay out the distinction in git pull vs git fetch.
• Keep generated and local-only files out of the repo. Build artifacts, editor settings, and local config that you keep editing are a constant source of "would be overwritten" friction. A good .gitignore stops them from being tracked at all.
• Commit in small, frequent units. The longer uncommitted work sits in your tree, the more likely a remote change collides with it. Small commits keep the window narrow.

New to Git and want the foundations behind all of this (the working tree, the staging area, commits, and remotes)? Start with Git for beginners, and read the staging area explained for what "committed" versus "uncommitted" really means.

FAQ