How to Fix Divergent Branches in Git (Fast-Forward Errors)

Both the "you have divergent branches" message and the "fatal: not possible to fast-forward, aborting" error mean the same thing: your local branch and the remote branch have each received new commits independently, so a simple fast-forward is impossible and Git needs to know how to reconcile them. To fix it for a single pull, use git pull --rebase to replay your local commits on top of the remote's (producing a clean linear history) or git pull --no-rebase to create a merge commit joining both lines of development. To configure a permanent default and silence the message for all future pulls, run git config --global pull.rebase true (for rebase) or git config --global pull.rebase false (to always allow merge commits). The "fatal: not possible to fast-forward" variant appears specifically when your pull strategy is set to --ff-only, which refuses to proceed when a fast-forward is not possible. Most modern teams prefer the rebase strategy for a cleaner history, but the important thing is to be consistent within your team. To diagnose the divergence, run git log --graph --oneline --all -10 to visualise both sides.

Git FAQ

Frequently asked questions around Git and Version Control.

How to Fix Divergent Branches and Fast-Forward Errors in Git

When you try to pull the latest changes, you may run into one of two closely related messages. The first is a prompt asking how to proceed:

$ git pull
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 pull --rebase
hint:   git pull --no-rebase
hint:   git pull --ff-only
fatal: Need to specify how to reconcile divergent branches.

The second is a harder stop:

$ git pull origin main
fatal: not possible to fast-forward, aborting.

Despite the different wording, both mean exactly the same thing: your local branch and the remote branch have diverged — each side has commits the other doesn't have, so Git can't simply fast-forward.

Why Does This Happen?

This is a normal part of collaborative work. Here's a typical scenario:

You clone a repository and start working on the main branch.
While you're working, a colleague pushes new commits to main on the remote.
Now your local main and the remote main have diverged. When you try to pull, Git can't just add the remote changes on top of yours — it needs you to decide how to combine the two histories.

The difference between the two error variants is your pull configuration: the "divergent branches" prompt appears when no default strategy is set; the "not possible to fast-forward" error appears when your strategy is set to --ff-only, which refuses to proceed unless a fast-forward is possible.

The Git Cheat Sheet

No need to remember all those commands and parameters: get our popular "Git Cheat Sheet" - for free!

How to Fix It

You have two main strategies: merge or rebase. You can apply either as a one-time fix or configure it permanently.

The One-Time Fix

To resolve the current pull, pass a strategy flag explicitly:

git pull --rebase — performs a rebase. Your local commits are set aside, the remote changes are pulled, and then your commits are re-applied on top. This produces a clean, linear history.
git pull --no-rebase — performs a merge. Git fetches the remote changes and creates a new merge commit tying both histories together.

The Permanent Fix: Configuring Your Pull Strategy

To stop seeing this message altogether, set a global default:

Always rebase:
```
git config --global pull.rebase true
```
Popular with teams that prefer a clean, linear commit history.
Always merge:
```
git config --global pull.rebase false
```
Creates an explicit merge commit on every divergent pull — preferred by teams that want a clear record of when branches were integrated.
Fast-forward only (strictest):
```
git config --global pull.ff only
```
Refuses to pull if a fast-forward isn't possible, forcing you to fetch and merge/rebase manually. This is what produces the "not possible to fast-forward" error when set as the default.

Which Strategy Should You Choose?

Rebasing produces a cleaner, easier-to-read history — as if all work happened in a straight line.
Merging preserves the exact record of what happened, including when branches diverged and were joined.

Most teams prefer rebasing for day-to-day syncing with the remote. The important thing is to be consistent: once you pick a global configuration, you'll have a predictable workflow.

Diagnosing the Divergence

To see exactly what's on each side before you decide, run:

git log --graph --oneline --all -10

This shows the last 10 commits across all branches in a graph, making the divergence immediately visible. You can also check each side individually:

git log HEAD..origin/main      # commits on remote that you don't have
git log origin/main..HEAD      # your local commits not yet on remote