Re: [PATCH v2 2/4] doc: git-pull: clarify options for integrating remote branch

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> +Integrate changes from a remote repository into the current branch.
> +
> +First, `git pull` runs `git fetch` with the same arguments
> +(excluding merge options) to fetch remote branch(es).
> +Then it decides which remote branch to integrate: if you run `git pull`
> +with no arguments this defaults to the <<UPSTREAM-BRANCHES,upstream>>
> +for the current branch.
> +Then it integrates that 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.

Technically, you can pretend to be the king, the center of the
world, and occasionally publish your very latest to the remote by
pushing there, and it is technically possible that the remote to
diverge from you by somehow acquiring its own commits, so the above
is not wrong per-se, but the way it is phrased is a bit awkward.

The operation fails when _you_ diverged from the remote branch.

In other words, you cloned or made yourself in-sync with the remote
earlier, the remote may or may not have progressed before your
'pull'.  If you created your own commits on top of the state that
was in sync with them, you diverged from them and --ff-only is
stopped in such a case.  If you haven't changed your branch since
you were in sync with them the last time, --ff-only would
fast-forward your branch to match what they have.

> +2. `git pull --rebase` runs `git rebase`

This technically does not integrate remote branch into our current
branch.  Rather, the commits on our current branch are integrated
on top of their history.  That may be worth noting?  I dunno.

> +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.

This part has two orthogonal things, each of which has its own
default, which may be a bit confusing.  (1) which branch we get from
the remote integrates with the current branch.  The default is to
use the upstream of our current branch.  (2) how the integration
between the remote thing and our current branch is done.  The
default is only to accept fast-forward updates.

Perhaps it may help clarify the flow if we said upfront that we
describe two orthgonal things?  E.g.,

    First it fetches.  Then it decides two things: what to integrage
    with the current branch, and how to do the integration.  By
    default, the upstream branch of the current branch is what gets
    integrated, and by default "pull --ff-only" (described below) is
    how the integration is done.

or something?  I dunno.