Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 78 ยท Branching and Merging

Resolving Merge Conflicts

Learn why Git merge conflicts happen, how to read conflict markers, resolve them by hand, with --ours and --theirs, abort a merge, and reuse fixes with rerere.

Sooner or later, Git will stop in the middle of a merge and say CONFLICT. New users often feel they broke something. They did not. A merge conflict is Git being honest: two people changed the same part of the same file in different ways, and Git cannot know which version is right. It leaves the decision to you, marks the problem spots in the file, and waits.

Conflicts are a normal part of teamwork, and resolving them is a skill with a clear routine. This lesson explains exactly when conflicts happen, how to read the markers Git writes, three ways to resolve them, how to back out safely with --abort, and how to avoid repeating the same fix with rerere. Make sure you know how a normal merge works first.

When does a conflict happen?

Git compares each branch with the merge base (their last common commit). If only one side changed a region, Git takes that change. If both sides changed the same lines, or one side edited lines the other side deleted, Git cannot choose, and that is a conflict. Changes in different parts of a file merge cleanly even when both branches touched that file.

TEXT
base:      color = "red"
main:      color = "blue"       (changed)
feature:   color = "green"      (changed the same line)
                                  โ”€โ”€โ–ถ CONFLICT: blue or green?

Other kinds of conflict exist too: one branch deletes a file the other edited, or both add a file with the same name but different content. The routine below is the same for all of them.

A conflict, step by step

The next example creates a file with a setting, then changes the same line on two branches. Run it and look at what the merge prints and what the file looks like afterwards.

Bash Cause a conflict and read the markers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Git printed CONFLICT (content): Merge conflict in config.txt and Automatic merge failed; fix conflicts and then commit the result. The merge is now in progress: Git has staged everything it could merge and left the conflicting file for you. git status -s shows UU config.txt, where UU means "unmerged, modified by both". (Other codes you may see: AA both added, DU deleted by us, UD deleted by them.)

Inside the file, Git wrote conflict markers around the disputed lines:

TEXT
<<<<<<< HEAD
color = blue
=======
color = green
>>>>>>> feature
  • Everything between <<<<<<< HEAD and ======= is your side, the branch you are on (HEAD, here main).
  • Everything between ======= and >>>>>>> feature is their side, the branch you are merging in.
  • Lines outside the markers merged cleanly and need no attention (title and size above).

Resolving by editing

The classic method needs no special tools:

  1. Open each conflicted file (git status lists them under "Unmerged paths", or run git diff --name-only --diff-filter=U).
  2. Decide what the final text should be: ours, theirs, a mix, or something new. Delete all three marker lines and any lines you do not want.
  3. Save the file and run git add file to tell Git "this one is resolved".
  4. When no unmerged paths remain, run git commit to finish the merge. Git prepares a message like Merge branch 'feature'.
Bash Resolve by editing, then finish the merge

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Notice that we did not choose either original value: Git does not care what you write, only that the markers are gone and you ran git add. After the commit the history shows the usual diamond-shaped merge commit.

Never commit conflict markers. The compiler or parser will usually choke on them, but in plain text, Markdown or JSON-like config they can slip through. Before git add, search for leftovers: grep -rn '^<<<<<<<\|^>>>>>>>' . or run git diff --check, which flags markers and whitespace problems.

Taking one whole side: --ours and --theirs

Sometimes the answer is simply "use their file" or "keep mine". For a whole file, use git checkout --ours or --theirs (the newer git restore --ours / --theirs also works), then git add.

Option Meaning during a merge
--ours The version from the branch you are on (the receiving branch)
--theirs The version from the branch you are merging in

During a rebase the meaning flips: the "ours" side is the branch you are rebasing onto and "theirs" is your own commit being replayed. This surprises everyone once. See Rebasing.

To apply a preference to every conflict in the whole merge, pass a merge option when you start: git merge -X ours feature or -X theirs. This resolves only the conflicting hunks in your favor; non-conflicting changes from both sides are still merged. It is quick, but it quietly throws away decisions, so use it deliberately.

Bash Choose a side per file with --ours and --theirs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

We kept a-main (ours) and took b-feature (theirs). After staging, only b.txt shows in the status (M ), because the resolved a.txt is identical to the commit on main, so it differs from nothing. The checkout lines print Updated 1 path from the index, because Git rebuilds the working file from the stored versions. Those versions exist because a conflicted path is stored in the index in three numbered "stages": stage 1 is the common ancestor, stage 2 is ours and stage 3 is theirs. git show :1:file, :2:file and :3:file print them, and git diff --ours / --theirs compare your file with each side. The index internals are explained in The Index, Packfiles and Garbage Collection.

Seeing more context: diff3 style

The default markers show only two versions. With three, including the original, you can usually see what each person meant. Turn it on once:

INI
[merge]
	conflictstyle = zdiff3

(git config --global merge.conflictstyle zdiff3; diff3 is the older variant, zdiff3 trims the repeated lines at the edges.) Conflicts then gain a third part between ||||||| and ======= that shows the base version. In our example it would show color = red, which immediately explains that both sides changed the original red.

Backing out: git merge --abort

If the conflicts are bigger than expected, or you started the merge by mistake, you can undo it. git merge --abort restores the state from just before the merge began, as long as you had no uncommitted changes when you started.

Bash Abort a merge and get back to a clean state

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

During the merge Git keeps the second parent in .git/MERGE_HEAD; that file is how commands know a merge is unfinished. After --abort, f.txt is back to main and the status is clean. The same escape exists for other multi-step commands: git rebase --abort, git cherry-pick --abort and git revert --abort.

If you have already run git add on some files, you can still abort. If you have committed the merge and then regret it, that is no longer an abort; use git reset --hard ORIG_HEAD right after the merge (only if you have not pushed), or revert the merge commit.

Merge tools

git mergetool launches a visual three-way merge program (VS Code, Meld, IntelliJ, vimdiff...) configured with merge.tool. It is interactive and needs a graphical or terminal editor, so it cannot run on this page; here is how you would use it on your own machine:

CONSOLE
$ git config --global merge.tool vscode
$ git mergetool

Git opens each conflicted file in the tool in turn and, after you save, stages it and keeps a .orig backup (turn that off with git config --global mergetool.keepBackup false). Many people instead resolve conflicts directly in their IDE, which does the same job with a nicer interface. Pick whichever you read most easily; the result in the file is the same.

Remembering resolutions with rerere

"Reuse recorded resolution" (rerere) is a little-known feature that saves you from solving the same conflict twice. It is useful when you repeatedly rebase a long-lived branch, or when you merge, regret it and try again. Once enabled, Git records how you resolved each conflict and, when the same conflict appears, applies your earlier answer automatically.

Bash rerere replays a resolution the second time

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The second merge prints Resolved 'c.txt' using previous resolution. and writes color = teal without asking. The file is still marked as unmerged, so you review it, git add it and commit. Git stores the recorded fixes under .git/rr-cache. Enable it everywhere with git config --global rerere.enabled true. Check the reused result before committing; rerere remembers, it does not understand.

Habits that prevent conflicts

You cannot eliminate conflicts, but you can make them small and rare:

  • Merge or rebase from main often into long-lived branches, so differences never grow large.
  • Keep branches and commits small and short-lived; see Branch Management and Cleanup.
  • Do not reformat whole files in a feature commit. A formatting sweep touches every line and conflicts with everyone.
  • Talk to teammates when two of you will edit the same area, and split big files into smaller modules.
  • Avoid editing generated files (lock files, compiled output) by hand; regenerate them after the merge instead of resolving them line by line.
  • Run the tests after resolving. A conflict-free text merge can still be a broken program, and a hand-resolved merge is where logic mistakes happen.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In a merge conflict, what is between <<<<<<< HEAD and =======?

    The top part is HEAD (your side, the branch you are on). The part after ======= up to >>>>>>> is the incoming branch.
  2. 2. You fixed a conflicted file by editing it. What must you do before you can commit the merge?

    git add tells Git the file is resolved. When no unmerged paths remain, git commit (or git merge --continue) finishes the merge.
  3. 3. What does git merge --abort do?

    --abort cancels an in-progress merge and returns the branch, index and working tree to how they were before git merge was run.
  4. 4. Which command takes the whole file from the branch you are merging in?

    --theirs selects the incoming branch's version during a merge. Afterwards you still need git add. Note that the meaning is reversed during a rebase.
  5. 5. What does rerere do?

    rerere stands for reuse recorded resolution. It saves your fixes in .git/rr-cache and replays them for identical conflicts.

Summary

  • A conflict means both sides changed the same lines (or one deleted what the other edited); Git stops the merge and asks you.
  • Markers: <<<<<<< your side, ======= divider, >>>>>>> their side. Remove all marker lines before staging.
  • Resolve: edit the file, git add it, then git commit. Use git status to see what is still unmerged.
  • git checkout --ours/--theirs file takes a whole side; -X ours/-X theirs prefers a side only for conflicting hunks. The meanings flip during a rebase.
  • git merge --abort returns you to the state before the merge; merge.conflictstyle zdiff3 shows the base version too.
  • Enable rerere to reuse past resolutions, and keep branches short and up to date to avoid conflicts.

Next: Branch Management and Cleanup