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 <julia@jvns.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Julia Evans committed
Oct 15, 2025 at 13:13 UTC
59b28f928b2b3b91033ee4e9cbe0cf51a781e55b
1 file changed
+20
-11
Documentation/git-pull.adoc
+20
-11
@@ -15,17 +15,26 @@ SYNOPSIS
15
DESCRIPTION
16
-----------
17
18
-Incorporates changes from a remote repository into the current branch.
19
-If the current branch is behind the remote, then by default it will
20
-fast-forward the current branch to match the remote. If the current
21
-branch and the remote have diverged, the user needs to specify how to
22
-reconcile the divergent branches with `--rebase` or `--no-rebase` (or
23
-the corresponding configuration option in `pull.rebase`).
24
-
25
-More precisely, `git pull` runs `git fetch` with the given parameters
26
-and then depending on configuration options or command line flags,
27
-will call either `git rebase` or `git merge` to reconcile diverging
28
-branches.
18
+Integrate changes from a remote repository into the current branch.
19
+
20
+First, `git pull` runs `git fetch` with the same arguments
21
+(excluding merge options) to fetch remote branch(es).
22
+Then it decides which remote branch to integrate: if you run `git pull`
23
+with no arguments this defaults to the <<UPSTREAM-BRANCHES,upstream>>
24
+for the current branch.
25
+Then it integrates that branch into the current branch.
26
+
27
+There are 4 main options for integrating the remote branch:
28
+
29
+1. `git pull --ff-only` will only do "fast-forward" updates: it
30
+ fails if your local branch has diverged from the remote branch.
31
+ This is the default.
32
+2. `git pull --rebase` runs `git rebase`
33
+3. `git pull --no-rebase` runs `git merge`.
34
+4. `git pull --squash` runs `git merge --squash`
35
+
36
+You can also set the configuration options `pull.rebase`, `pull.squash`,
37
+or `pull.ff` with your preferred behaviour.
38
39
Assume the following history exists and the current branch is
40
"`master`":