From: "Julia Evans" <julia@jvns•ca>
To: "D. Ben Knoble" <ben.knoble@gmail•com>,
"Julia Evans" <gitgitgadget@gmail•com>
Cc: git@vger•kernel.org
Subject: Re: [PATCH 1/4] doc: git-pull: move <repository> and <refspec> params
Date: Tue, 07 Oct 2025 17:20:52 -0400 [thread overview]
Message-ID: <9091705b-e575-48d7-95a0-5e2835fb9edf@app.fastmail.com> (raw)
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.
next prev parent reply other threads:[~2025-10-07 21:21 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-09-23 19:44 [PATCH 0/4] doc: git-pull: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-09-23 19:44 ` [PATCH 1/4] doc: git-pull: move <repository> and <refspec> params Julia Evans via GitGitGadget
2025-09-24 20:17 ` D. Ben Knoble
2025-10-07 21:20 ` Julia Evans [this message]
2025-09-23 19:45 ` [PATCH 2/4] doc: git-pull: clarify options for integrating remote branch Julia Evans via GitGitGadget
2025-09-24 20:23 ` D. Ben Knoble
2025-09-24 20:54 ` Julia Evans
2025-09-24 22:38 ` Chris Torek
2025-10-06 21:16 ` Julia Evans
2025-09-23 19:45 ` [PATCH 3/4] doc: git-pull: delete the example Julia Evans via GitGitGadget
2025-09-23 19:45 ` [PATCH 4/4] doc: git-pull: clarify how to exit a conflicted merge Julia Evans via GitGitGadget
2025-09-24 17:21 ` Julia Evans
2025-09-24 20:29 ` D. Ben Knoble
2025-10-07 21:01 ` Julia Evans
2025-10-10 0:45 ` Ben Knoble
2025-09-24 19:56 ` [PATCH 0/4] doc: git-pull: clarify DESCRIPTION section D. Ben Knoble
2025-10-08 19:25 ` [PATCH v2 " Julia Evans via GitGitGadget
2025-10-08 19:25 ` [PATCH v2 1/4] doc: git-pull: move <repository> and <refspec> params Julia Evans via GitGitGadget
2025-10-08 19:25 ` [PATCH v2 2/4] doc: git-pull: clarify options for integrating remote branch Julia Evans via GitGitGadget
2025-10-08 21:33 ` Junio C Hamano
2025-10-09 21:31 ` Julia Evans
2025-10-09 22:20 ` Kristoffer Haugsbakk
2025-10-09 22:41 ` Junio C Hamano
2025-10-08 19:25 ` [PATCH v2 3/4] doc: git-pull: delete the example Julia Evans via GitGitGadget
2025-10-08 19:25 ` [PATCH v2 4/4] doc: git-pull: clarify how to exit a conflicted merge Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 0/4] doc: git-pull: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 1/4] doc: git-pull: move <repository> and <refspec> params Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 2/4] doc: git-pull: clarify options for integrating remote branch Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 3/4] doc: git-pull: delete the example Julia Evans via GitGitGadget
2025-10-15 13:13 ` [PATCH v3 4/4] doc: git-pull: clarify how to exit a conflicted merge Julia Evans via GitGitGadget
2025-10-15 16:56 ` [PATCH v3 0/4] doc: git-pull: clarify DESCRIPTION section Ben Knoble
2025-10-15 20:36 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=9091705b-e575-48d7-95a0-5e2835fb9edf@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=ben.knoble@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox