From: Julia Evans Date: Tue, 23 Sep 2025 19:45:00 +0000 (+0000) Subject: doc: git-pull: clarify options for integrating remote branch X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=fa79b939377a114663aea2c146fa7aba564cc3f5;p=thirdparty%2Fgit.git doc: git-pull: clarify options for integrating remote branch From user feedback: - One user is confused about the current default ("I was convinced that the git default was still to merge on pull") - One user is confused about why "git fetch" isn't mentioned earlier - One user says they always forget what the arguments to `git pull` are and that it's not immediately obvious that `--no-rebase` means "merge" - One user wants `--ff-only` to be mentioned Resolve this by listing the options for integrating the the remote branch. This should help users figure out at a glance which one they want to do, and make it clearer that --ff-only is the default. Signed-off-by: Julia Evans Signed-off-by: Junio C Hamano --- diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc index 50af7fde81..61d18fef36 100644 --- a/Documentation/git-pull.adoc +++ b/Documentation/git-pull.adoc @@ -15,17 +15,20 @@ SYNOPSIS DESCRIPTION ----------- -Incorporates changes from a remote repository into the current branch. -If the current branch is behind the remote, then by default it will -fast-forward the current branch to match the remote. If the current -branch and the remote have diverged, the user needs to specify how to -reconcile the divergent branches with `--rebase` or `--no-rebase` (or -the corresponding configuration option in `pull.rebase`). - -More precisely, `git pull` runs `git fetch` with the given parameters -and then depending on configuration options or command line flags, -will call either `git rebase` or `git merge` to reconcile diverging -branches. +Integrate changes from a remote repository into the current branch. + +First, `git pull` runs `git fetch` with the same arguments to fetch +remote branch(es). Then it integrates the remote branch into the current +branch. There are 4 main options for integrating the remote branch: + +1. `git pull --ff-only` will only do "fast-forward" updates: it + fails if the remote branch has diverged. This is the default. +2. `git pull --rebase` runs `git rebase` +3. `git pull --no-rebase` runs `git merge`. +4. `git pull --squash` runs `git merge --squash` + +You can also set the configuration options `pull.rebase`, `pull.squash`, +or `pull.ff` with your preferred behaviour. Assume the following history exists and the current branch is "`master`":