Git Merge Conflicts Resolution Tutorial: 7 Essential Fixes That Actually Work

Getting stuck on a Git merge conflict and panicking? You’re not alone. A Git merge conflicts resolution tutorial is exactly what junior developers need when branches collide and files show those scary conflict markers. This guide walks you through every scenario—from simple two-line fixes to complex multi-file disasters—so you never corrupt your codebase or lose work again.

What Is a Merge Conflict (And Why It’s Not Your Fault)

A merge conflict occurs when you try to combine two branches in Git, and both branches have modified the same lines in the same file differently. Git is smart but not psychic—it can’t guess which change you want.

Here’s the real-world analogy: Imagine you and a colleague both edit the same section of a shared document. One of you changes “Our mission is to build software” to “Our mission is to build fast software.” The other changes it to “Our mission is to build reliable software.” When you try to combine your edits, Git stops and asks: “Which one should I keep? Or do you want both?”

This isn’t a sign you’re doing something wrong. Even senior developers hit merge conflicts daily, especially in teams using feature branches (a common practice where each developer works on a separate code branch).

Quick Wins: Try These First (30 Seconds Each)

Before diving into detailed fixes, try these fast solutions:

1. View the Conflict with git status

git status

This shows you which files have conflicts. Files listed as “both modified” need your attention.

2. Abort the Merge (If You Panicked)

git merge --abort

This resets everything and takes you back to before the merge started. Use this if you need to take a breath and plan your approach.

3. Accept One Side Completely

git checkout --ours filename.js  # Keep your changes
git checkout --theirs filename.js  # Keep the other branch's changes
git add filename.js
git commit -m "Resolved merge conflict"

Use this only if one side is completely correct and the other should be discarded entirely.

Git Merge Conflicts Resolution Tutorial: The Complete Step-by-Step Method

This is the detailed process most developers follow when conflicts need careful handling:

Step 1: Identify the Conflicted File

git status

Look for files marked as “both modified” or “both added.” Open one of these files in your editor.

Step 2: Read the Conflict Markers

Inside the file, you’ll see conflict markers that look like this:

<<<<<<< HEAD
Your changes go here
=======
Their changes go here
>>>>>>> branch-name

The section between <<<<<<< and ======= is your current branch (HEAD). The section between ======= and >>>>>>> is the branch you’re merging in.

Step 3: Choose Your Resolution

You have four options:

• Keep only your changes: Delete the “their” section and all markers.
• Keep only their changes: Delete the “your” section and all markers.
• Combine both: Keep both sections and remove the markers. This is common when both sides added useful code.
• Write something new: Delete everything in the conflict markers and write a fresh solution that incorporates logic from both sides.

Step 4: Remove Conflict Markers

Make sure you delete all <<<<<<<, =======, and >>>>>>> lines. Leaving even one marker behind will cause the merge to fail.

Step 5: Stage and Commit

git add filename.js
git commit -m "Resolved merge conflict in filename.js"

Don’t add other changes to this commit—keep it focused on the merge resolution.

Problem: Multiple Files Have Conflicts

When git status shows five or ten conflicted files, take a structured approach:

git status | grep "both modified"

This filters the list to only conflicted files. Resolve them one at a time in order of complexity—easiest first, hardest last. This builds momentum and prevents decision fatigue.

For each file, use the Step-by-Step Method above. After resolving each file, run git add filename immediately. When all files are resolved, commit once with a message like: “Resolved merge conflicts from feature-branch merge.”

Problem: Conflict in Binary Files (Images, PDFs)

Binary files—like images, PDFs, or compiled code—can’t be merged by hand. You can’t edit conflict markers in a JPG or PDF. When this happens, you must choose one version entirely:

git checkout --ours image.png    # Keep your version
git checkout --theirs image.png  # Keep their version
git add image.png

If you need to build AI-ready documents from conflicted files, consider restructuring how PDFs and other documents flow through your merge process—for example, storing them in a separate branch or using Git LFS (Large File Storage).

Problem: One Branch Deleted a File, the Other Modified It

This is a special merge conflict. Git asks: “Should I keep the file or delete it?”

If you want to keep the file (and the modifications):

git add filename.js

If you want to delete the file:

git rm filename.js

Then commit as normal.

Problem: Merge Conflict in JSON or Config Files

JSON conflicts are common in package.json, config.json, or settings.json. The conflict markers break JSON syntax, making the file invalid until resolved.

{
  “name”: “my-app”,
  “version”: “1.0.0”,
  <<<<<<< HEAD
  “dependencies”: { “react”: “^18.0.0” }
  =======
  “dependencies”: { “react”: “^17.0.0” }
  >>>>>>> feature-branch
}

For config files, merging usually means combining both sides (not picking one). Merge the dependencies or settings from both branches:

{
  “name”: “my-app”,
  “version”: “1.0.0”,
  “dependencies”: {
    “react”: “^18.0.0”,
    “other-lib”: “^1.2.0”
  }
}

Problem: Conflicts During git rebase

Rebasing is a different workflow from merging, but conflicts happen the same way. When rebase stops on a conflict, resolve it the same way as a merge:

git status                    # See which files conflict
# Fix the conflicts in your editor
git add filename.js
git rebase --continue         # Keep rebasing

If you want to cancel the rebase and start over:

git rebase --abort

Problem: You Committed Conflict Markers Accidentally

You resolved most of the merge, but accidentally committed a file that still has <<<<<<< markers in it. The code compiles or runs, but those markers are still there.

Fix it quickly:

git log --oneline -n 5         # Find the commit with the markers
git show bad-commit-hash:filename.js | grep "<<<<<<<"  # Verify
# Edit the file to remove the markers
git add filename.js
git commit --amend             # Redo the commit without adding a new one

If the commit is already pushed to a shared branch, follow your team’s process for fixing shared history (usually involving a new commit that removes the markers).

Advanced: Understanding Three-Way Merges

Git doesn’t just compare two branches—it compares three versions:

1. Base: The common ancestor of both branches (the last commit where they were together).
2. Ours: Your current branch (HEAD).
3. Theirs: The branch you’re merging in.

Git uses the base as a reference point. If only one side changed a line compared to the base, Git assumes that change is intentional and keeps it. If both sides changed the same line differently, Git stops and asks you.

Example: The base has “version: 1.0.0”. You changed it to “1.1.0” and they changed it to “2.0.0”. Since both sides differ from the base, Git flags it as a conflict. This is correct behavior—you need to decide which version or what the final version should be.

Advanced: Using Merge Tools

For complex conflicts, text editors alone aren’t enough. Use a graphical merge tool:

Visual Studio Code (Built-In)

VS Code shows conflict markers with inline buttons. Click “Accept Current Change,” “Accept Incoming Change,” or “Accept Both Changes.” This is the easiest method for most developers.

Configure a Custom Merge Tool

git config merge.tool meld    # Use Meld (free, cross-platform)
git mergetool

This opens the tool for each conflicted file. Other options include Kaleidoscope (Mac), Beyond Compare, and P4Merge.

Three-Way Merge in an Editor

git config merge.tool vimdiff
git mergetool

Opens a side-by-side view of both versions and the base, giving you full context.

Nuclear Option: When Nothing Else Works

If the merge is a disaster and you want to start over:

git merge --abort

This cancels the merge and returns your branch to its state before you ran git merge. You lose no work—your code is exactly as it was.

If you’ve already committed a bad merge, you can undo it with:

git revert -m 1 HEAD           # Undo the last commit (a merge commit)

This creates a new commit that reverses the merge. Your history shows both the merge and the revert, which is useful for tracking what happened.

Best Practices: Prevent Most Conflicts Before They Happen

The best way to handle merge conflicts is to avoid them in the first place. Here’s how:

1. Pull Before You Push

git pull origin main            # Get the latest changes
# Test your code
git push origin my-branch

If you pull before pushing, you’ll catch conflicts while they’re small and easy to resolve.

2. Keep Branches Short-Lived

Feature branches that exist for weeks are more likely to conflict. Aim for merges within 2-3 days of creation. Smaller, focused changes conflict less often.

3. Coordinate with Your Team

If two people are working on the same file, agree on who changes what. Use code review comments to flag potential conflicts early.

4. Use .gitignore Properly

Don’t commit files that change frequently (like package-lock.json or IDE settings). Generate them during builds instead. This eliminates a huge source of conflicts.

5. Rebase Instead of Merge (When Appropriate)

git rebase main                 # Instead of git merge main

Rebasing creates a linear history and can prevent some merge commits. However, never rebase commits that are already pushed to shared branches—this rewrites history and confuses teammates.

6. Use a Merge Strategy

git merge -X theirs main        # In case of conflict, auto-accept their changes
git merge -X ours main          # In case of conflict, auto-accept your changes

Use these only when you’re confident about which side should win. Usually, you want to resolve conflicts manually.

FAQ: Common Questions About Git Merge Conflicts

Q: Will a merge conflict delete my code?
A: No. Both versions are preserved in the conflict markers. Nothing is deleted automatically. You choose what to keep.

Q: Can I merge without conflict markers?
A: Only if the conflicts are resolved automatically. Git’s auto-merge works fine for most changes. Conflicts only appear when Git can’t decide automatically.

Q: Do I need to resolve all conflicts at once?
A: Yes. A merge isn’t complete until all files are resolved and committed. You can’t partially finish a merge.

Q: What’s the difference between merge and rebase?
A: Merge creates a commit that joins two branches. Rebase moves your commits on top of another branch. Merge is safer for shared branches; rebase is cleaner for local work.

Q: Can I undo a merge after committing?
A: Yes. Use git revert -m 1 HEAD to create a commit that undoes the merge. Or use git reset --hard HEAD^ to delete the merge commit (only if it’s not yet pushed).

Summary: Your Merge Conflict Action Plan

1. Run git status to see which files conflict.
2. Open the first conflicted file and find the conflict markers.
3. Decide: keep ours, keep theirs, combine both, or write something new.
4. Remove all <<<<<<<, =======, and >>>>>>> markers.
5. Run git add filename for each resolved file.
6. Commit once with a clear message: “Resolved merge conflicts.”
7. Test thoroughly before pushing.
8. For complex conflicts, use a merge tool like VS Code or Meld.
9. For the future, keep branches short, pull before push, and coordinate with your team.

Merge conflicts stop being scary once you understand that they’re just Git asking for clarification. You control the outcome entirely. Take your time, resolve one file at a time, and commit when done. Your codebase will be safe, and you’ll be faster next time.