Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash The divergence error and its cures

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.

Bash Merge instead of rebase

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

Terminal
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=false just moves the branch forward.
  • pull.rebase=true keeps 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=true or pull.ff=only plus an explicit git rebase so merges happen only for real integration.
  • Uncommitted changes block a rebase pull unless you also set rebase.autoStash or pass --autostash.
  • Per-branch override: use branch.<name>.rebase when only some branches should rebase.
  • Values preserve was removed; use merges.
  • Safer habit: git fetch then inspect with git log HEAD..@{u} before integrating.