FlowingDev

Merge Conflicts, explained: Untangling code when two worlds collide

Learn how merge tools reconcile two different versions of a file, combining changes line by line to create a single, unified result without losing work.

Try the tool: Merge Tool

In one sentence

A merge tool helps you intelligently combine changes from two different versions of a file into a single, unified result, letting you act as the tie-breaker when changes overlap.

The problem it solves

Picture this: it’s 1995. You and a colleague are working on the same HTML file for your company's hot new GeoCities page. You're adding a sick <marquee> tag, and they're adding a guestbook. You both save your changes to the shared network drive. The problem? Whoever saves last completely overwrites the other person's work. The marquee is gone. Tears are shed. Friendships are tested.

This was the chaotic reality of collaborative work before modern version control. The "solution" was a messy ballet of shouting across the office ("I'm in contact.html! Don't touch it!") or creating a jungle of filenames like contact_v2_final_jennifer_edits_FINAL.html. It was, to put it mildly, a dumpster fire.

Version Control Systems (VCS) like Git, Subversion, and Mercurial were created to solve this. They allow multiple people to work on the same codebase, on their own copies, and then merge their changes back together.

But this creates a new, more interesting problem. What happens when you and your colleague both edit the exact same line of code? The VCS can't read your minds. It doesn't know if your change is more important than theirs. It throws up its digital hands and declares a merge conflict. This is where the merge tool enters the scene. It’s the calm, patient negotiator that sits down with both versions of the file and helps you, the developer, decide how to create a single, harmonious final version.

How it works under the hood

A merge tool isn't just a simple side-by-side text viewer. It's powered by some clever algorithms that have been refined for decades. The magic is in how it understands change relative to a common starting point.

The Secret: A Three-Way Merge

You might think a merge tool just compares your-file.js and their-file.js. Nope! That's a two-way comparison, which is what a simple "diff" tool does. A true merge tool performs a three-way merge.

It looks at three files:

  1. MINE (or LOCAL): Your version of the file, with your changes.
  2. THEIRS (or REMOTE): The other version of the file you're trying to merge in.
  3. BASE (or ANCESTOR): The original version of the file, from before either of you made your changes.

The BASE is the key. The tool doesn't just ask "Are these files different?" It asks, "How did MINE change from BASE?" and "How did THEIRS change from BASE?" This context is everything.

Here’s the logic it follows for every chunk of the file:

Did MINE change from BASE? Did THEIRS change from BASE? The Tool's Action
No No Nothing to do. The chunk is identical.
Yes No Auto-merge: Takes the change from MINE.
No Yes Auto-merge: Takes the change from THEIRS.
Yes Yes Conflict! Both sides changed the same chunk. Human intervention is required.

This three-way approach allows the tool to automatically resolve all the easy stuff, leaving you to focus only on the actual conflicts where you and another developer had the same idea (or a conflicting one) at the same time.

The Anatomy of a Diff "Hunk"

Under the hood, merge tools are running a diff algorithm (like the classic Hunt–McIlroy algorithm) to find the differences. These differences are grouped into "hunks." A hunk is a contiguous block of the file where changes occurred.

When you see a conflict in a raw text file (before opening a visual tool), it looks like this mess:

<<<<<<< HEAD
// MINE: I think this is a better comment
function calculateTotal(price, quantity) {
=======
// THEIRS: Add tax calculation
function calculateTotal(price, quantity, taxRate) {
>>>>>>> feature-branch
  // ... function body
}
  • <<<<<<< HEAD: Marks the beginning of the conflicting chunk from your current version (MINE). HEAD is Git's name for your current branch.
  • =======: The separator. Everything between the top marker and here is MINE. Everything between here and the bottom marker is THEIRS.
  • >>>>>>> feature-branch: Marks the end of the conflicting chunk from the other branch you're merging (THEIRS).

A visual merge tool parses this format and presents it in a much friendlier side-by-side or three-pane view, replacing the ugly markers with helpful colors and buttons.

Resolving the Clash

When a conflict occurs, the merge tool presents the MINE and THEIRS versions of the hunk. You are the ultimate authority. You can:

  • Choose MINE: Discard their change and keep yours.
  • Choose THEIRS: Discard your change and keep theirs.
  • Edit the result manually: This is the most powerful option. You can take a piece of their change and a piece of your change and craft a new, correct version. For example, you might take their new function parameter but keep your improved comment.

Once you've resolved every conflicting hunk, the tool helps you build and save the final, unified file, ready to be committed back to version control.

Real-world stories

The Case of the Overlapping Refactor

Two developers, Anya and Ben, are working on an e-commerce checkout. Anya is on a feature branch to add gift card support, modifying the calculatePrice function. Ben, on a separate bug-fix branch, discovers a flaw in the same function and refactors it for correctness.

When Anya tries to merge Ben's fix into her branch, Git screams "CONFLICT!" on calculatePrice. She opens a merge tool. On the left (MINE), she sees her version with the new giftCardAmount parameter. On the right (THEIRS), she sees Ben's heavily refactored, but correct, logic. Simply choosing one side would be wrong—she'd either lose gift card support or re-introduce the bug. Using the merge tool's editor, she manually integrates her giftCardAmount logic into Ben's new, refactored function structure.

Lesson: A merge conflict isn't a failure; it's a conversation. The tool provides the context for you to combine two different, but equally valid, goals into a single correct solution.

The Last-Minute Config Shuffle

The team is scrambling for a production release. On the main branch, the lead dev just updated config.yml to use the production database credentials. Simultaneously, a junior dev, working on a hotfix branch, changed a logging level from INFO to DEBUG in the same config.yml to diagnose an urgent issue.

The hotfix must be merged into main before deployment. A merge conflict arises. The merge tool shows the two changes are on different lines. The database change is on line 10, and the logging change is on line 25. Because the changes don't overlap, the tool's three-way merge algorithm identifies this and automatically combines them. The lead dev just glances at the proposed result in the tool, sees both changes are present and correct, and approves it with a single click.

Lesson: Merge tools prevent catastrophic mistakes. Without it, a developer might have blindly accepted one version, accidentally deploying a hotfix pointed at the production database or, worse, deploying the main branch with debug logging still enabled.

The README Refresh

It's not just for code! Two technical writers are updating the project's README.md. One is completely rewriting the "Installation" section to be clearer. The other is adding a brand new "Code of Conduct" section at the end of the file. Since they're working in different parts of the document, the merge tool automatically combines their work flawlessly, creating a single README.md with both a better installation guide and the new Code of Conduct.

Lesson: Any plain text file under version control—documentation, configuration, scripts, prose—benefits from merge tooling.

Common mistakes and traps

  • Blindly picking a side. The most common error is to see a conflict and just click "Accept Ours" or "Accept Theirs" without understanding the context. This is how features get reverted and bugs get re-introduced. Always read both sides.
  • Forgetting the manual edit. Many conflicts aren't an either/or choice. The correct resolution is often a combination of both changes. Don't be afraid to dive into the result pane and edit the code by hand to get it right.
  • Ignoring whitespace changes. Sometimes a conflict is just a matter of tabs vs. spaces or different indentation. While it seems trivial, it's best to resolve it consistently. If your project has a linter or formatter, run it on the file after merging to clean up any mixed styles.
  • Manually "resolving" conflicts in a text editor. Seeing the <<<<<<< and >>>>>>> markers and trying to delete them by hand is playing with fire. It is incredibly easy to accidentally delete a real line of code or leave one of the markers in, which will break your application or build script. Let a tool do the parsing.
  • Resolving generated files. If a file like package-lock.json or a minified CSS bundle has a conflict, you're usually better off aborting the merge, regenerating the file from its source (e.g., by running npm install), and then re-attempting the merge. Resolving these by hand is a nightmare.

Why it belongs on your radar

If you write code, documentation, or configuration as part of a team (even a team of two!), you will encounter merge conflicts. It’s an unavoidable, normal part of collaborative development.

Fearing merge conflicts is a sign of a junior developer. Understanding that they are a solvable problem is a mark of experience. Mastering a merge tool turns a moment of panic into a routine 5-minute task. It transforms the dreaded "CONFLICT" message from a roadblock into a simple signpost that says, "Hey, you and a teammate had a great idea in the same place. Take a look and make it even better."

Go deeper

Theory done. Time to get your hands dirty — 100% in your browser.

Try the tool: Merge Tool