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

From: Julia Evans <julia@jvns.ca>
Date: Oct 6, 2025, 21:16 UTC
Message-ID: <6c8790b7-2b8c-4452-bcc6-2fa17d08ec86@app.fastmail.com>
In-Reply-To: <CAPx1GvfK5ZKUG86n=DR8LeO_STwO5FAkDzzD9t6d9R22KdOySg@mail.gmail.com>

On Wed, Sep 24, 2025, at 6:38 PM, Chris Torek wrote:

Show 28 quoted lines

> On Wed, Sep 24, 2025 at 1:23 PM D. Ben Knoble <ben.knoble@gmail.com> wrote:
>> > +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?
>
> I would suggest "equivalent" or (perhaps better) "appropriate".
> Perhaps even:
>
>     First, `git pull` runs the equivalent of `git fetch` with the
>     arguments needed to fetch necessary branches from
>     the remote ...
>
> Definition of these arguments can be deferred (perhaps
> even indefinitely); but:
>
>> > +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.
>
> here we'd need something along the lines of:
>
>     Then it integrates the appropriate remote branch ...
>
> and here we *do* have to define "appropriate".

I like the idea of adding "appropriate" here. The question of how to define it is a little messy.

We do define "appropriate" below under <refspec>, like this:

> See <refspec> below under "Options related to fetching" for the full syntax,
> and DEFAULT BEHAVIOUR below for how `git pull` uses this argument to
> determine which remote branch to integrate.

Like I mentioned in another reply I think deferring the question of what "the appropriate branch" is to the DEFAULT BEHAVIOUR section like this does is not a "good" long-term solution because that section is so confusing, but I think it's not worse than the current state and I don't want to expand the scope of this patch series too much.

However! I think there's a question of what behaviour to "encourage". Over on the `git push` side, we decided to highlight using `git push origin main` to push, because the behaviour of `git push origin main` is simple to explain ("it pushes the local main branch to the main on the `origin` remote").

So a natural next question is: should we equivalently highlight "git pull origin main", to mirror the `git push` man page? Then it would be easy to say what "the appropriate branch" is, because in that case the branch is "whatever branch you specified"

My initial instinct is "no": `git push origin main` also feels sort of "foolproof" to me, in the sense that if you accidentally run it while on the wrong branch, nothing really bad will happen, since it doesn't matter what your current branch is.

But `git pull` is not the same, since running `git pull origin <wrong-branch>` will integrate <wrong-branch> into your current branch, which could get confusing if you accidentally pulled while on the wrong branch. Personally I use `git pull` without any arguments, and it feels safer to me that way because I know that I'm likely to have set my upstream to something reasonable.

I also did some extremely informal and low-sample-size Mastodon polling and my sense so far is that folks tend to run `git pull` with no arguments in practice. So I think it makes sense to highlight the no-arguments version.

And in any case if you want to get really specific about what you're pulling I think going straight to "manually fetch and then run `git merge` yourself" is a safer approach instead of passing arguments to `git pull`.

All of that is to say: my best idea for how to resolve all of this is as follows:

Show 5 quoted lines

> 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 for the current branch.
> Then it integrates that branch into the current branch.

This explains what the "appropriate branch" is in (I think) the most common use case and deals with the "same arguments" issue.