
A merge conflict happens when two branches change the same lines of a file and Git cannot decide which version to keep. To resolve one, you open the marked file, choose the correct lines, remove the marker lines, then stage and commit the result. This guide covers why conflicts occur, how to fix them, and how to avoid them.
This article is part of our complete Git and GitHub Actions workflow guide.
This guide walks you through merge conflicts with clear examples and commands.
1. What Is a Merge Conflict?
A merge conflict occurs when Git can’t automatically combine changes from two branches.
This usually happens when:
- Two people edit the same line in a file.
- One person edits a file while another deletes it.
- A rebase or cherry-pick introduces overlapping changes.
Git stops and asks you to resolve the conflict manually before proceeding.
2. Example: Creating a Merge Conflict
Let’s simulate a conflict:
# Create a new repo
git init merge-demo
cd merge-demo
echo "Hello World" > app.txt
git add app.txt
git commit -m "Initial commit"
# Create a feature branch
git checkout -b feature
echo "Hello from Feature Branch" > app.txt
git commit -am "Update in feature branch"
# Switch back to main
git checkout main
echo "Hello from Main Branch" > app.txt
git commit -am "Update in main branch"
# Try merging feature into main
git merge feature
Git will now report a merge conflict.
3. Understanding Conflict Markers
Open app.txt and you’ll see something like:
<<<<<<< HEAD
Hello from Main Branch
=======
Hello from Feature Branch
>>>>>>> feature
- <<<<<<< HEAD → your branch (main)
- ======= → separator
- >>>>>>> feature → the branch you’re merging in
4. Resolving Merge Conflicts
You have a few options:
✅ Option 1: Manually Edit
Decide which change to keep (or merge them):
Hello from BOTH Main and Feature
Then mark as resolved:
git add app.txt
git commit
✅ Option 2: Use a Merge Tool
Git can launch a merge tool (like VS Code, Meld, Vimdiff).
Example:
git mergetool
For VS Code:
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd "code --wait $MERGED"
git mergetool
✅ Option 3: Abort the Merge
If you want to cancel and start over:
git merge --abort
If the merge is already finished and you want it undone, git reset --hard ORIG_HEAD puts the branch back. Our Git recover lost commits guide tests that and the other undo paths.
5. Handling Complex Conflicts
For conflicts involving:
- Deleted files → decide whether to restore or remove.
- Multiple files → resolve them one by one.
- Rebase conflicts → use:
git rebase --continue git rebase --abort
6. Best Practices to Avoid Merge Conflicts
- Pull often → keep your branch updated with
main. - Small PRs → fewer changes mean fewer conflicts.
- Clear ownership → use CODEOWNERS to define who edits what.
- Feature flags → reduce long-lived feature branches.
- Rebase regularly → instead of letting branches drift far apart.
✅ Key Takeaways
- Merge conflicts happen when Git can’t auto-merge.
- Conflict markers show you the differences.
- You can resolve them manually, with a merge tool, or abort and retry.
- Best practices help reduce conflicts, but you’ll always face them sometimes.
Frequently Asked Questions
A conflict happens when two branches change the same lines of a file, or one branch edits a file the other deletes, and Git cannot decide which version to keep.
Open each file Git marks as conflicted, choose the correct lines, delete the conflict marker lines, then run git add on the file and commit.
Run git merge –abort, or git rebase –abort during a rebase, to return the working tree to the state before the merge started.
You cannot eliminate them, but small frequent merges, short-lived branches, and agreed formatting rules sharply reduce how often they happen.
Get the next guide by email
New DevToolHub guides on Git, GitHub Actions, Claude Code and cloud tools, emailed as they publish: about one a weekday. I run the commands before I write them up. The Git + GitHub Actions cheat sheet is a free PDF, no signup needed.
You Might Also Like
- 👉 Day 1: Git Fundamentals
- 👉 Day 2: Basic Git Workflow
- 👉 Day 3: Branching and Merging
- 👉 Day 4: Remote Repositories
- 👉 Day 5: Advanced Git Operations
- 👉 Day 6: Git Workflows and Best Practices
- 👉 Git Recover Lost Commits: 12 Fixes for Common Mistakes
- 👉 Advanced Git Commands You Need to Master (With Examples)
- 👉 Git Best Practices for Branching and Approvals
- 👉 GitHub CODEOWNERS & Permissions: Best Practices with Teams
- 👉 Git Hooks Explained: Automate Your Workflow with Examples
- 👉 Git Tags and Releases Best Practices: A Complete Guide