git pull: You have divergent branches and need to specify how to reconcile them

You ran git pull and instead of pulling, git stopped with a long hint about divergent branches and three config commands. Nothing is broken: your branch and the remote both have commits the other lacks, and git wants you to pick how to combine them.

The message

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.

Since Git 2.27 (and as a hard stop since 2.33), git pull refuses to guess when a fast-forward is impossible. Older versions silently made a merge commit, which is why many people only see this after upgrading Git.

What “divergent” means

      A---B---C   origin/main   (someone else pushed B and C)
     /
D---E---F---G     main          (you committed F and G)

Both sides moved on from E. Git can stitch them together with a merge commit, or by replaying F and G on top of C (a rebase). Neither is wrong; they just leave different history.

See exactly what diverged

git fetch
git status                         # "have 2 and 2 different commits each"
git log --oneline --graph --left-right HEAD...@{u}
#  < = only yours,  > = only on the remote

If the “yours” side is something you did not mean to commit (an experiment on main), stop and move it to a branch first: git branch my-experiment, then git reset --hard @{u} on main. Only do the reset once you are sure the work is safe on the new branch.

Choose a strategy

Drop --global to set it for the current repository only. A reasonable default for most people is pull.rebase true together with rebase.autoStash true, which stashes uncommitted changes around the rebase automatically.

If the rebase hits a conflict

git status                 # shows the conflicted files
# fix the files (remove the <<<<<<< ======= >>>>>>> markers)
git add path/to/file
git rebase --continue
# changed your mind?
git rebase --abort         # back to exactly where you were

The markers are explained in git merge conflict markers. Pasting “ours” and “theirs” side by side into the text diff tool makes a big conflict easier to read.

Do not reach for --force

If you rebased commits that were already pushed, the next push will be rejected as non-fast-forward. Use git push --force-with-lease, which refuses if someone else pushed in the meantime, and only on branches nobody else builds on. On a shared main, prefer the merge strategy instead. More on that in git push rejected (non-fast-forward).

Related

local changes would be overwritten by merge · git push rejected (non-fast-forward) · git merge conflict markers · refusing to merge unrelated histories · git detached HEAD · src refspec main does not match any

Questions

Published 5 November 2026.