Merge Conflicts

Listen to Episode 7: Merge Conflicts Are Not Scary - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

Related appendices: Appendix E: Advanced Git | Appendix G: VS Code Reference Authoritative sources: GitHub Docs: Resolving merge conflicts | Git SCM: Basic Merge Conflicts

Understanding, Preventing, and Resolving Conflicts

Merge conflicts sound intimidating but are a normal, manageable part of collaborative development. This guide explains what conflicts are, how to read conflict markers, and how to resolve them - step by step.

Workshop Recommendation (Chapter 7)

Chapter 7 uses one controlled practice challenge so students can learn conflict resolution without high-pressure scenarios.

• Challenge count: 1
• Time: under 10 minutes
• Evidence: issue-linked PR and completion comment
• Pattern: observe, resolve, verify

Chapter 7 Challenge Set

1. Resolve conflict markers - identify and clean up conflict markers in a practice file, then open a linked PR.

Branch guidance for Chapter 7: Use a short-lived feature branch: fix/yourname-issueXX (for example, fix/maria-issue48). The same pattern you used in Chapter 6.

Challenge 7.1 Step-by-Step: Resolve Conflict Markers

Goal: Identify the three types of conflict markers in a practice file, decide which content to keep, remove the markers, and submit a clean PR.

Agentic strategy: Sometimes an AI agent will confidently generate code that conflicts with human-written code. Resolving merge conflicts is not just a hurdle for human teamwork; it is exactly how you supervise, correct, and collaborate safely with an AI.

Where you are working: your Learning Room repository on GitHub.com (web editor) or in VS Code if you cloned locally.

Before you start: Open your assigned Chapter 7 challenge issue (the one titled "Chapter 7.1: Resolve Conflict Markers (@yourname)"). The issue description tells you which practice file contains the conflict markers.

Practice sample: learning-room/docs/samples/chapter-6-conflict-practice-sample.md

1. Open the practice file specified in your challenge issue.
2. Search the file for <<<<<<<. This is the start marker - it shows where the conflict begins.
3. Read the content between <<<<<<< and =======. This is your version (the current branch).
4. Read the content between ======= and >>>>>>>. This is their version (the incoming branch).
5. Decide which content to keep:
   • Keep only your version, or
   • Keep only their version, or
   • Combine both versions into one clean paragraph.
6. Delete all three marker lines:
   • The <<<<<<< HEAD line (or similar)
   • The ======= separator line
   • The >>>>>>> branch-name line
7. Review the file to confirm no marker lines remain. Search for <<<<<<< again - there should be zero results.
8. Commit your changes on a branch named fix/yourname-issueXX.
9. Open a pull request with:
   • Title: fix: resolve conflict markers in [filename]
   • Body: Include Closes #XX (your challenge issue number) and a 1-2 sentence description of which content you kept and why.

Screen reader tip: Use your screen reader's find command (Ctrl+F in browser, Ctrl+H in VS Code) to jump directly to <<<<<<<. The markers are plain text, so they are fully readable.

You are done when: Your PR passes bot validation checks and contains no remaining conflict markers.

Completing Chapter 7: Submit Your Evidence

When your PR is open and passing checks, post a comment on your assigned Chapter 7 challenge issue:

Chapter 7 completed:
- Challenge 7.1: Opened PR #[number] resolving conflict markers in [filename]
- Content decision: kept [your version / their version / combined both] because [reason]

Expected Outcomes

• Student can identify the three conflict marker lines (<<<<<<<, =======, >>>>>>>) immediately.
• Student can read both sides of a conflict and make an intentional content decision.
• Student can remove all markers and submit a clean, issue-linked PR.

If You Get Stuck

1. Can't find the markers? Use Ctrl+F and search for <<<<<<< - they are always in sets of three.
2. Not sure which side to keep? Read both versions aloud. Pick the one that is clearer, or combine them.
3. Accidentally deleted too much? Undo with Ctrl+Z and start the section over.
4. PR bot says content is wrong? Double-check that zero marker lines remain - search for <<<<<<<, =======, and >>>>>>>.
5. Ask facilitator to sanity-check your final content before opening the PR.
6. Finished but not sure you did it right? Compare your work against the Challenge 7 reference solution.

Learning Moment

Merge conflicts are not failures. They are a normal collaboration checkpoint and a chance to make an intentional content decision. In real open source projects, conflicts happen whenever two people edit near the same lines. The skill is not avoiding them - it is resolving them calmly and clearly.

Learning Pattern Used in This Chapter

1. Start with a controlled, safe conflict (practice file with known markers).
2. Learn to read the conflict structure (your version vs. their version).
3. Make a deliberate content decision (not just deleting randomly).
4. Submit clean evidence through the PR workflow.
5. Build confidence for real conflicts in future contributions.

About Learning Cards in This Chapter

This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. Not every card appears at every step. Open the ones that match how you work.

The following table describes the five learning card types used in this chapter.

Local Git Alternative: Resolving Conflicts from Your Terminal

cd ~/Documents/learning-room
git checkout main
git pull origin main
git checkout your-branch-name
git merge main

code docs/welcome.md   # or your preferred editor

<<<<<<< HEAD
Your version of the content
=======
The incoming version from main
>>>>>>> main

git add docs/welcome.md
git commit -m "Resolve merge conflict in welcome.md"
git push

What Is a Merge Conflict?

A merge conflict occurs when two people have both changed the same part of the same file in different ways, and Git cannot automatically decide which version is correct.

Git can merge changes automatically when they touch different parts of a file. Conflicts only happen when two changes overlap - for example:

• Person A changed line 12 to say "Submit form"
• Person B changed line 12 to say "Send message"
• Git asks: which one do you want to keep?

Why Conflicts Happen

The most common causes:

How to Prevent Conflicts (Prevention is Easier Than Resolution)

Avoiding conflicts in the first place saves time and reduces stress. Here are the most effective strategies:

1. Keep your branches short-lived

Work in small, focused chunks. A branch that lives for 3 days has far fewer conflicts than one that lives for 3 weeks.

• Target: 1-3 days from branch to merge
• If a feature takes longer, break it into smaller PRs

2. Sync with main frequently

The longer your branch diverges from main, the more likely conflicts become.

Best practice: Sync daily if main is active:

# From your feature branch
git fetch origin
git merge origin/main
# Or: git rebase origin/main (if comfortable with rebasing)

GitHub web method: Use the "Update branch" button on your PR if it appears.

3. Communicate with your team

Let others know what files you're working on. Use issue comments:

"Heads up: I'm working on the [TODO] sections in docs/welcome.md for Challenge 3. If you're also editing welcome.md, let's coordinate so we don't conflict."

In the Learning Room, this is especially important because multiple students may claim challenges that touch the same file. Challenges 1 and 3 both modify docs/welcome.md - if two students work on both simultaneously without coordinating, a merge conflict will occur.

4. Avoid mass reformatting

Running a formatter on an entire file creates conflicts with anyone else editing that file. If you must:

• Do it in a separate PR before functional changes
• Announce it to the team
• Merge it quickly so everyone can sync

5. Pull before you push

Always fetch and merge (or pull) before pushing your changes:

git pull origin main  # Sync your local main
git checkout your-branch
git merge main        # Merge main into your branch
git push              # Now push

This catches conflicts locally where they're easier to resolve.

6. Work on separate files when possible

If multiple people are working simultaneously, divide tasks by files or modules rather than everyone touching the same code.

7. Keep PRs small

A 50-file PR will almost certainly conflict with something. A 5-file PR merges quickly and cleanly.

The most effective contributors make many small PRs rather than one giant one.

8. Use Draft PRs for early visibility

Open your PR as a draft while still working. Others can see what you're changing and avoid overlapping work. Convert to "Ready for review" when done.

Learning Cards: How to Prevent Conflicts

Advanced Prevention: Understanding Fast-Forward Merges

When your branch is perfectly up to date with main and adds new commits on top, GitHub can do a "fast-forward" merge - main simply moves forward to your latest commit. No merge commit needed. No possibility of conflicts.

How to achieve this: Rebase your branch on main right before merging:

git checkout your-branch
git fetch origin
git rebase origin/main
git push --force-with-lease  # See warning below about force pushing

Warning: Force pushing rewrites history. Only do this on branches you alone control (not shared branches). Never force push to main.

For more on force pushing and rebasing, see the Glossary.

When Conflicts Are Actually Good

Conflicts indicate that multiple people are actively improving the project. In a healthy, collaborative environment, occasional conflicts are normal and manageable.

If you never have conflicts, it might mean:

• You're the only contributor (less review, less learning)
• PRs are moving too slowly (stagnation)
• People are avoiding working on important files (technical debt)

The goal isn't zero conflicts. The goal is catching them early, resolving them cleanly, and learning patterns that reduce future conflicts.

Spotting a Conflict on GitHub

Tool Cards: Resolve a Merge Conflict

github.com (browser):

1. On the PR page, click Resolve conflicts if the button is available.
2. Edit the file in the web editor to remove conflict markers.
3. Click Mark as resolved, then Commit merge.

github.dev (web editor):

1. Open the PR's branch by pressing . on the repository page.
2. Open the conflicting file -- conflict markers are highlighted in the editor.
3. Edit to resolve, commit via Source Control panel.

VS Code Desktop:

1. Pull the latest changes: git pull origin main.
2. VS Code highlights conflicts with Accept Current / Accept Incoming / Accept Both buttons.
3. Click your choice, save, stage, and commit.

GitHub Desktop:

1. Branch > Update from main (or the merge prompt banner).
2. GitHub Desktop opens your editor with conflict markers highlighted.
3. Resolve in the editor, return to GitHub Desktop, and click Commit merge.

Git CLI (terminal):

git merge main
# Edit conflicting files to remove <<<<<<< / ======= / >>>>>>>
git add resolved-file.md
git commit -m "resolve merge conflict"

When a PR has a merge conflict, you will see this message on the Conversation tab, near the merge section:

“This branch has conflicts that must be resolved”

You will also see a “Resolve conflicts” button. If you cannot see it (it may require write access), contact the PR author.

Conflict Markers - What They Mean

When conflict markers appear in a file, your editor is showing you both versions of the conflicted content so you can choose. The format is always:

<<<<<<< HEAD
The content that is on YOUR current branch
=======
The content coming from the OTHER branch (or main)
>>>>>>> branch-name-or-commit-hash

Breakdown

• <<<<<<< HEAD - the start of YOUR version (HEAD = "the branch you are currently on")
• ======= - the dividing line between the two versions
• >>>>>>> branch-name - the end of the INCOMING version (from the branch being merged in)

Example in a real file

Original file (docs/keyboard-shortcuts.md) before conflict

| Insert+Space | Toggle between Browse Mode and Focus Mode |

After two students both added a shortcut to the same table row

<<<<<<< HEAD
  Insert+Space -- Toggle between Browse Mode and Focus Mode
  Insert+F5 -- List elements by type
=======
  Insert+Space -- Toggle between Browse Mode and Focus Mode
  Insert+F7 -- Elements list (links, headings, form fields)
>>>>>>> add-nvda-shortcut

Resolution options

1. Keep your version: add only Insert+F5
2. Keep their version: add only Insert+F7
3. Keep both rows: add both shortcuts to the table (often the right answer when two students added different valid shortcuts)

Learning Cards: Conflict Markers

Resolving Conflicts on GitHub (Web Editor)

GitHub has a built-in conflict editor that you can use without any local tools.

Step-by-step: GitHub Conflict Editor

What it looks like in the editor

When the conflict editor opens, your screen reader will announce a text editor. In Focus Mode, navigate with arrow keys. The content reads:

<  <  <  <  <  <  <  H  E  A  D
<button aria-label="Submit form">Submit</button>
=  =  =  =  =  =  =
<button type="submit">Send message</button>
>  >  >  >  >  >  >  f  e  a  t  u  r  e  /  f  o  r  m - i  m  p  r  o  v  e  m  e  n  t  s

(Note: screen readers may spell out the < and > characters letter by letter - this is normal)

Learning Cards: Resolving Conflicts on GitHub

Resolving Conflicts in VS Code (Day 2)

See also: Appendix E: Advanced Git covers rebase, cherry-pick, and other advanced conflict resolution strategies.

VS Code has excellent merge conflict tooling with full screen reader support. This is covered in depth in Git & Source Control in VS Code, but here is an overview:

VS Code shows conflicts as

<<<<<<< HEAD (Current Change)
Your version
======= original                   -- (3-way merge, if enabled)
Original version before both edits
=======
Incoming version
>>>>>>> branch-name (Incoming Change)

VS Code merge conflict actions

When You Feel Stuck

Ask for help - it's normal

If you are unsure which version to keep:

1. Leave a comment on the PR: "I have a merge conflict in filename.js and I'm not sure which version to keep - could someone help me understand the intent of these two changes?"
2. Tag the PR author or a maintainer with @username

Abandon and start fresh (nuclear option)

If a conflict is severe (the branch diverged a lot from main):

1. Close the PR without merging
2. Start a new branch from the latest main
3. Apply only your intended changes to the new branch
4. Open a new PR

This is legitimate - not a failure.

Learning Cards: When You Feel Stuck

Reading a Conflict Message from Git (Command Line Reference)

If you work locally, git merge or git pull will say:

CONFLICT (content): Merge conflict in src/index.html
Automatic merge failed; fix conflicts and then commit the result.

And git status will show:

both modified: src/index.html

These are normal outputs. The conflict markers are inserted into the file by Git - open the file and follow the steps above.

# 1. Start the merge that causes the conflict
git merge main

# 2. See which files have conflicts
git status
# Look for "both modified:" entries

# 3. Open each conflicted file in your editor
# Edit the file: remove <<<<<<, =======, >>>>>> markers
# Keep the content you want

# 4. After editing, mark the file as resolved
git add src/index.html

# 5. Complete the merge
git commit
# Git auto-fills the merge commit message

# Check the result
git log --oneline -3

# View PR status (shows merge state)
gh pr view 42

# Check all PR checks and merge readiness
gh pr checks 42

# View the diff to understand what changed
gh pr diff 42

Summary Checklist

Before you start:
  □ My PR is small and focused (fewer conflicts = easier life)
  □ I checked that others aren't editing the same files

When you see a conflict:
  □ Don't panic - conflicts are normal
  □ Read both versions (between <<< and ===, and between === and >>>)
  □ Decide: keep one, keep both, or combine intelligently
  □ Remove ALL three conflict marker lines (<<<, ===, >>>)
  □ Verify the final file makes sense
  □ Mark as resolved → Commit merge

After resolving:
  □ Re-check that the PR description and issue link are still accurate
  □ Comment on the PR: "Resolved merge conflict - kept both the aria-label and type attribute"
  □ Request re-review if reviewers already approved before the conflict was introduced

Try It: Read a Conflict (Without Fear)

Time: 2 minutes | What you need: Any text editor or just read below

Read this merge conflict aloud. The goal is not to resolve it - just to understand what you're hearing:

The button should have an
<<<<<<< HEAD
aria-label="Submit form"
=======
aria-label="Send your response"
>>>>>>> feature-branch
attribute for screen readers.

Answer these three questions:

1. What does your branch say? (The text between <<<<<<< HEAD and =======)
2. What does the other branch say? (The text between ======= and >>>>>>>)
3. Which version would you keep, and why?

You're done. You just read a merge conflict. That's the entire skill - everything else is just choosing which lines to keep and deleting the three marker lines.

What success feels like: Conflicts aren't mysterious anymore. They're just two versions side by side with markers telling you which is which. You already know how to pick the right one.

Day 2 Amplifier - Copilot Chat & Conflict Prevention

Resolve at least one conflict completely by hand before using any AI assistance. You must be able to read <<<<<<<, =======, and >>>>>>> markers and understand what each version represents. An AI-suggested resolution you cannot independently verify is a liability - you are accepting a change you do not understand into a codebase other people depend on.

Once you have mastered manual conflict resolution:

• In VS Code - Copilot Chat (Ctrl+Alt+I, or Chat: Open Chat from the Command Palette if your keymap differs) can explain a conflict in plain language - "Person A renamed the button to 'Submit Form'; Person B renamed it to 'Send Message'. Which intent should take priority?" - but you decide what survives
• In your repo - Accessibility Agents' @pr-review can identify high-risk overlapping changes before a conflict occurs, flagging when two contributors are editing the same file area and giving you time to coordinate before it escalates
• In the cloud - GitHub Agentic Workflows can detect stale PRs diverging from main and automatically notify contributors with a suggested rebase checklist - preventing the conflict before it is ever introduced

Understanding conflict markers is not a stepping stone to letting AI handle conflicts. It is the skill that tells you when AI got it wrong.

Challenge Time: Check the Challenge Hub for Challenge 7: Survive a Merge Conflict. Follow the steps to resolve it, then move to Chapter 08: Open Source Culture.

Next: Chapter 08: Open Source Culture
Back: Chapter 06: Working with Pull Requests
Related appendices: Appendix E: Advanced Git

Authoritative Sources

Use these official references when you need the current source of truth for facts in this chapter.

• GitHub Docs, home
• GitHub Changelog
• About Git
• GitHub flow
• About pull requests
• About issues
• Contributing to a project

Section-Level Source Map

Use this map to verify facts for each major section in this file.

• Understanding, Preventing, and Resolving Conflicts: GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• Workshop Recommendation (Chapter 7): GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• Local Git Alternative: Resolving Conflicts from Your Terminal: GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• What Is a Merge Conflict?: GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• Why Conflicts Happen: GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• How to Prevent Conflicts (Prevention is Easier Than Resolution): GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• Advanced Prevention: Understanding Fast-Forward Merges: GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• When Conflicts Are Actually Good: GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• Spotting a Conflict on GitHub: GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• Conflict Markers - What They Mean: GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• Resolving Conflicts on GitHub (Web Editor): GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• Resolving Conflicts in VS Code (Day 2): GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• When You Feel Stuck: GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• Reading a Conflict Message from Git (Command Line Reference): GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• Summary Checklist: GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests
• Try It: Read a Conflict (Without Fear): GitHub Docs, home, GitHub Changelog, About Git, GitHub flow, About pull requests