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

From: Julia Evans <julia@jvns.ca>
Date: Oct 9, 2025, 21:31 UTC
Message-ID: <b432f1b9-804d-4249-bc1a-4f3629aff50c@app.fastmail.com>
In-Reply-To: <xmqqqzvddqon.fsf@gitster.g>

On Wed, Oct 8, 2025, at 5:33 PM, Junio C Hamano wrote:

Show 22 quoted lines

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

Thanks, I meant to fix that earlier. Will fix to say "if your local branch has diverged from the remote".

Show 5 quoted lines

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

At least 2 users who read this also commented that they find the word "integrate" using, for perhaps a similar reason. Specifically, one comment was "unclear if 'integrate' is a technical/specific term or just generic".

My assumption was that the word "integrate" was meant to be a generic way to communicate "combine the changes in the two branches in some unspecified way", and that's how I was using it. I'm not sure what you mean when you say "integrate" (is it "merge"?).

I see a few options here:

1. Try to find a different word that communicates "combine the two
   branches in a way that you have to specify". I'm not sure how
   likely this is to succeed.
2. Instead of using the word "integrate", instead always say something
   like "merge or rebase". I tried this but I found it a bit unwieldy, and
   I think it might also be confusing for users who aren't familiar with
   both merge and rebase, they might worry "do I need to understand
   rebase to use `git pull`?", when of course you don't.
3. Keep the word "integrate".

I'm very open to hearing suggestions here, maybe there's another better way I haven't thought of.

Show 23 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.

I think I'm happy with how the two different defaults are being described right now, but I'll run this by some folks and see what they think.