gray and black laptop computer on surface

How to Resolve Git Merge Conflicts: A Step-by-Step Guide

Sooner or later, git merge or git pull stops with a message like CONFLICT (content): Merge conflict in app.js and Automatic merge failed; fix conflicts and then commit the result. It looks alarming, but nothing is lost. Git has simply found two changes to the same lines and wants you to choose. Once you know the routine, it’s quick to resolve Git merge conflicts by hand. Here’s that routine, step by step.

Why conflicts happen

Git merges most changes automatically. It only stops when both branches changed the same part of the same file, or when one branch edited a file the other deleted. It can’t know which version is right, so it marks the file as conflicted and leaves the decision to you. Everything that merged cleanly is already staged.

Step 1: see which files are conflicted

git status

Conflicted files are listed under Unmerged paths, usually marked both modified. If you only want the file names, for a script or a long list, use:

git diff --name-only --diff-filter=U

Step 2: read the conflict markers

Open a conflicted file and you’ll find blocks like this:

<<<<<<< HEAD
const timeout = 30;
=======
const timeout = 60;
>>>>>>> feature/slow-api

The part between <<<<<<< HEAD and ======= is your current branch. The part between ======= and >>>>>>> is the branch you’re merging in, named after the arrows. There can be several of these blocks in one file.

Step 3: edit the file to the version you want

For each block, decide what the code should be. You can keep your side, keep theirs, or write something that combines both. Then delete all three marker lines. For the example above, if the slow API really does need longer, the result is simply:

const timeout = 60;

Don’t just pick a side by reflex. Read both changes, because the right answer is often a mix. Search the file for <<<<<<< when you think you’re done, to make sure you haven’t missed a block. Run your tests too: a file can be free of markers and still not work.

Step 4: mark it resolved and finish the merge

Stage each file once it’s fixed. That’s how you tell Git it’s resolved:

git add app.js
git status

When git status shows no unmerged paths, complete the merge:

git commit

Git pre-fills a merge commit message. Save it, or add a line about how you resolved anything tricky. That note helps whoever reads the history later, quite possibly you.

Taking one whole side of a file

Sometimes you know a file should match one branch exactly, such as a lockfile or a generated file. You don’t have to edit markers by hand:

git checkout --ours package-lock.json     # keep your branch's version
git checkout --theirs package-lock.json   # keep the incoming branch's version
git add package-lock.json

For lockfiles, the cleanest fix is often to take either side and then regenerate it with your package manager (npm install, composer update --lock and so on) before staging.

Changed your mind? Abort

If the merge turns out to be bigger than you expected, or you want to start again, you can back out completely:

git merge --abort

That puts your branch back to how it was before the merge started. If you’ve already finished a merge and regret it, how to undo the last Git commit explains your options.

Conflicts during a rebase

A rebase replays your commits one at a time on top of another branch, so you may hit conflicts at more than one commit. The fix is the same (edit, then git add), but you continue with a different command:

git add app.js
git rebase --continue      # move on to the next commit
git rebase --skip          # drop this commit entirely
git rebase --abort         # give up and go back to where you started

One gotcha: during a rebase, --ours and --theirs are swapped. “Ours” is the branch you’re rebasing onto, and “theirs” is your own commit being replayed. It’s the opposite of a merge, and it catches everyone at least once.

Use a merge tool if you prefer

If reading markers in a text editor isn’t for you, git mergetool opens each conflicted file in a visual three-way merge tool. VS Code, JetBrains IDEs and most Git GUIs also have a conflict editor with “Accept Current” and “Accept Incoming” buttons, which is handy for big files. If you’re choosing a GUI, the best Git UI clients for 2026 compares the main options.

Make the next conflict easier

Two settings are worth turning on once:

git config --global merge.conflictStyle zdiff3
git config --global rerere.enabled true
  • zdiff3 (Git 2.35 and later) adds a third section to each conflict block, starting with |||||||, showing what the code looked like before either branch changed it. Seeing the original makes it much easier to tell what each side was trying to do.
  • rerere (“reuse recorded resolution”) remembers how you resolved a conflict and applies the same fix automatically if the identical conflict comes up again, which happens a lot when you rebase a long-running branch repeatedly.

Beyond that, the best prevention is small, frequent merges. Pull the main branch into your feature branch often, keep branches short-lived, and avoid reformatting whole files in the same branch as real changes. If you juggle several branches at once, Git worktrees let you keep each one checked out in its own folder.

The routine in short

  1. git status to list conflicted files
  2. Edit each file, choose the right code and delete the markers
  3. git add each fixed file
  4. git commit for a merge, or git rebase --continue for a rebase
  5. git merge --abort or git rebase --abort if you want out

Leave a Reply