Home › Git

fatal: Need to specify how to reconcile divergent branches. (Git) — how to fix

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
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches.

Quick fix: Choose once per pull with git pull --rebase (replay your commits on top) or git pull --no-rebase (merge commit). Set a default with git config --global pull.rebase true (or false). If you have no local commits worth keeping, reset instead: git fetch && git reset --hard origin/main.

What it means

git pull is git fetch followed by integrating origin/<branch> into your branch. When both sides have new commits the history has diverged:

      A---B---C   origin/main
     /
D---E---F---G     main (your local commits F, G)

Git can combine them in two ways — a merge commit, or rebasing F and G on top of C. Since Git 2.27 it warned when you hadn't picked a default, and since about Git 2.33.1 it refuses to pull until you do. Your work is untouched; no merge happened yet.

See what diverged:

git fetch
git log --oneline --graph main origin/main
git status          # "Your branch and 'origin/main' have diverged, and have 2 and 3 different commits each"

Fix 1: rebase your commits on top (linear history)

git pull --rebase

Your local commits are replayed after the remote ones. If a conflict appears, fix the files, then:

git add <file>
git rebase --continue      # or: git rebase --abort to go back

Don't rebase commits you have already pushed and others built on — that rewrites shared history.

Fix 2: merge (keeps both histories, adds a merge commit)

git pull --no-rebase

This is the old default behaviour. Resolve any conflicts, git add, then git commit.

Fix 3: set a default so the message stops

Pick one, globally or per repository (drop --global):

git config --global pull.rebase true    # always rebase
git config --global pull.rebase false   # always merge
git config --global pull.ff only        # refuse unless fast-forward is possible

pull.ff only is the safest: pulls that would create a merge or rebase stop with fatal: Not possible to fast-forward, aborting. and you decide case by case. Many people combine pull.rebase true with rebase.autoStash true so uncommitted changes are stashed automatically.

Fix 4: you don't need your local commits — reset to the remote

If the local commits are mistakes, or the remote was force-pushed (for example after someone rebased the branch), make your branch identical to the remote:

git fetch origin
git branch backup-before-reset       # optional safety net
git reset --hard origin/main

reset --hard discards local commits and uncommitted changes. The backup branch lets you recover them.

Fix 5: the remote has nothing you need — push instead

If the remote commits should be replaced by yours (e.g. you amended a commit you'd already pushed to your own feature branch):

git push --force-with-lease

--force-with-lease refuses to overwrite commits you haven't fetched. Never force-push to shared branches like main without agreement.

Which should I choose?

Situation Command
Personal feature branch, unpushed local commits git pull --rebase
Shared branch, team prefers merge commits git pull --no-rebase
You never commit on this branch locally git config pull.ff only
Local commits are junk / remote was rewritten git reset --hard origin/main

IDEs (VS Code, JetBrains) show the same error when their "Sync"/"Pull" button runs git pull; setting pull.rebase globally fixes them too.

Last updated 2026-11-16.