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

From: Julia Evans <julia@jvns.ca>
Date: Sep 24, 2025, 20:54 UTC
Message-ID: <f6dea581-04c5-4b05-ab81-1fb06de1cf41@app.fastmail.com>
In-Reply-To: <CALnO6CCkWaxZKGseHR7dk20erFPAvGMqO+OYr3Np+y+=1Y34HA@mail.gmail.com>

Show 11 quoted lines

>> -More precisely, `git pull` runs `git fetch` with the given parameters
>> -and then depending on configuration options or command line flags,
>> -will call either `git rebase` or `git merge` to reconcile diverging
>> -branches.
>> +Integrate changes from a remote repository into the current branch.
>> +
>> +First, `git pull` runs `git fetch` with the same arguments to fetch
>
> Hm. Is it worth saying "similar" rather than "same" since we don't
> pass e.g. `--rebase` to `git fetch`? Or is that detail unimportant in
> this context?

That's a good point, I'll try to think of a better way to phrase it.

I guess the truth is that `git pull` has three categories of options, those it passes verbatim to `git fetch`, those it passes verbatim to `git merge`, and the others (-q, -v, and --recurse-submodules). That's a bit of a mouthful but maybe there's a way to say that explicitly that isn't too awkward, it does seem helpful to know when reading the OPTIONS section.

Show 9 quoted lines

>> +remote branch(es). Then it integrates the remote branch into the current
>> +branch.
>
> Plural-singular here leaves me wondering how Git decides which of
> multiple fetched branches to integrate. A quick test of the form
>
>     git pull origin refs/heads/\*:refs/remotes/origin/\*
>
> just gives an error in every mode I tried, so I'm now confused about this use :)

I find it confusing too. My current strategy for handling this here is to somewhat awkwardly say "it's explained in the DEFAULT BEHAVIOUR section" a bit further down.

It's a tricky situation because I find the DEFAULT BEHAVIOUR section very confusing. It seems like there's a fair amount of duplication with other sections that could be cleaned up to make it easier. But removing the duplication and making it easier to understand feels like too many changes for this series, especially because really doing it well probably involves the sub-project of "clean up the <refspec> section of the `git fetch` man page".

In any case, I'll see if I can find a way to make it a little less awkward.