You have divergent branches and need to specify how to reconcile them

Git’s “divergent branches” error appears when git pull finds local and remote branches have diverged and Git 2.27+ refuses to guess how to combine them.

What It Means

Since Git 2.27 (July 2020), git pull without a configured strategy warns and fails when branches have diverged — your local branch has commits the remote doesn’t, and the remote has commits you don’t have locally. Git 2.27 changed the default pull mode from “merge” to a warning that requires explicit configuration. This prevents accidental merge commits or unexpected rebases.

Why It Happens

• You upgraded to Git 2.27+ and ran git pull on a branch with divergent history.
• No pull.rebase or pull.ff is configured in your Git config.
• Someone else pushed to the remote branch while you were working locally.
• You have unpushed commits and the remote has new commits.
• Your branch was rebased on the remote (e.g., after a squash merge).

How to Fix It

Step 1: Configure your preferred pull strategy (one-time fix)

To use merge (the traditional behavior):

git config --global pull.rebase false

To use rebase (keeps a linear history):

git config --global pull.rebase true

To use fast-forward only (fails if a merge is needed):

git config --global pull.ff only

Step 2: Run git pull with an explicit strategy

If you haven’t configured a global setting, specify the strategy per command:

# Merge (creates a merge commit)
git pull --no-rebase

# Rebase (replays your commits on top of remote)
git pull --rebase

# Fast-forward only (fails if divergence exists)
git pull --ff-only

Step 3: Update the default pull mode for Git 2.27+

Set the default behavior globally with git config --global pull.default:

# To restore pre-2.27 behavior (merge):
git config --global pull.default merge
# Or set pull.rebase as shown in Step 1

Step 4: Fetch and inspect before pulling

git fetch origin
git log --oneline HEAD..origin/main  # What's in remote but not locally
git log --oneline origin/main..HEAD  # What's local but not in remote

Step 5: Manually merge or rebase

If you prefer to control the process step by step:

git fetch origin
git log --oneline origin/main
git merge origin/main
# Or
git rebase origin/main