Fix: Git "Your local changes would be overwritten by merge"

The Error

You run git pull or git merge and get:

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

Or during git checkout:

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

Or during git rebase:

error: cannot rebase: You have unstaged changes.
Please commit or stash them.

Git is protecting your work. You have uncommitted changes in files that the incoming merge, checkout, or rebase would also modify. Git refuses to proceed because it would overwrite your local edits.

Why This Happens

Git needs to modify files in your working directory to complete the operation (merge, pull, checkout, or rebase). If those files have uncommitted changes, Git has a conflict: your local edits versus the incoming changes. Rather than silently losing your work, Git aborts the operation.

The check happens before any merging starts, by comparing the index against both HEAD and the target tree. If any file is dirty (different in your working tree from the index) and the operation would change that file in the target, Git refuses. This is why the error can show up even when your edit and the incoming change touch entirely different lines of the same file — Git is conservative, not smart. It does not attempt a three-way merge against an uncommitted state, because doing so could silently lose your work if the merge algorithm chose the wrong side.

This happens in these scenarios:

• You edited files and then ran git pull before committing.
• You are switching branches that have different versions of files you modified.
• You are rebasing onto a branch that touches the same files.
• An IDE or build tool modified files automatically (like package-lock.json, .DS_Store, or generated configs).
• A line-ending or filemode change has marked files as modified even though the visible content is identical.

The fix depends on whether you want to keep your changes, discard them, or save them temporarily. Pick the action first, then pick the command — most of the time you want option one, and stashing is the safest path.

In Production: Incident Lens

This is primarily a developer-side error rather than a production runtime failure, but it shows up in production in one specific scenario: hotfix deploys. The flow is: an on-call engineer SSHes (or shells into a build agent) to deploy a hotfix, runs git pull origin main on the deploy host, sees this error because the build agent had local changes from a previous deploy script that wrote a config file, and either force-discards the change (losing important state) or panics and types git reset --hard from muscle memory. Either way, the hotfix can land on top of state that nobody expected.

The blast radius is “the hotfix did not actually get deployed correctly.” If the engineer did git stash and forgot to git stash pop after merging, the local fix is silently dropped. If they did git reset --hard, any deploy-time config (build IDs, release tags written into version files, generated assets) is gone. The monitoring signal is the smoke test that runs immediately after every deploy: it should hit a known endpoint and verify the hotfix-specific behavior. If your smoke test only checks “200 OK on /health,” you will not catch a hotfix that silently regressed.

Recovery is git reflog and git cherry-pick. The reflog keeps a 90-day history of where HEAD has pointed, so you can find the lost commit hash and cherry-pick it back. Postmortem preventives are branch protection rules (require PR review and CI green before main can change), a deploy script that runs against a clean checkout every time (no in-place pulls on a long-lived working tree), and a smoke test per deploy that verifies the specific change, not just process liveness. Some teams also forbid running git commands on production hosts entirely — deploys come from immutable artifacts built in CI, which sidesteps this class of error completely.

Fix 1: Stash Your Changes, Then Pull

The most common fix. Git stash temporarily saves your changes, lets you pull, then reapplies them.

git stash
git pull
git stash pop

Step by step:

1. git stash — saves your uncommitted changes and reverts the working directory to the last commit.
2. git pull — pulls the latest changes from the remote (now succeeds because no local changes conflict).
3. git stash pop — reapplies your stashed changes on top of the pulled code.

If git stash pop causes merge conflicts, Git tells you which files conflict. Resolve them manually, then:

git add <resolved-files>
git stash drop  # Remove the stash entry after resolving

For detailed conflict resolution during stash pop, see Fix: git stash pop conflicts.

Pro Tip: Use git stash -u to also stash untracked files (new files that haven’t been added to Git). Without -u, untracked files are left behind and can sometimes cause issues during merge.

Fix 2: Commit Your Changes First

If your changes are ready to keep, commit them before pulling:

git add -A
git commit -m "WIP: save current work before pulling"
git pull

If the pull introduces conflicts with your committed changes, Git starts a merge. Resolve the conflicts:

# Edit the conflicting files
git add <resolved-files>
git commit -m "Merge remote changes"

This approach creates a clean history where your changes and the remote changes are both preserved. If you prefer a linear history, use git pull --rebase instead (see Fix 5).

Fix 3: Discard Your Local Changes

If you don’t need your local changes and just want the remote version, discard them:

Discard changes to specific files:

git checkout -- src/config.js src/utils/helpers.ts

Or with newer Git (2.23+):

git restore src/config.js src/utils/helpers.ts

Discard all uncommitted changes:

git checkout -- .

Or:

git restore .

Then pull:

git pull

Warning: Discarded changes are gone forever. Git does not keep a backup of uncommitted changes. Make sure you truly don’t need them before discarding. If you are unsure, use stash (Fix 1) instead — you can always drop the stash later.

Fix 4: Stash Specific Files

If you want to keep some changes and discard others, stash only specific files:

git stash push -m "save config changes" src/config.js

This stashes only src/config.js. Other modified files remain in your working directory.

Then resolve the remaining files:

git checkout -- src/utils/helpers.ts  # Discard this one
git pull
git stash pop  # Restore the stashed config changes

You can also use git stash push with --patch to selectively stash individual hunks within files:

git stash push -p

Git interactively asks which changes to stash and which to keep.

Fix 5: Use git pull —rebase

If you prefer a linear commit history without merge commits:

git stash
git pull --rebase
git stash pop

Or commit first, then rebase:

git add -A
git commit -m "WIP: my changes"
git pull --rebase

--rebase replays your commits on top of the remote changes instead of creating a merge commit. This keeps the history cleaner.

If conflicts arise during rebase, resolve them and continue:

# Edit conflicts
git add <resolved-files>
git rebase --continue

For more complex rebase scenarios, see Fix: git rebase conflicts.

To make rebase the default for git pull:

git config --global pull.rebase true

Fix 6: Add Generated Files to .gitignore

If the conflicting files are generated artifacts — build output, lock files, IDE configs — they probably should not be tracked by Git in the first place.

Common culprits:

• .DS_Store (macOS)
• Thumbs.db (Windows)
• *.pyc, __pycache__/ (Python)
• .idea/, .vscode/settings.json (IDE settings)
• dist/, build/, .next/ (build output)
• *.log (log files)

Add them to .gitignore:

.DS_Store
Thumbs.db
*.pyc
__pycache__/
.idea/
dist/
build/
*.log

Then remove them from tracking (without deleting the files):

git rm --cached .DS_Store
git rm --cached -r .idea/
git commit -m "Stop tracking generated files"

After this, Git no longer tracks these files, and they won’t cause merge conflicts.

Common Mistake: Adding files to .gitignore after they are already tracked does nothing. You must also git rm --cached them. The .gitignore file only affects untracked files.

Fix 7: Handle package-lock.json Conflicts

package-lock.json is a frequent source of this error. It changes whenever you npm install, and pulling someone else’s changes often conflicts.

Option 1: Accept theirs and regenerate:

git checkout --theirs package-lock.json
npm install
git add package-lock.json

Option 2: Stash, pull, reinstall:

git stash
git pull
npm install  # Regenerates lock file with merged dependencies
git add package-lock.json
git commit -m "Update package-lock.json after merge"
git stash pop

Fix 8: Force Checkout (Nuclear Option)

If you want to switch branches and don’t care about any local changes:

git checkout -f <branch-name>

Or:

git reset --hard
git checkout <branch-name>

Warning: git reset --hard permanently discards all uncommitted changes — both staged and unstaged. There is no recovery. Only use this when you are certain you don’t need any local changes.

If you end up in a detached HEAD state after a forced checkout, see Fix: git detached HEAD.

Still Not Working?

If the error persists after trying the fixes above:

Check for case-sensitivity conflicts. On macOS/Windows, Config.js and config.js are the same file. On Linux, they are different. This can cause phantom “changes” that Git reports as modified even though you haven’t edited them.

Check line ending settings. If core.autocrlf is converting line endings, Git may report files as modified even though the content is the same:

git config core.autocrlf

Set it consistently:

git config --global core.autocrlf input  # Linux/macOS
git config --global core.autocrlf true   # Windows

Check for file permission changes. On some systems, Git tracks file permission changes. If a file’s executable bit changed, Git reports it as modified:

git config core.fileMode false  # Ignore permission changes

Check for git hooks or IDE auto-formatting. Pre-commit hooks or IDE format-on-save can modify files right after you stage them, causing unexpected changes. Disable auto-format temporarily to test.

Use git diff to see what changed:

git diff src/config.js

This shows exactly what is different between your local file and the last commit. If the diff looks unexpected (whitespace changes, line endings), the issue is likely in your editor or Git configuration, not in your code.

Check the reflog if you already destroyed something. If you ran git reset --hard or git stash drop and lost a change you actually needed, every commit Git has seen in the last 90 days is still in .git/objects and reachable via reflog:

git reflog
# Find the commit hash where your work existed
git checkout <hash>          # Inspect it
git cherry-pick <hash>       # Or pull it back onto your current branch

This only recovers committed work. Uncommitted edits that were discarded by git checkout -- or git restore are gone — Git never wrote them to the object database. Once you have learned this lesson, commit early and often, even with WIP: messages, so the reflog has something to recover from. See Fix: git reset —hard undo for a deeper walkthrough.

Check for a partially-applied previous merge. If a previous git pull failed halfway through (network drop, Ctrl+C), Git can leave the index in an inconsistent state where files appear modified but git diff is empty. Look for .git/MERGE_HEAD or .git/index.lock:

ls .git/MERGE_HEAD .git/index.lock 2>/dev/null
git merge --abort   # if MERGE_HEAD exists
rm .git/index.lock  # if a stale lock exists from a crashed git process

Check sparse-checkout patterns. If you use sparse checkout (git sparse-checkout), files outside your sparse pattern are not in your working tree but are still tracked. A pull that updates one of those files can trigger this error in unexpected ways. List the active patterns with git sparse-checkout list and either widen the pattern or use git sparse-checkout reapply.

If none of this helps and you have to force push after resolving, be cautious — force push overwrites remote history and any teammate who already pulled the rewritten branch will see the same “local changes” error in reverse.