Automatic merge failed
Git was unable to merge the branches automatically because changes in the target branch conflict with the source branch.
Usually happens because:
- ☑ Conflicting overlapping changes in merge branches files
- ☑ Binary files cannot be parsed or merged automatically by Git
- ☑ Submodule commits are out of sync between branches
🔍 Quick Checklist:
What is Automatic merge failed?
This error represents the overall state when Git aborts an automated branch integration. When you run 'git merge', Git attempts to perform a fast-forward merge or a three-way merge. If it finds conflicting changes (like edits to the same lines of code) in both branches, it reports 'Automatic merge failed', leaving the repository in a half-merged state. The user must manually resolve conflicts or abort the merge to restore the branch.
Common Causes
- Unreconciled file modifications: Overlapping modifications on the same files in both branches.
- Binary file conflicts: Git cannot automatically merge changes in binary files (like images, zip files, or compiled assets).
- Submodule state conflicts: Different submodules versions or hashes checked out on both merging branches.
| Cause | Frequency |
|---|---|
| Unresolved line modifications | ⭐⭐⭐⭐⭐ |
| Conflicting modifications on binary assets | ⭐⭐⭐⭐ |
| Diverging git submodule commits reference | ⭐⭐ |
Common Mistakes
- Running `git commit` without running `git add` on resolved files, which fails because Git thinks conflicts are still unaddressed.
- Attempting to manually edit binary files to remove conflict markers (doing so will corrupt the binary structure).
How to Fix
Git Operations & Verification
Git cannot insert text conflict markers inside binary assets. Use checkout flags to select files.
# 1. Keep our current branch logo image:
$ git checkout --ours assets/logo.png
# 2. Keep their incoming branch logo image:
$ git checkout --theirs assets/logo.png
# 3. Add to stage to mark resolved
$ git add assets/logo.pngPlatform Specific Fixes
Running manual merge resolution checks on command line.
# List status of unmerged files
git status --short | grep "^UU"Best Practices
- Merge or rebase frequently to minimize divergence between branches.
- Configure custom diff/merge settings for binary or specialized files inside your `.gitattributes` file.
Frequently Asked Questions (FAQ)
Q: What is the difference between 'automatic merge failed' and a merge conflict?
A merge conflict is the specific conflict within a file. 'Automatic merge failed' is the final notification returned by Git indicating it has paused the entire merge process because one or more conflicts occurred.
Q: How do I choose 'our' version of a file?
Run 'git checkout --ours path/to/file' to keep the changes from your current branch.
Q: How do I choose 'their' version?
Run 'git checkout --theirs path/to/file' to discard your local changes and accept the incoming branch's changes.
Q: How do I cancel the merge?
Run 'git merge --abort' to cancel the merge and restore your files to the state they were in before you started the merge.