Resolving Merge Conflicts — Resolve simple merge conflicts in text files (intro) - JavaScript

SECTION 1

Historical Context & Motivation

When people work together on a software project, they often edit the same files. Before modern tools existed, developers had to manually coordinate who was editing what—sometimes by literally shouting across the room, "Hey, I'm editing that file right now!" This approach didn't scale. As projects grew from a handful of files to thousands, the software industry needed a better way to handle simultaneous edits. The concept of version control emerged to solve this problem, and with it came the challenge of merge conflicts—situations where two people change the same part of a file and the computer can't automatically figure out which change to keep.

1972 • SCCS — First Version Control

Bell Labs creates the Source Code Control System (SCCS), one of the first tools to track file history. It used a lock-based model: only one person could edit a file at a time, avoiding conflicts entirely but slowing teams down.

1986 • CVS Introduces Merging

The Concurrent Versions System (CVS) allowed multiple developers to edit files simultaneously. When their changes overlapped, it introduced the concept of a merge conflict that required manual resolution.

2005 • Git Is Born

Linus Torvalds creates Git to manage the Linux kernel. Git's branching model makes merging a core part of everyday development, making merge conflict resolution an essential skill for all developers.

2008 • GitHub Launches

GitHub brings Git-based collaboration to the mainstream. Millions of developers begin using branches and pull requests, making merge conflicts a daily occurrence in professional and open-source work.

Today, nearly every JavaScript project is managed with Git. Whether you're building a React app, a Node.js server, or a simple webpage, you'll eventually encounter a merge conflict. The question isn't if you'll face a conflict—it's when. So how do you read, understand, and fix a merge conflict in a text file? That's exactly what this lesson covers.

SECTION 2

Core Principles & Definitions

Before you can fix a merge conflict, you need to understand a few foundational ideas about how Git tracks changes and why conflicts happen in the first place. A branch in Git is like a separate copy of your project where you can make changes without affecting the main codebase. When you're done, you merge your branch back into the main branch. Git is usually smart enough to combine changes automatically, but when two branches modify the same lines of the same file, Git can't decide which version to keep—that's a merge conflict.

Branch

An independent line of development. Think of it as a parallel universe for your code where you can experiment freely without breaking the main project.

Merge

The process of combining changes from one branch into another. Git automatically merges changes that don't overlap, creating a single unified version of the code.

Conflict Markers

Special lines that Git inserts into your file to show you exactly where the conflict is. They use symbols like <<<<<<<, =======, and >>>>>>>.

Resolution

The act of choosing which changes to keep (or combining both), removing the conflict markers, and telling Git the conflict is resolved by staging and committing the file.

✦

KEY TAKEAWAY

Think of a merge conflict like two people editing the same sentence in a shared Google Doc at the same time while offline. When they reconnect, the app can't decide whose sentence to keep—so it highlights both versions and asks a human to choose. Git does the same thing with conflict markers in your code files.

SECTION 3

Visual Explanation — How a Conflict Forms

This diagram shows how two branches diverge from a shared commit. Both branches change line 5 of the same file. When you try to merge them, Git inserts conflict markers because it cannot automatically choose between "blue" and "red".

In the diagram above, notice how both branches stem from the same starting point (commit B). Your branch changes line 5 to color = "blue", while their branch changes the exact same line to color = "red". Git handles hundreds of non-overlapping changes automatically, but when two changes touch the same line, it stops and asks you for help. The bottom box shows what your file actually looks like after a failed merge—filled with those special conflict markers.

SECTION 4

How Conflict Markers Work

When Git encounters a merge conflict, it modifies the conflicted file by inserting three special markers. Understanding these markers is the key to resolving any conflict. Let's break down exactly what each marker means and where it appears.

The Three Conflict Markers

The first marker is <<<<<<< HEAD. Everything between this line and the next marker is your version of the code—the changes on your current branch. The word HEAD refers to the latest commit on the branch you're currently on.

The second marker is =======. This is the divider between your changes and their changes. Think of it like a fence separating two yards.

The third marker is >>>>>>> branch-name. Everything between the ======= and this line is their version of the code—the changes from the branch you're trying to merge in. The branch name tells you where those changes came from.

ℹ

Full Conflict Pattern

A complete conflict block always follows this pattern: <<<<<<< HEAD your changes here ======= their changes here >>>>>>> feature-branch You must remove all three marker lines and decide which code to keep. You can keep yours, theirs, both, or write something entirely new.

The Resolution Process

Open the file — Look for the <<<<<<< markers. Your text editor or IDE will usually highlight these.
Read both versions — Understand what your branch changed and what their branch changed. Ask yourself: what was the intent behind each edit?
Choose and edit — Keep your version, keep their version, combine both, or rewrite the section entirely.
Remove ALL markers — Delete every <<<<<<<, =======, and >>>>>>> line. Leaving them in will cause syntax errors.
Stage and commit — Run git add <file> then git commit to finalize the merge.

SECTION 5

Anatomy of a Conflicted File

Let's look at a realistic example. Imagine you and a teammate are both working on a JavaScript file called config.js. You're on a branch called update-theme and your teammate is on a branch called dark-mode. Both of you edited the same section of the file.

This annotated file view shows the complete structure of a merge conflict. Lines 1–3 and 11–12 are clean—Git had no trouble with them. Lines 4–10 contain the conflict zone, marked by the three conflict delimiters. The violet-shaded region is your code; the pink-shaded region is theirs.

Notice that the lines outside the conflict markers (lines 1–3, 11–12) are completely normal. Git doesn't touch code that wasn't changed by both branches. Only the overlapping changes—lines 5–6 in your branch and lines 8–9 from the dark-mode branch—are wrapped in markers. A single file can have multiple conflict blocks if there are several overlapping sections. You need to resolve each one individually.

SECTION 6

Worked Example — Resolving a Conflict Step by Step

Let's walk through resolving the conflict from the previous section. We'll assume you've decided that the correct resolution is to use their theme name ("midnight") but keep your font size (16). This is a very common scenario—combining the best parts of both changes.

Resolving the config.js Merge Conflict

1
Step 1 — Identify the Conflict

After running git merge dark-mode, Git outputs a message like CONFLICT (content): Merge conflict in config.js. Run git status to confirm which files have conflicts. Open config.js in your text editor.

The file shows conflict markers around lines 4–10.
2
Step 2 — Read Both Versions

Between <<<<<<< HEAD and =======, your branch sets theme: "ocean" and fontSize: 16. Between ======= and >>>>>>> dark-mode, their branch sets theme: "midnight" and fontSize: 14.

You understand both sides. Their theme name is better; your font size is better.
3
Step 3 — Edit the File

Delete all three marker lines (<<<<<<<, =======, >>>>>>>) and write the combined result. Your file should now read: theme: "midnight", fontSize: 16,

The conflict zone is replaced with a single, clean version that combines both contributions.
4
Step 4 — Verify the File

Scan the entire file for any remaining <<<<<<< markers. Make sure the JavaScript syntax is valid—no missing commas, no broken brackets. You can run the file with node config.js to check for syntax errors.

No markers remain. The file is clean JavaScript.
5
Step 5 — Stage and Commit

Run git add config.js to tell Git you've resolved the conflict, then run git commit. Git will auto-populate a merge commit message. You can accept it or customize it to explain your resolution choices.

The merge is complete. Both branches are unified.

💡

Pro Tip

Most code editors like VS Code will show you color-coded buttons above each conflict: "Accept Current Change," "Accept Incoming Change," "Accept Both Changes," or "Compare Changes." These buttons automate the marker removal, but you should still understand the markers themselves—the buttons don't always produce the result you want, especially when you need to combine parts of both versions.

SECTION 7

Resolution Strategies Compared

When you encounter a merge conflict, you have several options for how to resolve it. Each strategy is appropriate in different situations. Understanding when to use each approach will save you time and prevent bugs.

Strategy	What You Do	When to Use It
Accept Yours	Delete their changes and the markers. Keep only the code between `<<<<<<< HEAD` and `=======`.	When you're confident your changes are correct and their changes are outdated or wrong.
Accept Theirs	Delete your changes and the markers. Keep only the code between `=======` and `>>>>>>>`.	When their version is better, or you want to defer to a teammate's expertise on that part of the code.
Combine Both	Manually merge the best parts of both versions into a new version. Remove all markers.	When both branches made valuable but different changes that should coexist. This is the most common approach in real projects.
Rewrite	Discard both versions and write entirely new code that addresses the intent of both changes.	When the conflict reveals a deeper design issue and neither version is quite right.
Abort the Merge	Run `git merge --abort` to undo the entire merge attempt and return to the state before you merged.	When the conflict is too complex to resolve right now, or you need to talk to your teammate first.

Five common merge conflict resolution strategies

✦

KEY TAKEAWAY

Resolving a merge conflict is like being a judge in a debate. Two sides present their arguments (the two code versions). You listen to both, then issue a ruling—which might side with one party, combine elements of both arguments, or propose a completely new solution. The key is that you are always in control. Git never forces a resolution on you.

SECTION 8

Connection to Advanced Conflict Resolution

The simple text-based conflicts we've covered in this lesson are just the beginning. As your projects grow, you'll encounter more complex situations that require additional tools and strategies. Here's a preview of what lies ahead.

What You Learned Today	What Comes Next
Conflicts in a single text file with clear markers	Conflicts across multiple files in a single merge, where changes in one file depend on changes in another
Editing conflict markers manually in a text editor	Using visual merge tools (VS Code's built-in tool, Beyond Compare, Meld) to compare versions side by side
Two-way conflicts (yours vs. theirs)	Three-way merges that also show the common ancestor—the original version both branches started from
Resolving conflicts during `git merge`	Resolving conflicts during `git rebase`, `git cherry-pick`, and pull request workflows
Text-based conflicts in .js files	Binary file conflicts (images, compiled assets) and `package-lock.json` conflicts

Intro vs. advanced merge conflict skills

Don't worry about mastering all of these right away. The foundation you're building now—understanding markers, reading both sides, choosing a resolution, and committing—applies to every type of merge conflict you'll ever encounter. More advanced scenarios just add layers of context, but the core process remains the same.

SECTION 9

Practice Problems

Question 1: CONCEPTUAL

Explain in your own words why Git cannot automatically resolve a merge conflict. What specific condition must be true for a conflict to occur?

Show answer

Git cannot automatically resolve a merge conflict because two branches have modified the same lines in the same file. Git is excellent at combining changes that are in different parts of a file—for example, if one branch edits line 5 and another edits line 20, Git merges them automatically. However, when both branches change the same line, Git has no way to know which version the developer intended to keep. The specific condition for a conflict is: two branches that share a common ancestor commit have both modified overlapping lines in the same file.

Question 2: BASIC CALCULATION

Given the following conflict in a file called greeting.js, write out exactly what the file should look like after resolving the conflict by accepting the incoming (their) change:

<<<<<<< HEAD
const msg = "Hello, World!";
=======
const msg = "Welcome aboard!";
>>>>>>> feature-welcome

Show answer

After accepting the incoming change, the file should contain only one line: const msg = "Welcome aboard!"; All three conflict marker lines (<<<<<<< HEAD, =======, and >>>>>>> feature-welcome) must be completely removed. The HEAD version ("Hello, World!") is also removed because we chose to accept the incoming change.

Question 3: INTERMEDIATE

You encounter this conflict in styles.js:

const styles = {
<<<<<<< HEAD
  color: "navy",
  background: "white",
=======
  color: "teal",
  background: "black",
>>>>>>> dark-theme
  padding: 10,
};

You decide you want the color from the dark-theme branch ("teal") but the background from your branch ("white"). Write the resolved file.

Show answer

The resolved file should look like this:

const styles = {
  color: "teal",
  background: "white",
  padding: 10,
};

This is a "combine both" resolution. You took the color value from the incoming branch and the background value from your branch. All conflict markers are removed, and the padding: 10 line was never part of the conflict so it stays unchanged. The file is now valid JavaScript.

Question 4: APPLIED

You're working on a group project with three classmates. You all use Git and GitHub. After running git merge, you see conflicts in two files: index.js and utils.js. However, you're not sure what your classmate intended with their changes to utils.js. Describe the steps you would take and the Git commands you would use.

Show answer

First, resolve the conflict in index.js since you understand both sides: open the file, choose the correct resolution, remove the markers, and run git add index.js. For utils.js, you should contact your classmate to discuss their intent before making changes. If you need to pause the entire merge, run git merge --abort to undo everything and return to your pre-merge state. Once you've discussed with your classmate, re-run the merge and resolve both files. Alternatively, you could resolve index.js, leave utils.js unresolved, communicate with your teammate, then resolve it—you don't have to abort the whole merge just because one file is tricky.

Question 5: CRITICAL THINKING

A student says, "Merge conflicts are bad and should be avoided at all costs. If your team gets a conflict, something went wrong." Do you agree or disagree? Explain your reasoning and suggest at least two practices that could reduce (but not eliminate) the frequency of merge conflicts.

Show answer

This statement is a common misconception. Merge conflicts are a normal, healthy part of collaborative development—they mean that multiple people are actively contributing to the same codebase. Conflicts aren't a sign that something went wrong; they're simply a signal that two people had overlapping ideas that need human judgment to reconcile. That said, you can reduce their frequency with good practices. First, communicate with your team about who's working on which files, so you naturally minimize overlap. Second, merge frequently—if you let your branch drift far from the main branch, you accumulate more potential conflicts. Small, frequent merges mean smaller, easier-to-resolve conflicts. Other strategies include keeping pull requests small and focused, dividing work into separate files or modules when possible, and pulling the latest changes from the main branch before starting new work.

SUMMARY

Lesson Summary

Summary

A merge conflict occurs when two branches modify the same lines of the same file and Git cannot automatically determine which version to keep. Git marks the conflicted area with three conflict markers: <<<<<<< HEAD (start of your changes), ======= (divider), and >>>>>>> branch-name (end of their changes). To resolve a conflict, you read both versions, decide which code to keep—using strategies like accept yours, accept theirs, combine both, or rewrite—then delete all marker lines and finalize with git add and git commit.

Merge conflicts are a normal part of collaboration, not a sign of failure. The key skills are understanding the conflict marker format, reading both sides carefully, and making an intentional decision about the final code. With practice, resolving conflicts becomes a quick and routine part of your Git workflow.