DevToolHub

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

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

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
• 👉 Day 7: Troubleshooting and Expert Techniques
• 👉 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