Skip to content

Merge Conflicts

Resolving merge conflicts step by step — understanding conflict markers and resolution strategies.

What you'll learn

  • How to read and understand conflict markers
  • Step-by-step conflict resolution workflow
  • Using merge tools and aborting conflicts
  • Strategies to minimize conflicts in the first place

Concept

What Is a Merge Conflict?

A merge conflict occurs when two branches change the same lines of the same file and Git cannot determine which version to keep. Git pauses the merge and asks you to resolve the conflict manually.

git merge feature-branch
# Auto-merging login.js
# CONFLICT (content): Merge conflict in login.js
# Automatic merge failed; fix conflicts and then commit the result.

Conflicts are normal and nothing to fear — they happen every day in team development.

Conflict Markers

Git marks the conflicting section in the file:

function login(user) {
<<<<<<< HEAD
  const token = generateToken(user);
  return { token, user };
=======
  const session = createSession(user);
  return { session, user };
>>>>>>> feature-branch
}
  • <<<<<<< HEAD — your current branch's version (the one you are merging INTO)
  • ======= — the separator
  • >>>>>>> feature-branch — the incoming branch's version (the one you are merging FROM)

The Resolution Workflow

  1. Identify the conflicts: git status shows files with conflicts as "both modified"
  2. Open each conflicted file and find the <<<<<<< markers
  3. Edit the file to keep the correct version (or combine both)
  4. Remove the conflict markers (<<<<<<<, =======, >>>>>>>)
  5. Stage the resolved file: git add <file>
  6. Complete the merge: git commit (or git merge --continue)

Choosing the Resolution

You have several options for each conflict:

  • Keep your version (HEAD) — delete the incoming code and markers
  • Keep their version (incoming) — delete your code and markers
  • Combine both — merge the logic from both versions
  • Write something new — replace the entire conflicted section

For simple conflicts, you can use checkout to choose a side:

git checkout --ours conflicted-file.js    # keep our version
git checkout --theirs conflicted-file.js  # keep their version
git add conflicted-file.js

Using a Merge Tool

Configure and use a visual merge tool for complex conflicts:

git config --global merge.tool vscode
git mergetool

VS Code, IntelliJ, and other editors have excellent visual merge tools that show three panels: yours, theirs, and the result.

Aborting a Merge

If you are not ready to resolve conflicts:

git merge --abort

This cancels the merge and returns to the pre-merge state. You can always try again later.

Minimizing Conflicts

  • Pull frequently — keep your branch up to date with main
  • Communicate with your team — avoid editing the same files simultaneously
  • Keep commits small and focused — smaller changes mean smaller conflicts
  • Use feature branches — isolate work to reduce overlap
  • Rebase before merging — git pull --rebase keeps your branch linear

Verifying the Resolution

After resolving, always verify your code works:

git add .
git commit  # complete the merge
# Run your tests to make sure nothing broke
npm test

Never complete a merge without testing that the combined code actually works.

Example

              # Simulate a conflict: two branches change the same line
git checkout -b feature-a
echo "Version A" > config.txt
git commit -am "feat: set config to version A"

git checkout main
echo "Version B" > config.txt
git commit -am "feat: set config to version B"

# Now merge — this will conflict
git merge feature-a
# CONFLICT (content): Merge conflict in config.txt

# See which files have conflicts
git status
# both modified:   config.txt

# Open config.txt — it now contains:
# <<<<<<< HEAD
# Version B
# =======
# Version A
# >>>>>>> feature-a

# Edit the file to resolve — keep one or combine:
echo "Version A and B combined" > config.txt

# Stage the resolved file
git add config.txt

# Complete the merge
git commit -m "merge: resolve config.txt conflict"

# --- Alternative: keep one side entirely ---
git merge another-branch
git checkout --ours config.txt   # keep our version
git add config.txt
git commit

# --- If overwhelmed, abort ---
git merge --abort

# --- Use a visual merge tool ---
git mergetool

# After resolving, verify everything works
npm test
            

Simulates a conflict by having two branches change the same file, shows the conflict markers, resolves by editing the file, stages and commits. Also shows the --ours/--theirs shortcuts, aborting, and using a merge tool. Always run tests after resolving conflicts.

Try it

  • Code Diff

    Compare conflicting versions side by side to decide the resolution.

  • .gitignore Generator

    Keep generated files out of Git to reduce merge conflicts.

Common mistakes

The mistake

Leaving conflict markers in the file and committing them

The fix

After resolving a conflict, search for <<<<<<<, =======, and >>>>>>> markers in your files before committing. These markers must all be removed. Run git diff --staged to verify the final state, and always run your tests after resolving.

The mistake

Panicking at a conflict and force-resetting, losing work

The fix

Conflicts are normal. If you are not ready, run git merge --abort to safely cancel and return to the pre-merge state. Never use git reset --hard to escape a conflict — it can lose uncommitted work. Take your time, resolve one file at a time, and test afterward.

Related Cheatsheets

Practice Merge Conflicts

2 exercises

Practice Merge Conflicts

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors