On Wed, Apr 30, 2025, at 18:09, Lino Haupt wrote: > 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.
