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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 8, 2025, 21:33 UTC
Message-ID: <xmqqqzvddqon.fsf@gitster.g>
In-Reply-To: <122774d4cc8fa4e9184a0f82e9b6e562363ea433.1759951536.git.gitgitgadget@gmail.com>

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

Show 12 quoted lines

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

Show 5 quoted lines

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