Push & pull problemsAlways fixable

Fix 'Need to specify how to reconcile divergent branches'

git pull says I need to specify how to reconcile divergent branches — what do I choose?

Short answer

Git 2.27+ refuses to guess whether you want a merge or a rebase when both sides have new commits. Pick one — git config --global pull.rebase true gives you clean linear history and is the best default for most people.

quick fix
git config --global pull.rebase true
git pull

Set rebase as your permanent pull strategy, then pull normally

Does this match your situation?

  • 'hint: You have divergent branches and need to specify how to reconcile them.'
  • 'fatal: Need to specify how to reconcile divergent branches.'
  • The hint mentions pull.rebase, pull.ff and pull.merge.

Step-by-step fix

  1. Understand what you're choosing between

    Both branches gained commits since they diverged, so Git has to combine them somehow. Rebase replays your commits on top of theirs, producing a straight line. Merge keeps both sequences and joins them with a merge commit. Neither loses work.

    step 1
    # rebase:  ...--A--B--C(theirs)--Y'--Z'   (your commits replayed, new hashes)
# merge:   ...--A--B--C(theirs)-----M         (M has two parents)

  2. Set a global default — rebase is the usual pick

    Linear history is easier to read, bisect and revert, and it avoids the merge commits that clutter a log when everyone syncs several times a day. Set it once and never see the message again.

    step 2
    git config --global pull.rebase true

  3. Or choose merge, or refuse to guess at all

    Merge preserves the exact shape of what happened, which some teams prefer. ff-only is the most conservative: it refuses to pull whenever a real integration is needed, so you always decide consciously.

    step 3
    git config --global pull.rebase false   # always merge
git config --global pull.ff only        # refuse unless fast-forward

    pull.ff only is a great safety setting — you'll run an explicit merge or rebase when it stops you.

  4. Override for a single pull

    The flags work per-command too, so you can keep a global default and deviate when a particular branch needs it.

    step 4
    git pull --rebase
git pull --no-rebase
git pull --ff-only

Why this works

For years git pull silently merged, which quietly filled shared repositories with 'Merge branch main of ...' commits that nobody intended to create. Git 2.27 made the choice explicit rather than defaulting to the option most people didn't want. The warning isn't an error in your repository — it's Git declining to make a structural decision about your history on your behalf.

How to stop it happening again

  • Configure pull.rebase (or pull.ff only) once on every machine you use.
  • Pull before you start working, so divergence stays small.
  • Use --autostash with rebase so uncommitted work isn't in the way: git config --global rebase.autoStash true.

Commands used in this guide

git pull

Fetch from the remote and immediately integrate the changes into your branch.

git config

Read and write Git settings for one repo, your user, or the whole machine.

git rebase

Replay your commits on top of another branch to produce a straight, linear history.

git merge

Combine another branch's history into the current one.

Still stuck?

Search the full command reference and every other rescue guide — there are 56 of them, covering everything from detached HEAD to force-push disasters.

Browse all guides →

Frequently asked questions

Should I set pull.rebase to true or false?

True for most people: it keeps history linear and avoids pointless merge commits from routine syncing. Set it to false if your team prefers history to show exactly when each sync happened, or if several people share the same branch and rebasing would rewrite commits they already have.

What does pull.ff only do?

It makes git pull succeed only when it can fast-forward — that is, when you have no local commits of your own. Any real divergence stops with an error, so you consciously run git merge or git rebase. It's the safest setting if you dislike surprises.

Is rebasing on pull dangerous?

Not for your own unpushed commits — that's exactly what it's designed for. It's only a problem if you rebase commits that other people have already pulled, which routine pulling of your own local work never does.

Related rescue guides

Always fixable

My push was rejected — 'Updates were rejected because the remote contains work that you do not have'. What now?

Someone pushed commits you don't have yet, so your push would erase them. Git is protecting you. Fetch and integrate their work first with git pull --rebase, then push again. Never reach for --force here unless you genuinely intend to delete what's on the server.

Read the fix →Always fixable

How do I undo a git pull?

A pull is a fetch plus a merge or rebase, so undoing it means moving your branch back to where it was. git reset --hard ORIG_HEAD does exactly that, because Git saves your pre-pull position there automatically.

Read the fix →Always fixable

Git won't let me pull because of local changes — how do I fix it?

Git is refusing to overwrite uncommitted edits to files the incoming commits also change. Commit them, stash them, or discard them — stashing is the reversible choice and takes one command.

Read the fix →Always fixable

Git says I have merge conflicts — how do I fix them?

Git pauses and marks the clashing sections with <<<<<<<, ======= and >>>>>>>. Edit each file to the version you actually want, delete the markers, git add the file, then git merge --continue. If it gets overwhelming, git merge --abort returns you to exactly where you started.

Read the fix →
← All Git Rescue guides