Git Reference ยท Configuration Options
pull.rebase and pull.ff settings
Reference for pull.rebase, pull.ff and pull.twohead: choose whether git pull merges, rebases or refuses when your branch and its upstream have diverged.
git pull is a fetch followed by an integration step. When the remote branch has moved ahead and you also have local commits, the histories have diverged and Git must pick a strategy: merge, rebase, or stop. The settings pull.rebase and pull.ff make that choice once so you are not asked every time.
Since Git 2.33, a plain git pull on diverged branches without any of these settings fails with a message asking you to decide. That is the situation these options exist to solve.
git config --global pull.rebase true # replay local commits on top git config --global pull.rebase false # merge (classic behavior) git config --global pull.ff only # refuse anything but a fast-forward
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git config pull.rebase (true | false | merges | interactive) git config pull.ff (true | false | only) git config pull.twohead <strategy> git config pull.octopus <strategy>
| Name | Description |
|---|---|
pull.rebase = true |
After fetching, rebase local commits onto the upstream instead of merging. |
pull.rebase = false |
Merge the upstream into the current branch (creates a merge commit when diverged). |
pull.rebase = merges |
Rebase while preserving local merge commits (--rebase-merges). |
pull.rebase = interactive |
Rebase with the todo list opened for editing. |
pull.ff = only |
Allow only fast-forwards; stop with an error when the branches diverged. |
pull.ff = false |
Always create a merge commit, even when a fast-forward is possible (like --no-ff). |
pull.twohead, pull.octopus |
Default merge strategy for one or several remote heads. |
Precedence: the command-line flags --rebase, --no-rebase, --ff-only override everything; branch.<name>.rebase overrides pull.rebase; pull.rebase overrides pull.ff for the rebase decision.
Errors: with pull.ff=only, diverged branches end with fatal: Not possible to fast-forward, aborting.. Without any setting, Git 2.33 and later stops with fatal: Need to specify how to reconcile divergent branches..
Usage notes
- A fast-forward is never a problem. If you have no local commits, every setting except
pull.ff=falsejust moves the branch forward. pull.rebase=truekeeps history linear but rewrites your unpublished local commits (new hashes). That is safe only for commits nobody else has based work on.- Merge commits from pulls clutter history. Many teams choose
pull.rebase=trueorpull.ff=onlyplus an explicitgit rebaseso merges happen only for real integration. - Uncommitted changes block a rebase pull unless you also set
rebase.autoStashor pass--autostash. - Per-branch override: use
branch.<name>.rebasewhen only some branches should rebase. - Values
preservewas removed; usemerges. - Safer habit:
git fetchthen inspect withgit log HEAD..@{u}before integrating.