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

From: "Julia Evans" <[email-masked]>
Date: Thu, 09 Oct 2025 17:31:30 -0400

On Wed, Oct 8, 2025, at 5:33 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <[email-masked]> 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".

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

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