Git merge conflicts: resolve them without losing work
Short answer: A merge conflict happens when two people changed the same part of the same file differently and Git can't decide which version to keep. Git stops, marks the clashing sections in the file with <<<<<<<, ======= and >>>>>>> lines, and waits for a person to choose. Don't panic and don't force anything: run git status to see the affected files, edit each conflict to the correct final version, remove the markers, git add the files and finish the merge. If it's getting messy, git merge --abort returns you to where you started. Small, frequent merges prevent most conflicts.
What a conflict looks like
The Pro Git book's chapter on basic branching and merging explains that if you changed the same part of the same file differently in the two branches you're merging, Git won't be able to merge them cleanly. It pauses the merge, and files with conflicts are listed as unmerged when you run git status.
Inside a conflicted file, Git adds standard markers:
<<<<<<< HEAD
<p>Call us on 09 123 4567</p>
=======
<p>Phone: 09 765 4321 (Mon–Fri)</p>
>>>> update-contact-page
The part above ======= is your current branch's version; the part below is the incoming branch's version. Your job is to replace the whole block, markers included, with what the file should actually say. That might be one side, the other, or a combination.
Step-by-step resolution
- Check status.
git statuslists "Unmerged paths" with each conflicted file marked as "both modified". - Open each file and search for
<<<<<<<. - Decide the right result. Talk to the person who made the other change if you're unsure. Conflicts are often about intent, not code.
- Edit the block to the final version and delete all three marker lines. The Pro Git book stresses that the
<<<<<<<,=======and>>>>>>>lines must be completely removed. - Mark resolved. Run
git addon each file; the book explains that staging the file marks the conflict as resolved. - Check again.
git statusshould say all conflicts are fixed but you're still merging. - Finish. Run
git commit(orgit merge --continue). - Test. Build or run the site and check the affected pages before pushing.
When to back out
The git merge documentation describes git merge --abort, which aborts the merge and tries to reconstruct the pre-merge state. It warns that if there were uncommitted changes when the merge started, it may not be able to reconstruct them. So:
- commit or stash your work before merging;
- if a merge becomes confusing, abort, take a breath and try again, perhaps with the other developer.
Make conflicts easier to read
The git merge documentation explains that setting the merge.conflictStyle configuration to diff3 or zdiff3 also shows the common ancestor version, the text before either person changed it. Seeing the original often makes it obvious what each person intended.
Visual merge tools, built into many code editors, show the two versions side by side with buttons to accept either or both. They're easier for occasional Git users than raw markers.
Files that need special care
- Lock files such as
package-lock.json: usually regenerate rather than hand-edit. Resolve the package list, then reinstall. - Generated files such as compiled CSS or build output: ideally they shouldn't be in Git at all; regenerate them.
- Database migrations: two developers adding migrations at the same time can need framework-specific steps.
- Binary files such as images: Git can't merge them; choose one version deliberately.
- Content files edited by non-developers: agree who owns which pages.
Preventing conflicts
- Merge or rebase from the main branch often, so differences stay small.
- Keep branches short-lived: days, not weeks.
- Make small, focused changes instead of large reformatting commits.
- Agree on formatting tools so automatic formatters don't rewrite whole files differently on different machines.
- Communicate when you're about to change a shared file, such as the main stylesheet or navigation.
- Use pull requests so changes are reviewed and merged one at a time.
Conflicts in hosted editors and CMS deploys
Not every conflict appears in a terminal. Hosting platforms and Git-based website builders often show conflicts in their web interface when a pull request can't be merged automatically. Most let you resolve simple conflicts in the browser using the same idea: choose or combine the versions and remove the markers. For anything larger, pull the branch locally and resolve it with an editor, where you can test the result before pushing.
Agree a team routine
A short written routine prevents most bad merges: everyone pulls the latest main branch before starting work, branches are named after the task, nobody force-pushes to shared branches, conflicts are resolved by the person merging with the other author on call, and every merged change is checked on a staging site before going live. Put the routine in the repository's readme so new team members and freelancers see it on day one.
An illustrative example
A hypothetical Halifax marketing agency had a designer and a developer editing the same website repository. Both changed the contact page in separate branches and the merge stopped with a conflict. The developer ran git status, opened the file, saw the designer's new layout below ======= and his own phone number update above it, combined them into one block, removed the markers, added and committed the file, and checked the page in the browser. The team then turned on zdiff3 and agreed to merge from main every morning.
FAQ
Did I lose any work?
No. Both versions are in the file until you resolve it, and committed history is kept.
Can I just accept "mine" for everything?
Only if you're sure the other changes aren't needed. That's how work gets lost.
Why do conflicts happen when we edited different lines?
Changes very close together, or a reformatted file, can still clash.
Are rebase conflicts different?
Similar markers and resolution, but you may resolve them commit by commit.
If merge conflicts keep slowing your team down and you'd like a simpler workflow, tell us how your team works.