git config pull.rebase: merge or rebase on git pull
- tool
- Git
- file
- .git/config or ~/.gitconfig
- key
- pull.rebase
- type
- true | false | merges | interactive
- default
- unset (merge, but git pull stops when branches diverged and pull.ff is unset)
pull.rebase chooses what git pull does when your branch and its upstream both have new commits: false merges (creates a merge commit), true rebases your local commits on top of the upstream. If neither pull.rebase nor pull.ff is set, Git stops with fatal: Need to specify how to reconcile divergent branches. Set one of them once, for example git config --global pull.rebase true.
The error when nothing is configured
git init -q --bare origin.git
git clone -q origin.git a 2>/dev/null && cd a
git switch -q -c main && echo base > f && git add f && git commit -qm base && git push -q -u origin main
cd .. && git clone -q -b main origin.git b && cd b && echo theirs > t && git add t && git commit -qm theirs && git push -q
cd ../a && echo mine > m && git add m && git commit -qm mine
git pullOutput · exit 128
From /tmp/work/origin 350f8df..2a05824 main -> origin/main 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 config pull.rebase false # merge hint: git config pull.rebase true # rebase hint: git config pull.ff only # fast-forward only hint: hint: You can replace "git config" with "git config --global" to set a default hint: preference for all repositories. You can also pass --rebase, --no-rebase, hint: or --ff-only on the command line to override the configured default per hint: invocation. fatal: Need to specify how to reconcile divergent branches.
With pull.rebase true
git init -q --bare origin.git
git clone -q origin.git a 2>/dev/null && cd a
git switch -q -c main && echo base > f && git add f && git commit -qm base && git push -q -u origin main
cd .. && git clone -q -b main origin.git b && cd b && echo theirs > t && git add t && git commit -qm theirs && git push -q
cd ../a && echo mine > m && git add m && git commit -qm mine
git config pull.rebase true
git pull -q
git log --oneline --graphOutput
* d46e51d mine * 2a05824 theirs * 350f8df base
The local commit mine was replayed on top of theirs: the history stays linear, and the replayed commit gets a new hash.
Values
| Setting | git pull does |
|---|---|
| pull.rebase false | Merge; creates a merge commit when branches diverged |
| pull.rebase true | Rebase local commits onto the upstream |
| pull.rebase merges | Rebase, keeping local merge commits (replaces the removed preserve value) |
| pull.rebase interactive | Interactive rebase |
| pull.ff only | Only fast-forward; fail when branches diverged |
| pull.ff false | Always create a merge commit, even when a fast-forward is possible |
Command-line flags override the configuration for one pull: git pull --rebase, git pull --no-rebase, git pull --ff-only. branch.NAME.rebase overrides pull.rebase for one branch.
Which setting to choose
| If you want | Set |
|---|---|
| A straight history and you work alone or on your own branch | git config --global pull.rebase true |
| Merge commits that record each pull, as in Git before 2.27 | git config --global pull.rebase false |
| To be stopped whenever the branches diverged, and decide each time | git config --global pull.ff only |
| Rebase but keep merge commits you made locally | git config --global pull.rebase merges |
Whatever you choose, a pull that rebases can still stop on conflicts. Resolve them, git add the files and run git rebase --continue, or git rebase --abort to return to the state before the pull. A pull that merges stops the same way (Automatic merge failed); finish it with git commit. The differences between both strategies are compared in git merge vs git rebase.
FAQ
Should I set pull.rebase to true or false?
true if you want a linear history and your local commits are not shared yet; false if you prefer merge commits that show when you integrated upstream work. pull.ff only is a third option that never creates merges or rebases silently.
Does pull.rebase true rewrite commits that are already pushed?
It rebases only the local commits that are not in the upstream yet. Commits you already pushed are part of the upstream and are not replayed.
Why does git pull --rebase fail with unstaged changes?
A rebase needs a clean working tree. Commit or stash the changes, or set rebase.autoStash true so Git stashes and restores them around the pull.