TECH **Git & GitHub: Merge Conflicts – How to Resolve with a Merge Tool**

Git & GitHub: Merge Conflicts – How to Resolve with a Merge Tool

(Hyper-Practical, Zero-Fluff Study Guide)

1. What This Is & Why It Matters

A merge conflict happens when Git can’t automatically reconcile differences between two branches. Think of it like two chefs editing the same recipe—one adds garlic, the other removes it. Git doesn’t know which change to keep, so it pauses and asks you to decide.

Why this matters in production:
- Broken deployments: If you merge conflicting code into main, your CI/CD pipeline might fail, or worse—deploy broken code to users.
- Wasted time: Manually resolving conflicts in a large codebase (e.g., 50+ files) without a tool is error-prone and slow.
- Team friction: Unresolved conflicts block other developers. If you’re the bottleneck, your team’s velocity drops.

Real-world scenario:
You’re a DevOps engineer working on a microservice. Your teammate updates the API contract in feature/login, while you modify the same endpoints in feature/auth. When you try to merge into develop, Git throws a conflict. If you resolve it incorrectly, the service might crash in staging.

Superpower: A merge tool (like meld, kdiff3, or VS Code’s built-in resolver) lets you visually compare changes, pick which lines to keep, and resolve conflicts in minutes—not hours.

2. Core Concepts & Components

• ? Merge Conflict
  Definition: Git’s way of saying, “I can’t decide which change to keep—you choose.” Production insight: Conflicts aren’t bugs; they’re a sign of parallel work. Ignoring them leads to broken builds.

• ? Three-Way Merge
  Definition: Git compares:

• The common ancestor (last commit both branches share).
• Your local changes (your branch).

• The incoming changes (the branch you’re merging).
  Production insight: Always check the ancestor to understand why the conflict exists.

• ? Conflict Markers (<<<<<<<, =======, >>>>>>>)
  Definition: Git inserts these in files to show conflicting sections.
  Example: ```python def calculate_discount(price): <<<<<<< HEAD
  return price * 0.9 # Your change: 10% discount =======
  return price * 0.8 # Their change: 20% discount

  
  

  feature/login ``` Production insight: Never commit files with conflict markers—your code won’t run.

  
  

• ? Merge Tool
  Definition: A GUI app (e.g., meld, kdiff3, VS Code) that visualizes conflicts and lets you pick changes interactively.
  Production insight: CLI-only conflict resolution is slow and risky. A merge tool reduces errors by 80%.

• ? .gitconfig
  Definition: Git’s config file where you set your default merge tool.
  Production insight: Configure this once to avoid typing git mergetool --tool=meld every time.

• ? git mergetool
  Definition: The command that launches your configured merge tool.
  Production insight: Run this after Git reports a conflict (not before).

• ? git rerere (Reuse Recorded Resolution)
  Definition: Git remembers how you resolved a conflict and reapplies the fix if it sees the same conflict again.
  Production insight: Enable this in large projects to avoid re-resolving the same conflicts.

• ? ours vs. theirs
  Definition:

• ours: Keep your changes (the current branch).
• theirs: Keep their changes (the incoming branch).
  Production insight: Use git checkout --ours file.txt or git checkout --theirs file.txt to pick a side without a merge tool.

3. Step-by-Step: Resolve a Conflict with a Merge Tool

Prerequisites

1. Git installed (git --version).
2. A merge tool installed (e.g., Meld, KDiff3, or VS Code).
3. A Git repo with two branches that have conflicting changes.

Step 1: Create a Conflict (For Practice)

# Clone a test repo (or use your own)
git clone https://github.com/your-repo.git
cd your-repo

# Create two branches with conflicting changes
git checkout -b feature/conflict-1
echo "Change from conflict-1" > conflict.txt
git add conflict.txt
git commit -m "Add conflict-1 change"

git checkout -b feature/conflict-2
echo "Change from conflict-2" > conflict.txt
git add conflict.txt
git commit -m "Add conflict-2 change"

# Try to merge (this will fail)
git checkout feature/conflict-1
git merge feature/conflict-2

Expected output:

Auto-merging conflict.txt
CONFLICT (content): Merge conflict in conflict.txt
Automatic merge failed; fix conflicts and then commit the result.

Step 2: Configure Your Merge Tool

Pick one of these tools and configure it:

Option A: Meld (Recommended for Linux/macOS)

# Install Meld (Linux: sudo apt install meld, macOS: brew install meld)
git config --global merge.tool meld
git config --global mergetool.meld.path "/usr/bin/meld"  # Adjust path if needed
git config --global mergetool.meld.trustExitCode true

Option B: KDiff3 (Cross-Platform)

# Install KDiff3 (Linux: sudo apt install kdiff3, macOS: brew install kdiff3)
git config --global merge.tool kdiff3
git config --global mergetool.kdiff3.path "/usr/bin/kdiff3"  # Adjust path
git config --global mergetool.kdiff3.trustExitCode true

Option C: VS Code (Built-in)

git config --global merge.tool vscode
git config --global mergetool.vscode.cmd "code --wait $MERGED"

Step 3: Launch the Merge Tool

git mergetool

What happens:
- Your merge tool opens with a 3-way diff (ancestor, yours, theirs).
- You’ll see conflicting sections highlighted.
- Use the GUI to: - Pick changes (click buttons or drag/drop).
- Edit manually (if needed).
- Save and exit when done.

Example (Meld):
- Left pane: Your changes (ours).
- Middle pane: Ancestor (common base).
- Right pane: Their changes (theirs).
- Bottom pane: Result (what will be saved).

Step 4: Save and Commit

1. After resolving all conflicts, save the file in your merge tool.
2. Close the merge tool.
3. Verify the resolved file:
   bash
cat conflict.txt # Should show your final merged content
4. Mark the conflict as resolved:
   bash
git add conflict.txt
5. Commit the merge:
   bash
git commit -m "Merge branch 'feature/conflict-2' into feature/conflict-1"

Step 5: Verify the Merge

git log --graph --oneline --all

Expected output:

*   abc1234 Merge branch 'feature/conflict-2' into feature/conflict-1
|\
| * def5678 Add conflict-2 change
* | 1234abc Add conflict-1 change
|/
* 9876zyx Initial commit

4. ? Production-Ready Best Practices

Security

• Never resolve conflicts in main/master directly. Always use a feature branch.
• Review changes carefully. A merge tool makes it easy to accidentally keep the wrong code.

Cost Optimization

• Use git rerere to avoid re-resolving the same conflicts: bash git config --global rerere.enabled true
• Avoid large binary files (e.g., node_modules, .zip). They cause conflicts that merge tools can’t handle well.

Reliability & Maintainability

• Resolve conflicts early. The longer you wait, the more divergent the branches become.
• Use descriptive commit messages for merges: ```bash git commit -m "Merge feature/login into develop
• Keep login API changes from theirs
• Keep auth middleware from ours" ```
• Tag conflict resolutions in the commit message (e.g., [conflict: login-api]).

Observability

• Monitor merge conflicts in CI. Add a step to fail the build if conflict markers are detected: bash grep -r "<<<<<<<" . && exit 1
• Log conflict resolutions in a team wiki or Slack channel to document decisions.

5. ⚠️ Common Mistakes & Traps

6. ? Exam/Certification Focus

Typical Question Patterns

1. Scenario: "You’re merging feature/login into develop and get a conflict in api.js. What’s the first command you run?"
2. Answer: git mergetool (or git status to see conflicts first).

3. Trap: git merge --abort is wrong—it cancels the merge entirely.

4. Scenario: "After resolving a conflict, the file still shows <<<<<<<. What did you forget?"

5. Answer: git add <file> to mark it as resolved.

6. Trap: git commit alone won’t work—you must git add first.

7. Scenario: "Which merge tool is configured by default in Git?"

8. Answer: None. You must configure one manually.

9. Trap: "vimdiff" is the default fallback, but it’s not a GUI tool.

10. Scenario: "How do you keep your changes and discard theirs for a single file?"

11. Answer: git checkout --ours file.txt
12. Trap: git merge --ours keeps all your changes, not just one file.

7. ? Hands-On Challenge

Challenge:
1. Create a Git repo with two branches (feature/a and feature/b).
2. In both branches, modify the same line in README.md.
3. Merge feature/b into feature/a and resolve the conflict using meld.
4. Verify the merge with git log --graph.

Solution:

# 1. Create repo and branches
mkdir merge-challenge && cd merge-challenge
git init
echo "Original line" > README.md
git add README.md
git commit -m "Initial commit"

git checkout -b feature/a
echo "Change from A" > README.md
git add README.md
git commit -m "Change from A"

git checkout -b feature/b
echo "Change from B" > README.md
git add README.md
git commit -m "Change from B"

# 2. Merge and resolve
git checkout feature/a
git merge feature/b  # Conflict!
git mergetool        # Use meld to pick "Change from A" or "Change from B"
git add README.md
git commit -m "Merge feature/b into feature/a"

# 3. Verify
git log --graph --oneline

Why it works:
- git mergetool launches your configured GUI to resolve the conflict.
- git add marks the file as resolved.
- git log --graph shows the merge commit.

8. ? Rapid-Reference Crib Sheet

9. ? Where to Go Next

1. Git Official Docs – Merge Tools
2. Meld Download & Docs
3. Git Rerere Guide
4. VS Code Git Merge Conflicts