From: Julia Evans <julia@jvns.ca>
Date: Tue, 07 Oct 2025 21:20:52 GMT
Subject: Re: [PATCH 1/4] doc: git-pull: move <repository> and <refspec> params
Message-ID: <9091705b-e575-48d7-95a0-5e2835fb9edf@app.fastmail.com>
In-Reply-To: <CALnO6CCQhTR77nvjPM-fhTm9o6imjw9Erk0NMWhLMYrSAWW8hw@mail.gmail.com>



On Wed, Sep 24, 2025, at 4:17 PM, D. Ben Knoble wrote:
> On Tue, Sep 23, 2025 at 3:45 PM Julia Evans via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>>
>> From: Julia Evans <julia@jvns.ca>
>>
>> From user feedback:
>>
>> - it's confusing that we use both <branch> and <refspec> to refer to the
>>   second argument
>
> Yep.
>
>> - one user is not clear about what `refs/heads/*:refs/remotes/origin/*`
>>   is meant to be an example of ("is it like a path?")
>
> Also yep, since the deleted text doesn't contain any pointers to learn
> what a refspec is.
>
>> The DESCRIPTION section is also doing a lot right now: it's trying to
>> describe both how the <repository> and <refspec> arguments work (which
>> is pretty complex, as seen in the DEFAULT BEHAVIOUR section)
>> as well as how `git pull` calls `git fetch` and merge/rebase/etc
>> depending on the arguments.
>>
>> Handle this by moving the description of the <repository> and <refspec>
>> arguments to the OPTIONS section, so that we can focus on the
>> merge/rebase/etc behaviour in the DESCRIPTION section, and refer folks
>> to the later sections for details.
>
> I generally like this: it makes things a bit more consistent, even
> though "options" isn't quite how I think of these (optional!)
> positional parameters. Still, I generally jump down to the <arg>
> sections (like in git-push(1)) to learn what I can do with those.
>
>> Use the term "upstream" instead of 'the "remote" and "merge"
>> configuration for the current branch' since users are more likely to
>> know what an "upstream" is.
>
> With the upstream section, great.
>
>> diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc
>> index 48e924a10a..50af7fde81 100644
>> --- a/Documentation/git-pull.adoc
>> +++ b/Documentation/git-pull.adoc
>> @@ -27,17 +27,6 @@ and then depending on configuration options or command line flags,
>>  will call either `git rebase` or `git merge` to reconcile diverging
>>  branches.
>>
>> -<repository> should be the name of a remote repository as
>> -passed to linkgit:git-fetch[1].  <refspec> can name an
>> -arbitrary remote ref (for example, the name of a tag) or even
>> -a collection of refs with corresponding remote-tracking branches
>> -(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),
>> -but usually it is the name of a branch in the remote repository.
>> -
>> -Default values for <repository> and <branch> are read from the
>> -"remote" and "merge" configuration for the current branch
>> -as set by linkgit:git-branch[1] `--track`.
>
> And we don't even mind losing "--track" here because we cover it in
> Upstream Branches (e.g.,
> https://lore.kernel.org/git/3ecfb5c3a67723f160e8161e212d77f95964539c.1758649472.git.gitgitgadget@gmail.com/).
>
>> -
>>  Assume the following history exists and the current branch is
>>  "`master`":
>>
>> @@ -77,6 +66,24 @@ pulling or stash them away with linkgit:git-stash[1].
>>  OPTIONS
>>  -------
>>
>> +<repository>::
>> +       The "remote" repository to pull from.  This can be either
>> +       a URL (see the section <<URLS,GIT URLS>> below) or the name
>> +       of a remote (see the section <<REMOTES,REMOTES>> below).
>> ++
>> +Defaults to the configured upstream for the current branch, or `origin`.
>> +See UPSTREAM BRANCHES below for more on how to configure upstreams.
>> +
>> +<refspec>::
>> +       Which branch or other reference(s) to fetch and integrate into the
>> +       current branch, for example `main` in `git pull origin main`.
>> +       Defaults to the configured upstream for the current branch.
>> ++
>> +This can be a branch, tag, or other collection of reference(s).
>> +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.
>> +
>
> I think these are covered in Documentation/pull-fetch-param.adoc,
> which I only found by looking at "git help pull" and searching for the
> URLs references, hah.
>
> Anyway, the existing explanations are far too late in the manual (Vim
> says ~46%, 960 lines down, when rendered with MANWIDTH=80). Moving
> them up is a good idea, but maybe we need to do that in a way that
> jives with the later "fetching" section. Hm.

That's a good point. It's a bit weird because (I think) `git pull does use the 
<refspec> parameter after passing it to `git fetch`  (to decide which
remote branch to merge), so we can't just say "to know what the refspec
parameter does, see "git fetch", and we can't just copy the existing
<refspec> section further up.

Rewriting the <refspec> section of `git fetch` so that it addresses both the
`git pull` and `git fetch` case seems like it would just add more confusion.

Duplicating the content of the <repository> bit and then referencing 
the second <refspec> section below is the least bad option I can think of
right now, since most of the time you don't actually need to know how to
write a refspec.

I'll add some internal links in the HTML version to the <refspec>
and DEFAULT BEHAVIOUR sections so that they'll be easier to find in the
HTML version at least.