Git Fix: fatal: Need to specify how to reconcile divergent branches

What Causes This Error

When you run git pull, Git fetches the latest commits from the remote and tries to integrate them into your local branch. If both your local branch and the remote branch have commits the other doesn’t have, the branches have diverged. Git doesn’t know which strategy you want to use to merge them, so it stops and asks you to decide:

hint: You have divergent branches and need to specify how to reconcile them.
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
fatal: Need to specify how to reconcile divergent branches.

A typical diverged state looks like this:

          A---B  (your local commits)
         /
...---X---Y---Z  (remote commits)

---

Three Ways to Fix It

Option 1: Rebase (Recommended for feature branches)

git pull --rebase

Your local commits are replayed on top of the remote’s latest commit, resulting in a clean linear history with no extra merge commits.

...---X---Y---Z---A'---B'
                  (your commits, rebased)

Best for: Personal feature branches, keeping history clean and readable.

---

Option 2: Merge (Creates a merge commit)

git pull --no-rebase

Both sets of commits are preserved, and Git creates a new merge commit to join them together.

          A---B
         /     \
...---X---Y---Z---M  (merge commit)

Best for: Shared branches where you want to preserve the full history of parallel work.

---

Option 3: Fast-forward Only (Most conservative)

git pull --ff-only

Git only proceeds if your local branch has no extra commits (i.e., it can simply move the branch pointer forward). If the branches have diverged, this will fail with an error rather than creating any merge or rebase.

Best for: Situations where you want to guarantee no unintended changes are introduced locally.

---

Set a Permanent Default (Recommended)

To avoid this error in every future git pull, configure a global default strategy once:

# Recommended: always rebase
git config --global pull.rebase true

# Or: always merge
git config --global pull.rebase false

# Or: always fast-forward only
git config --global pull.ff only

This writes your preference to ~/.gitconfig and applies to all repositories on your machine.

See also: Mastering the Linux Command Line — Your Complete Free Training Guide

---

Diagnose the Divergence First

Before choosing a strategy, it helps to see exactly what diverged:

# Show the diverged commits on both sides
git log --oneline --graph HEAD origin/$(git branch --show-current)

Example output:

* cc5e7f1 (HEAD -> my-branch) my local commit
| * 36788aa (origin/my-branch) remote commit
|/
* c2a9f17 common ancestor

This tells you:

• How many local commits need to be rebased or merged
• Whether there is a risk of conflicts

---

Which Option Should You Choose?

Situation	Recommended Strategy
Personal feature branch	--rebase
Shared team branch	--no-rebase (merge)
CI/CD or automated pipelines	--ff-only
You accidentally committed locally and want to discard	git fetch + git reset --hard origin/<branch>

---

Quick Reference

# One-time fix with rebase
git pull --rebase

# One-time fix with merge
git pull --no-rebase

# Set rebase as your global default forever
git config --global pull.rebase true