doc: git-clone: Improve discoverability of --no-single-branch flag
- From
- Lino Haupt <linojossfidel.haupt@uni-jena.de>
- Date
- Apr 30, 2025, 16:09 UTC
- Message-ID
- <fb842b0e-3666-4b78-bf00-c7d11a42dd25@uni-jena.de>
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.
Thanks for all the great work on Git!
Best regards, Lino Haupt