SoftwareSideHustles
How-To

How to Resolve Git Merge Conflicts (Step by Step, Without Panic)

What conflict markers mean, a calm step-by-step process for resolving merge and rebase conflicts, choosing ours or theirs, handling lockfiles, and settings that make conflicts easier to read.

By Software Side Hustles Editorial Team · Published · Updated · 4 min read

Quick answer: run git status to see the conflicted files, open each one, edit the section between <<<<<<< and >>>>>>> so it contains the code you actually want, delete the markers, then git add <file> and finish with git commit (for a merge) or git rebase --continue (for a rebase). If it goes wrong, git merge --abort or git rebase --abort puts everything back.

Why merge conflicts happen

Git merges automatically when two branches change different parts of a file. A conflict happens only when both branches changed the same lines (or one deleted a file the other edited), and Git cannot know which version is correct. A conflict is a question, not an error: "both of you edited this — what should it say now?"

Reading conflict markers

text
<<<<<<< HEAD
const timeout = 5000;
=======
const timeout = Number(process.env.TIMEOUT_MS ?? 3000);
>>>>>>> feature/configurable-timeout
  • Between <<<<<<< HEAD and ======= is your current branch's version.
  • Between ======= and >>>>>>> feature/... is the incoming version.

The right answer is often neither side as written but a combination — here, perhaps Number(process.env.TIMEOUT_MS ?? 5000), keeping the configurability from one side and the new default from the other.

Show the original too (diff3 / zdiff3)

bash
git config --global merge.conflictStyle zdiff3

This adds a third section showing what the code looked like before either branch changed it:

text
<<<<<<< HEAD
const timeout = 5000;
||||||| 3f2a1bc
const timeout = 3000;
=======
const timeout = Number(process.env.TIMEOUT_MS ?? 3000);
>>>>>>> feature/configurable-timeout

Now you can see that one branch changed the value and the other made it configurable — so the right resolution keeps both changes. Without the base, you are guessing intent. (zdiff3 needs Git 2.35 or later; use diff3 on older versions.)

Step-by-step: resolving a merge conflict

  1. See what conflicted.
    bash
    git status
    Files under "Unmerged paths" need attention.
  2. Open each file and search for <<<<<<<. Most editors (VS Code, JetBrains IDEs) highlight conflicts and offer "Accept current / incoming / both" buttons. Use them as a starting point, not an answer.
  3. Understand both changes. Look at the commits: git log --merge -p <file> shows the commits on both sides that touched the conflicted file.
  4. Edit to the correct final code and remove every marker line.
  5. Check for leftovers: git diff --check flags leftover conflict markers.
  6. Build and run the tests. A conflict-free file can still be wrong — for example, if one branch renamed a function and the other added a new call to the old name.
  7. Mark resolved and finish.
    bash
    git add src/config.js
    git commit # merge
    # or
    git rebase --continue # rebase

Taking one side completely

When you know one version is right for a whole file:

bash
git checkout --ours path/to/file # keep your branch's version
git checkout --theirs path/to/file # keep the incoming version
git add path/to/file

Warning: during a rebase, "ours" and "theirs" are swapped. A rebase replays your commits on top of the target branch, so "ours" is the branch you are rebasing onto and "theirs" is your work. Many people have discarded their own changes by forgetting this.

Lockfile conflicts (package-lock.json, yarn.lock, poetry.lock)

Do not hand-edit lockfiles. Resolve the manifest (package.json) first, then regenerate the lockfile:

bash
git checkout --theirs package-lock.json # take either version as a base
npm install # regenerates it to match package.json
git add package.json package-lock.json

The same approach works for yarn install, pnpm install and poetry lock. Generated files in general — compiled assets, snapshots, schema dumps — should be regenerated, not merged by hand.

Merge or rebase?

  • Merge (git merge main) records a merge commit and resolves all conflicts once.
  • Rebase (git rebase main) replays your commits one at a time, so you may resolve conflicts several times — once per commit that touches the same lines — but the result is a linear history.

Turn on rerere ("reuse recorded resolution") to have Git remember how you resolved a conflict and apply the same resolution automatically next time:

bash
git config --global rerere.enabled true

How to get fewer conflicts

  • Merge or rebase from main often. Small, frequent integrations produce small conflicts.
  • Keep pull requests small. A two-day branch conflicts less than a two-week one.
  • Separate formatting from logic. Reformatting a whole file in the same PR as a feature guarantees conflicts for everyone else. Agree on an auto-formatter and run it everywhere.
  • Avoid "append to the end" hotspots — central route lists, changelogs, registries — or structure them so additions land in different places.

Frequently asked questions

How do I cancel a merge with conflicts?

git merge --abort returns to the state before the merge started. For a rebase, git rebase --abort. For a cherry-pick, git cherry-pick --abort.

How do I see which files have conflicts?

git status, or git diff --name-only --diff-filter=U for just the file names.

I committed a file with conflict markers in it. What now?

Fix the file, commit the fix, and add a check: git diff --check in a pre-commit hook, or a CI step that searches for lines starting with <<<<<<<.

Should I resolve conflicts in the GitHub web editor?

It works for simple text conflicts, but you cannot run the tests there. For anything involving code logic, resolve locally.

Where this skill pays off

Resolving a conflict well means understanding two people's intent and producing code that honours both — the same reasoning used to compare two AI-generated solutions and decide which is better. If you're good at it, see how preference ranking works in AI evaluation, work developers are paid for on the side.

Cookies on this site

We use essential cookies to run the questionnaire, practice labs and sign-in. With your permission we'd also like to use analytics to understand which pages help people, and advertising cookies to measure our Google Ads. Rejecting never limits any feature. Cookie policy