How to Fix “Need to Specify How to Reconcile Divergent Branches”

Git reports divergent branches when your local branch and its upstream each have commits the other does not. Recent Git versions may ask you to choose how git pull should integrate those histories. Fetch and inspect the changes, then choose merge, rebase, or fast-forward-only based on your team’s workflow.

What does “divergent branches” mean?

The local branch and its upstream have moved forward independently. One may contain local commits while the other contains commits fetched from a teammate or hosting service. Git needs a policy for bringing the histories together because a pull can either create a merge commit, replay local commits on top of the remote, or refuse unless the update can fast-forward.

The message is a request to choose a policy, not proof that your work is lost. Avoid resetting or force-pushing just to silence it.

Step 1: Check your branch and working tree

Confirm the branch, working tree, and upstream before integrating anything:

git status
git branch -vv
git remote -v

If you have uncommitted changes, commit or safely save them first. Confirm that the upstream shown for your branch is the one you intended to update.

Step 2: Fetch and inspect the commits

Fetch updates without changing your working files, then inspect the commit graph:

git fetch
git log --oneline --graph --decorate --all -20

This helps confirm which commits are local and which came from the remote. Choose a pull strategy only after confirming the branch and reviewing the history.

Choose a strategy for this pull

Merge the histories

Use merge when you want to preserve both branch histories as-is and your project accepts merge commits:

git pull --no-rebase

Rebase local commits on top of the upstream

Use rebase when your team prefers a linear history and your local commits have not been shared. Rebase rewrites those local commit identities:

git pull --rebase

Allow only a fast-forward

Use fast-forward-only when you want Git to update the branch only if no merge commit or rebase is needed. It will refuse when histories have diverged:

git pull --ff-only

Set a default pull strategy

If you want one strategy to apply consistently, set it for all your repositories or only the current repository. These commands choose a policy; use the option that matches your project:

git config --global pull.rebase false   # merge
git config --global pull.rebase true    # rebase
git config --global pull.ff only       # fast-forward only

To apply a setting only in the current repository, omit --global. These are alternatives; do not copy all three lines as one configuration. For a one-time decision, use an option on git pull instead of changing your defaults.

Resolve conflicts or cancel safely

If a merge or rebase stops for conflicts, edit each conflicted file, resolve the marked sections, and stage the resolved files. For a rebase, continue with git rebase --continue; for a merge, complete it as Git instructs. If you need to abandon the operation, use git rebase --abort during a rebase or git merge --abort during a merge.

After integration completes, inspect the result before pushing:

git status
git log --oneline --graph -10

Common mistakes to avoid

• Do not use git reset --hard as a generic fix; it can discard local work.
• Do not force-push a shared branch to resolve a pull strategy prompt. Integrate and coordinate with collaborators.
• Do not rebase commits that others already rely on unless your team explicitly coordinates that history rewrite.
• If the eventual push is rejected as non-fast-forward, follow the non-fast-forward push troubleshooting guide.