freshlybakedca.ke / git
Git fork
fork atom

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>

authored by

Julia Evans and committed by
Junio C Hamano 59b28f92 85abbfc5

+19 -10
unified split
+19 -10
Documentation/git-pull.adoc
··· 15 15 DESCRIPTION 16 16 ----------- 17 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`). 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` 24 35 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. 36 + You can also set the configuration options `pull.rebase`, `pull.squash`, 37 + or `pull.ff` with your preferred behaviour. 29 38 30 39 Assume the following history exists and the current branch is 31 40 "`master`":