Resolving merge conflicts in Git - Deep Dive

Overview - Resolving merge conflicts

What is it?

Resolving merge conflicts is the process of fixing differences that happen when two people change the same part of a file in Git. When Git cannot automatically combine these changes, it stops and asks you to decide which changes to keep. This ensures that the final code is correct and everyone’s work fits together.

Why it matters

Without resolving merge conflicts, teams cannot safely combine their work, leading to broken code or lost changes. It helps keep projects organized and prevents mistakes that could cause software to fail. Resolving conflicts is essential for smooth teamwork and reliable software delivery.

Where it fits

Before learning this, you should understand basic Git commands like commit, branch, and merge. After mastering conflict resolution, you can learn advanced Git workflows, rebasing, and continuous integration practices.

Mental Model

Core Idea

Merge conflicts happen when Git can’t automatically combine changes, so you must manually choose how to merge them.

Think of it like...

It’s like two people editing the same paragraph in a shared document at the same time; the software can’t decide which edits to keep, so it asks you to pick the final version.

┌───────────────┐      ┌───────────────┐
│ Branch A      │      │ Branch B      │
│ (Your changes)│      │ (Other changes)│
└──────┬────────┘      └──────┬────────┘
       │                      │
       │                      │
       └───────┬──────────────┘
               │ Merge attempt
               ▼
       ┌─────────────────────┐
       │ Merge Conflict       │
       │ <<<<<<< HEAD         │
       │ Your changes here    │
       │ =======             │
       │ Other changes here   │
       │ >>>>>>> branch-name │
       └─────────────────────┘

Build-Up - 7 Steps

1

Foundation

What is a merge conflict

Concept: Introduce the basic idea of a merge conflict in Git.

When you try to combine two branches in Git, sometimes both branches change the same lines in a file. Git can’t decide which change to keep, so it stops and marks the file as conflicted. This is called a merge conflict.

Result

Git shows a message about conflicts and marks files as conflicted, stopping the merge.

Understanding what a merge conflict is helps you know why Git needs your help to combine changes safely.

2

Foundation

How Git marks conflicts in files

Concept: Learn how Git shows conflicts inside files.

Git adds special markers inside the conflicted file: - <<<<<<< HEAD marks your branch’s changes - ======= separates your changes from the other branch’s - >>>>>>> branch-name marks the other branch’s changes You edit between these markers to fix the conflict.

Result

You see clear conflict markers in the file showing both versions side by side.

Knowing the conflict markers lets you find exactly where changes clash and what your options are.

3

Intermediate

Manual conflict resolution steps

🤔Before reading on: do you think you must keep all changes, or can you choose only some? Commit to your answer.

Concept: Learn how to manually fix conflicts by editing files.

Open the conflicted file in a text editor. Look for the conflict markers. Decide which changes to keep: - Keep your changes - Keep the other branch’s changes - Combine both changes logically Remove the conflict markers after editing. Save the file. Then run 'git add ' to mark it resolved.

Result

The conflict is fixed in the file, and Git knows you resolved it.

Understanding manual resolution empowers you to control exactly how code merges, avoiding mistakes.

4

Intermediate

Using Git commands to manage conflicts

🤔Before reading on: do you think 'git merge --abort' deletes your work or just cancels the merge? Commit to your answer.

Concept: Learn Git commands to handle conflicts safely.

When conflicts happen: - Use 'git status' to see conflicted files. - Use 'git diff' to view differences. - After fixing, use 'git add' to mark resolved. - Use 'git commit' to finish the merge. - If stuck, 'git merge --abort' cancels the merge and restores the previous state.

Result

You can safely navigate conflicts and undo merges if needed.

Knowing these commands prevents confusion and data loss during conflict resolution.

5

Intermediate

Using merge tools for conflict resolution

🤔Before reading on: do you think merge tools automate conflict fixes or just help visualize? Commit to your answer.

Concept: Learn how graphical merge tools help resolve conflicts.

Git supports external merge tools like 'meld', 'kdiff3', or IDE built-ins. Run 'git mergetool' to open a visual tool showing both versions and the base. You can click to choose changes or edit directly. After saving, Git marks the conflict resolved.

Result

Conflicts are easier to understand and fix with visual help.

Using merge tools reduces errors and speeds up resolving complex conflicts.

6

Advanced

Strategies to avoid frequent conflicts

🤔Before reading on: do you think smaller, frequent merges reduce conflicts or increase them? Commit to your answer.

Concept: Learn best practices to minimize conflicts in teams.

To avoid conflicts: - Merge or rebase frequently to keep branches updated. - Communicate with teammates about overlapping work. - Use feature toggles to integrate incomplete work safely. - Keep changes small and focused. - Use code reviews to catch potential conflicts early.

Result

Teams experience fewer conflicts and smoother merges.

Knowing how to prevent conflicts saves time and frustration in real projects.

7

Expert

Advanced conflict resolution with rebase and cherry-pick

🤔Before reading on: do you think rebasing always avoids conflicts or can it cause new ones? Commit to your answer.

Concept: Explore how rebasing and cherry-picking affect conflicts.

'git rebase' reapplies your changes on top of another branch, which can cause conflicts that must be resolved similarly. 'Rebase' creates a cleaner history but requires careful conflict handling. 'git cherry-pick' applies specific commits and can also cause conflicts. Understanding these helps manage complex workflows and keep history clean.

Result

You can handle conflicts in advanced Git workflows confidently.

Mastering conflict resolution in rebasing and cherry-picking unlocks powerful Git usage for professional teams.

Under the Hood

Git stores snapshots of files as commits. When merging, Git tries to automatically combine changes by comparing the common ancestor commit with both branches. If changes overlap on the same lines, Git cannot decide which to keep, so it marks a conflict. The conflict markers are inserted directly into the file to show both versions. Git waits for the user to edit and resolve these conflicts before completing the merge.

Why designed this way?

Git was designed to be a distributed system where many people work independently. Automatic merging works most of the time, but when it fails, Git must involve the user to avoid losing work. Showing conflict markers inside files is a simple, universal way to highlight conflicts without special tools. This design balances automation with user control.

┌───────────────┐
│ Common Ancestor│
└──────┬────────┘
       │
       │ Changes in Branch A
       ▼
┌───────────────┐
│ Branch A      │
└──────┬────────┘
       │
       │ Merge attempt
       ▼
┌───────────────┐
│ Git Merge     │
│ Conflict?     │
└──────┬────────┘
       │ Yes
       ▼
┌─────────────────────┐
│ Conflict Markers in  │
│ File (manual fix)    │
└─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does resolving a merge conflict mean you must keep all changes from both branches? Commit to yes or no.

Common Belief: You must keep all changes from both branches when resolving conflicts.

Reality: You can choose to keep only one side’s changes or combine them logically; you don’t have to keep everything.

Why it matters: Believing you must keep all changes can lead to bloated or broken code and confusion about the final result.

Quick: Does 'git merge --abort' delete your committed work? Commit to yes or no.

Common Belief: 'git merge --abort' deletes all your work and resets the branch.

Reality: 'git merge --abort' cancels the current merge attempt and restores the branch to the state before the merge started, preserving your commits.

Why it matters: Misunderstanding this can cause fear of using abort and lead to messy manual fixes or lost time.

Quick: Does rebasing always prevent merge conflicts? Commit to yes or no.

Common Belief: Rebasing always avoids merge conflicts because it reapplies commits cleanly.

Reality: Rebasing can cause conflicts just like merging, especially if changes overlap; you must resolve them similarly.

Why it matters: Thinking rebasing avoids conflicts leads to surprise and confusion when conflicts still appear.

Quick: Can merge conflicts happen only in code files? Commit to yes or no.

Common Belief: Merge conflicts only happen in source code files.

Reality: Conflicts can happen in any text file tracked by Git, including documentation, configuration, or scripts.

Why it matters: Ignoring conflicts in non-code files can break builds or deployments unexpectedly.

Expert Zone

1

Conflicts can be semantic, not just textual; even if Git merges cleanly, the combined code might not work logically.

2

The order of applying patches in rebasing affects conflict complexity and resolution strategy.

3

Some merge tools support three-way merges using the common ancestor to better visualize changes and reduce errors.

When NOT to use

Manual conflict resolution is not ideal for very large or binary files; in such cases, use specialized merge drivers or avoid merging those files. Also, avoid rebasing public branches to prevent rewriting shared history.

Production Patterns

Teams use feature branches with frequent merges or rebases to minimize conflicts. Automated CI pipelines run tests after merges to catch semantic issues. Merge tools integrated into IDEs speed up conflict resolution during code reviews.

Connections

Version Control Systems

Builds-on

Understanding merge conflicts deepens your grasp of how version control systems manage parallel work and history.

Collaborative Writing

Same pattern

Resolving merge conflicts is like resolving editing conflicts in shared documents, highlighting universal challenges in teamwork.

Conflict Resolution in Negotiation

Analogous process

Both require understanding different perspectives and finding a compromise that fits all parties’ needs.

Common Pitfalls

#1 Ignoring conflict markers and committing files as-is.

Wrong approach:

git add conflicted_file.txt
git commit -m "Merge with conflicts"

Correct approach:

Edit conflicted_file.txt to remove conflict markers and fix code
then:
git add conflicted_file.txt
git commit -m "Resolved merge conflict"

Root cause:

Not understanding that conflict markers must be removed and conflicts fixed before committing.

#2 Running 'git merge --abort' after manually fixing conflicts without staging changes.

Wrong approach:

Fix conflicts in files but do not run 'git add'
Then run:
git merge --abort

Correct approach:

Fix conflicts, run 'git add ' for all resolved files
Then run:
git commit

Root cause:

Misunderstanding that 'git merge --abort' cancels the merge and discards manual fixes if not staged.

#3 Trying to resolve conflicts by deleting one side blindly without understanding changes.

Wrong approach:

Delete all lines between <<<<<<< and ======= without review
Remove markers and save.

Correct approach:

Carefully review both sides, combine or choose changes logically
Remove markers and save.

Root cause:

Rushing conflict resolution without understanding the impact of changes.

Key Takeaways

Merge conflicts occur when Git cannot automatically combine changes to the same lines in files.

Git marks conflicts inside files with clear markers showing both versions for manual resolution.

Resolving conflicts requires careful editing, choosing which changes to keep or combine.

Using Git commands and merge tools helps manage conflicts safely and efficiently.

Preventing conflicts through frequent merges and communication improves team productivity.