Re: doc: git-clone: Improve discoverability of --no-single-branch flag

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Apr 30, 2025, 16:49 UTC
Message-ID: <057e8f72-ea67-432b-a687-2b5af08fba05@app.fastmail.com>
In-Reply-To: <fb842b0e-3666-4b78-bf00-c7d11a42dd25@uni-jena.de>

On Wed, Apr 30, 2025, at 18:09, Lino Haupt wrote:

Show 40 quoted lines

> Dear Git developers,
>
> this is a minor usability suggestion
>
> git version: 2.47.2 (NixOS)
> and https://git-scm.com/docs/git-clone
>
> Short Explanation:
> `git clone --help` shows `--no-single-branch` only inside the
> `--depth` paragraph.  The canonical option paragraph
> `--[no]-single-branch` is hard to find when searching for the
> exact forms `--single-branch` or `--no-single-branch`.
>
> Extended Explanation:
> This reduces discoverability for users who quickly try to search
> or grep those options. I myself was confused by this.
> The search term '--[no]-single-branch' is not intuitive.
> Of course, searching 'single-branch' finds the option paragraph,
> but maybe only a secondary / tertiary choice.
> A second issue is that one has to deduce what exactly the 'no'
> shall negate. This is not complicated but may leave inexperience
> users unsure of the expected behavior.
>
> Suggestion:
> Below is a drop-in replacement that (a) places both variants in their
> own paragraph and (b) spells out the negated form explicitly,
> removing the need to deduce what the “no-” prefix negates.
>
> --single-branch
> Clone only the history leading to the tip of a single branch, either
> specified by the --branch option or the primary branch remote’s
> HEAD points at. Further fetches into the resulting repository will
> only update the remote-tracking branch for the branch this option
> was used for the initial cloning. If the HEAD at the remote did not
> point at any branch when --single-branch clone was made, no
> remote-tracking branch is created.
>
> --no-single branch
> Opposite of --single-branch: clone histories leading to the the tips of
> all branches.

Many options are documented as `--[no-]`.

    git grep --fixed-string -- '--[no-]' Documentation/ ':(exclude)Documentation/RelNotes/'

This is explained in gitcli(7), “Enhanced Option Parser” (for some commands), “Negating options”:

       Options with long option names can be negated by prefixing
       --no-. For example, git branch has the option --track which is on
       by default. You can use --no-track to override that
       behaviour. The same goes for --color and --no-color.

A concern might be that changing `--single-branch` in this way would be inconsistent with the overall style.