From: D. Ben Knoble <ben.knoble@gmail.com>
Date: Wed, 24 Sep 2025 20:17:28 GMT
Subject: Re: [PATCH 1/4] doc: git-pull: move <repository> and <refspec> params
Message-ID: <CALnO6CCQhTR77nvjPM-fhTm9o6imjw9Erk0NMWhLMYrSAWW8hw@mail.gmail.com>
In-Reply-To: <f69d2e6fabbace9ae76cb3822b063a3f19622138.1758656702.git.gitgitgadget@gmail.com>

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.

-- 
D. Ben Knoble