Resolve Divergent Branches

Happens when your local branch and the remote branch both have commits the other doesn’t — usually because someone else (or another session/tool) pushed to the branch after your last pull, and you’ve also committed locally in the meantime. git pull refuses and asks you to pick a strategy.

The error

hint: You have divergent branches and need to specify how to reconcile them.
fatal: Need to specify how to reconcile divergent branches.

Check what’s actually different first

git fetch origin main
git log origin/main..HEAD --oneline   # commits you have that remote doesn't
git log HEAD..origin/main --oneline   # commits remote has that you don't

Fix: rebase your commits on top

Best when your local commits are small/simple (e.g. a trigger commit, a quick fix) — replays them cleanly after the remote’s history instead of creating a merge commit.

git pull --rebase origin main
git push origin main

Rebase, step by step

What each command does, in the order you’d run them. Swap in your own branch for <branch>.

git status                       # modified, untracked, or mid-rebase?
git add <file>                   # stage by name; `git add .` stages everything
git commit -m "my changes"       # save work locally BEFORE pulling anyone else's
git log --oneline -n 5           # confirm the commit exists
git branch backup-before-rebase  # cheap undo: a second pointer at this commit
 
git fetch origin
git log --oneline HEAD..origin/<branch>   # what the remote has that you don't
 
git pull --rebase origin <branch>

pull --rebase downloads the remote commits, sets your local commits aside, and replays them on top of the new ones, with no extra merge commit.

If a replayed commit conflicts, Git stops and git status lists the conflicted files:

git diff                         # shows the conflict markers from both sides
# edit the file, keep what you want, delete every <<<<<<< ======= >>>>>>> line
git add <file>                   # "I've resolved this one"
git rebase --continue            # replay the next commit; repeat per conflict

Ways out:

git rebase --skip     # drop the commit being replayed (only if you no longer need it)
git rebase --abort    # cancel and return to exactly where you started

When it finishes cleanly:

git push origin <branch>

Still tangled? See Diagnose and Recover from Branch Collisions.

Fix: merge instead

Better when you want an explicit merge commit, or rebase produces conflicts you’d rather resolve in a merge:

git pull --no-rebase origin main
# resolve conflicts if any, then:
git add <resolved files>
git commit
git push origin main

Set a default so this doesn’t keep prompting

git config pull.rebase true    # always rebase on pull
# or
git config pull.rebase false   # always merge on pull

See also

• Diagnose and Recover from Branch Collisions — when a rebase has already conflicted or a commit seems to have gone missing.