Fix - you have divergent branches in Git
How to Fix "You have divergent branches" Error
The "You have divergent branches" error is a Git warning, not a hard error that stops your operation. It appears when your local branch and the corresponding remote branch have both moved forward, creating a divergent history. Git is telling you that a simple fast-forward merge is not possible and you need to choose a strategy to reconcile the differences before your next git pull.
The error message itself provides the three main solutions: merge, rebase, or fast-forward only.
Merge (Safest for Shared Branches)
Using git config pull.rebase false tells Git to use a merge strategy when you pull. This is the default behavior for git pull and is the safest option for branches that are shared with other developers.
How it works: Git creates a new merge commit that combines the changes from both your local commits and the remote commits. This approach preserves the complete history of both branches.
When to use: When working on a shared branch where others have pulled your commits. This is the "golden rule of rebasing" in practice: don't rebase public history (3).
Command: To set this as your default for all repositories:
git config --global pull.rebase false
Or, for the current repository only:
git config pull.rebase false
After setting this, a regular git pull will perform a merge.
Rebase (For a Clean, Linear History)
Using git config pull.rebase true tells Git to use a rebase strategy. This is a powerful tool for maintaining a clean and linear commit history, as it avoids creating a merge commit.
How it works: Git takes your local commits and "replays" them on top of the fetched remote commits. This makes it look as if your local changes were made after the latest remote commits.
When to use: When working on a private, local feature branch that no one else has pulled. This keeps your branch history tidy before you open a pull request.
Command: To set this as your default for all repositories:
git config --global pull.rebase true
Or, for the current repository only:
git config pull.rebase true
After setting this, a regular git pull will perform a rebase.
Fast-Forward Only (For a Strict Workflow)
Using git config pull.ff only is a more restrictive option. It tells Git to only perform a fast-forward merge.
How it works:
This will only work if your local branch is a direct ancestor of the remote branch. If your branches have diverged, the git pull command will fail, forcing you to manually resolve the divergence using a different command, like git pull --rebase or git pull --no-ff.
When to use: When you want to enforce a very strict, linear workflow and prevent accidental merges that could clutter the commit history. This is often used in automated scripts or for highly controlled release branches.
Command: To set this as your default for all repositories:
git config --global pull.ff only
Or, for the current repository only:
git config pull.ff only
A better way to apply this locally without a config is to simply run git pull --ff-only (1).
Summary
The divergent branches warning is a "choose-your-own-adventure" moment in Git. The right choice depends entirely on your project's workflow and whether your branch is private or shared. For shared branches, merging is the safe default. For private branches, rebasing provides a cleaner history.