Blog
3 min read

"You Have Divergent Branches" in git pull: What It Means and How to Fix It

"hint: You have divergent branches and need to specify how to reconcile them" means your local branch and the remote both have commits the other doesn't. What divergence is, the three options (merge, rebase, fast-forward only), which to pick, and how to set a default so git stops asking.

You run git pull and get:

hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
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.

Nothing is broken and nothing is lost. Git is asking you a question it used to answer silently.

What "divergent" means

Your branch and the remote branch started from the same commit, then both got new commits:

          A---B   (your local main)
         /
    ...--o
         \
          C---D   (origin/main)

Maybe you committed on your laptop while Claude Code or a teammate pushed from somewhere else. Git needs to know how to combine A B with C D.

The three options

1. Merge (pull.rebase false) — creates a merge commit joining both lines. Safe, keeps exact history, adds a "Merge branch 'main'" commit.

2. Rebase (pull.rebase true) — replays your commits on top of the remote ones, as if you'd written them after. Gives a straight, tidy history. (Git Rebase vs Merge)

    ...--o--C--D--A'--B'

3. Fast-forward only (pull.ff only) — updates your branch only if Git can move its pointer forward without a merge commit. It refuses when the histories have diverged. If your branch is already ahead of the remote, there may be nothing to pull.

Which should you pick?

For most people working on their own or in a small team: rebase. It keeps history readable and avoids a merge commit every time you pull.

Pick merge if your team prefers recording merges, or you're nervous about rebasing. Pick ff only if you never commit directly to the branch you're pulling (for example, you always work on feature branches and only pull main).

Fix it right now

Choose for this one pull:

git pull --rebase
# or
git pull --no-rebase

If a rebase or merge hits a conflict, git stops and tells you which files to fix. (Merge Conflicts Explained)

Set a default so git stops asking

For all your repositories:

git config --global pull.rebase true

For extra safety with rebase, also stash uncommitted changes automatically:

git config --global rebase.autoStash true

Don't reach for force-push

If you instead tried git push and it was rejected, the fix is the same: pull (with merge or rebase) first, then push. git push --force would delete the remote's C and D commits. (Git Push Rejected)

The summary

  • Divergent = you and the remote both have new commits.
  • Choose: merge, rebase, or fast-forward only.
  • git config --global pull.rebase true is a good default for most people.

EasySpawn works with GitHub as the home of your code, with Claude Code committing on branches from a persistent server — so pulls, rebases and conflicts get handled in one place. See how it works or join the waitlist.

Related: Git Fetch vs Pull · Your Branch Is Behind origin/main · Undo Almost Anything in Git · Git Branches Explained

Keep reading