[Git] Error: Your local changes would be overwritten by merge — Prevent Data Loss in Git — How to Fix It

Summary

error: Your local changes to the following files would be overwritten by merge occurs when you try to merge or pull while having uncommitted local modifications. Git refuses to proceed to avoid overwriting your changes. To fix this, you must commit, stash, or discard those local edits before continuing.

Context

This message appears during git pull, git merge, or git checkout operations when local changes exist in files that Git needs to modify or replace. The safeguard prevents data loss — Git stops automatically merging or switching branches until you resolve the conflict between your local working directory and the incoming changes.

Probable Cause

  • Uncommitted edits: You modified files locally that also changed in the remote branch.
  • Unstaged or staged changes overlap: The same files are touched by both local and remote commits.
  • Pending merges: You previously interrupted a merge without committing or aborting it.
  • Pulling before commit: Trying to synchronize before saving your local progress.

Quick Fix

  1. Check which files are blocking the merge: 
    git status
  2. If you want to keep your work, commit it: 
    git add . git commit -m "Save local changes"
    Then retry your pull or merge: 
    git pull origin main
  3. If you’re not ready to commit, stash temporarily: 
    git stash push -m "temp"
    Perform the pull or merge, then reapply your changes: 
    git stash pop
  4. If your local modifications don’t matter, discard them: 
    git restore . # for Git 2.23+ # or git checkout -- . # for older versions

Example

# Error $ git pull origin main 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
Fix

$ git stash push -m "temp"
Saved working directory and index state WIP on main: 7f6e1a2 Add footer section
$ git pull origin main
Updating 7f6e1a2..a5b2cd8
Fast-forward
$ git stash pop
Auto-merging src/app.js

Pitfalls & Debug

  • Symptom → You edited files locally but forgot. Fix → Use git diff to inspect what changed.
  • Symptom → You stashed work but nothing happened after stash pop. Fix → Check git stash list — the stash may still exist or failed to apply due to conflicts.
  • Symptom → You just want to overwrite everything. Fix → Run git fetch then git reset --hard origin/main — WARNING: this erases local edits permanently.
  • Symptom → Merge failed again after stash. Fix → Manually resolve conflicts, git add ., then git commit.

Verification & Next Steps

# Verify you have a clean working directory git status
If you stashed

git stash list

If you committed

git log -1

Best Practices

  • Always commit or stash before running git pull or git merge.
  • Use feature branches to isolate work and avoid local/remote overlap.
  • Keep commits small and frequent — easier recovery if conflicts arise.
  • Run git status before switching branches to avoid surprises.

Sources

git-merge Documentation

Atlassian — Git Stash

GitHub Docs — Using Git

Labels

Tool/Git, OS/Cross-platform, Topic/Merge Conflicts & Data Safety