When you perform a merge operation in a Git repository (e.g., git merge), you may encounter an error message: “Your local changes would be overwritten by merge”. This message means: “Your local modifications will be overwritten by the merge operation”. Git prevents the merge because it detects that your local branch has uncommitted changes, which could conflict with the target branch’s content or directly overwrite your uncommitted changes, risking data loss.

Why does this error occur?¶

For example: Suppose you made some changes to a file (e.g., main.js) on the dev branch but haven’t committed them (i.e., you haven’t run git add or git commit). If you then try to switch to the master branch and merge the dev branch’s changes (git merge dev), Git will worry: “If I merge directly, will your uncommitted changes on dev be overwritten? Or will there be conflicts with the master branch?” Hence, the error is triggered.

Solutions (in order of recommendation)¶

Here are common solutions to choose from based on your situation:

Method 1: Stash local changes and then merge (Most Recommended, Preserves Changes)¶

If you don’t want to discard your local modifications but want to temporarily “save” them to merge first, use git stash.
Steps:
1. Check the current status of changes (optional, to confirm uncommitted content):

   git status

(If you see uncommitted changes, e.g., modified: main.js, proceed to the next step.)

2. Stash local changes:

   git stash

This command “packages” all uncommitted changes, leaving your working directory clean (aligned with HEAD).

3. Perform the merge:

   git merge dev  # Replace "dev" with the branch you want to merge

Git will no longer warn about overwritten changes since the working directory is now clean.

4. Restore stashed changes:

   git stash pop

This restores the most recent stashed changes to the working directory and deletes the stash record (use git stash apply to keep the stash record).

Method 2: Commit local changes first, then merge (Most Safe, Preserves Changes)¶

If you confirm your local changes are valuable (and need to keep them), commit them first before merging. This ensures Git doesn’t detect uncommitted changes at risk of being overwritten.
Steps:
1. Stage local changes:

   git add .  # Add all changes to the staging area (specify filenames if only partial changes are needed)

2. Commit the staged changes to your local repository:

   git commit -m "Temporary commit: Save current changes before merging"

(Customize the commit message, e.g., “Fix bug” or “Add new feature.”)

3. Perform the merge:

   git merge dev  # Merge again; no conflicts since changes are committed

Method 3: Discard local changes (Use with Caution! Only for Confirmed Useless Changes)¶

If you’re certain local changes are unnecessary (e.g., test code, temporary drafts), you can discard them and then merge.
⚠️ Warning: This method permanently deletes uncommitted changes. Ensure you’ve backed up or confirmed the changes are insignificant!
Steps:
1. Discard all local changes (permanent data loss risk):

   git reset --hard HEAD

(--hard fully resets the working directory and staging area to the HEAD state, losing all uncommitted changes.)

2. Perform the merge:

   git merge dev

Method 4: Resolve merge conflicts (If conflicts persist after merging)¶

If a merge conflict occurs (e.g., different branches modified the same line in a file), Git will prompt “Automatic merge failed.” In this case, resolve the conflicts manually.
Steps:
1. Ensure local changes are handled (e.g., using Method 1/2/3 to stash or commit), then merge:

   git merge dev

Git will notify you of conflicting files (e.g., Automatic merge failed; fix conflicts and then commit the result.).

2. Open the conflicting file (e.g., main.js) and locate conflict markers:
   The file will show content like:

   <<<<<<< HEAD
   Your current branch's changes (e.g., console.log("hello"))
   =======
   Changes from the branch being merged (e.g., console.log("world"))
   >>>>>>> dev

3. Manually resolve conflicts:
   Keep or modify the content as needed, then delete the conflict markers (<<<<<<<, =======, >>>>>>>). For example, to keep the merged branch’s changes, delete <<<<<<< HEAD and =======, leaving only the content after >>>>>>> dev.

4. Mark conflicts as resolved and commit:

   git add main.js  # Replace "main.js" with the conflicting file
   git commit -m "Resolve merge conflicts"

Notes¶

1. git stash is a “lifesaver”: If you’re unsure whether to discard changes, use git stash to temporarily save them, then git stash pop to restore after merging. This avoids data loss.
2. git reset --hard is dangerous: This command permanently deletes uncommitted changes. Always confirm the changes are irrelevant before using it!
3. Backup changes: If modifications might be important, copy them to another location (e.g., a new folder) before proceeding.

Summary¶

The core idea to resolve “Your local changes would be overwritten by merge” is: either stash/commit your changes or discard them. Prioritize stashing or committing (Methods 1/2) unless you’re certain the changes are unnecessary (Method 3). If conflicts arise during merging, manually resolve the markers in the conflict files.

With these methods, you can successfully handle Git merge conflicts without losing data!