{"thread":{"id":"63377","subject":"doc: git-clone: Improve discoverability of --no-single-branch flag","startedAt":"2025-04-30T16:17:51Z","lastAt":"2025-05-01T18:10:42Z","messageCount":4,"participants":["Lino Haupt","Kristoffer Haugsbakk","Junio C Hamano","D. Ben Knoble"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"517025","messageId":"fb842b0e-3666-4b78-bf00-c7d11a42dd25@uni-jena.de","threadId":"63377","inReplyTo":null,"subject":"doc: git-clone: Improve discoverability of --no-single-branch flag","fromName":"Lino Haupt","fromEmail":"linojossfidel.haupt@uni-jena.de","sentAt":"2025-04-30T16:09:34Z","receivedAt":"2025-04-30T16:17:51Z","isPatch":false,"sender":{"key":"linojossfidel.haupt@uni-jena.de","avatar":null},"body":"Dear Git developers,\n\nthis is a minor usability suggestion\n\ngit version: 2.47.2 (NixOS)\nand https://git-scm.com/docs/git-clone\n\nShort Explanation:\n`git clone --help` shows `--no-single-branch` only inside the\n`--depth` paragraph.  The canonical option paragraph\n`--[no]-single-branch` is hard to find when searching for the\nexact forms `--single-branch` or `--no-single-branch`.\n\nExtended Explanation:\nThis reduces discoverability for users who quickly try to search\nor grep those options. I myself was confused by this.\nThe search term '--[no]-single-branch' is not intuitive.\nOf course, searching 'single-branch' finds the option paragraph,\nbut maybe only a secondary / tertiary choice.\nA second issue is that one has to deduce what exactly the 'no'\nshall negate. This is not complicated but may leave inexperience\nusers unsure of the expected behavior.\n\nSuggestion:\nBelow is a drop-in replacement that (a) places both variants in their\nown paragraph and (b) spells out the negated form explicitly,\nremoving the need to deduce what the “no-” prefix negates.\n\n--single-branch\nClone only the history leading to the tip of a single branch, either\nspecified by the --branch option or the primary branch remote’s\nHEAD points at. Further fetches into the resulting repository will\nonly update the remote-tracking branch for the branch this option\nwas used for the initial cloning. If the HEAD at the remote did not\npoint at any branch when --single-branch clone was made, no\nremote-tracking branch is created.\n\n--no-single branch\nOpposite of --single-branch: clone histories leading to the the tips of\nall branches.\n\n\nThanks for all the great work on Git!\n\n\nBest regards,\nLino Haupt\n\n"},{"id":"517027","messageId":"057e8f72-ea67-432b-a687-2b5af08fba05@app.fastmail.com","threadId":"63377","inReplyTo":"fb842b0e-3666-4b78-bf00-c7d11a42dd25@uni-jena.de","subject":"Re: doc: git-clone: Improve discoverability of --no-single-branch flag","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-04-30T16:49:46Z","receivedAt":"2025-04-30T16:50:35Z","isPatch":false,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Wed, Apr 30, 2025, at 18:09, Lino Haupt wrote:\n> Dear Git developers,\n>\n> this is a minor usability suggestion\n>\n> git version: 2.47.2 (NixOS)\n> and https://git-scm.com/docs/git-clone\n>\n> Short Explanation:\n> `git clone --help` shows `--no-single-branch` only inside the\n> `--depth` paragraph.  The canonical option paragraph\n> `--[no]-single-branch` is hard to find when searching for the\n> exact forms `--single-branch` or `--no-single-branch`.\n>\n> Extended Explanation:\n> This reduces discoverability for users who quickly try to search\n> or grep those options. I myself was confused by this.\n> The search term '--[no]-single-branch' is not intuitive.\n> Of course, searching 'single-branch' finds the option paragraph,\n> but maybe only a secondary / tertiary choice.\n> A second issue is that one has to deduce what exactly the 'no'\n> shall negate. This is not complicated but may leave inexperience\n> users unsure of the expected behavior.\n>\n> Suggestion:\n> Below is a drop-in replacement that (a) places both variants in their\n> own paragraph and (b) spells out the negated form explicitly,\n> removing the need to deduce what the “no-” prefix negates.\n>\n> --single-branch\n> Clone only the history leading to the tip of a single branch, either\n> specified by the --branch option or the primary branch remote’s\n> HEAD points at. Further fetches into the resulting repository will\n> only update the remote-tracking branch for the branch this option\n> was used for the initial cloning. If the HEAD at the remote did not\n> point at any branch when --single-branch clone was made, no\n> remote-tracking branch is created.\n>\n> --no-single branch\n> Opposite of --single-branch: clone histories leading to the the tips of\n> all branches.\n\nMany options are documented as `--[no-]`.\n\n    git grep --fixed-string -- '--[no-]' Documentation/ ':(exclude)Documentation/RelNotes/'\n\nThis is explained in gitcli(7), “Enhanced Option Parser” (for some\ncommands), “Negating options”:\n\n       Options with long option names can be negated by prefixing\n       --no-. For example, git branch has the option --track which is on\n       by default. You can use --no-track to override that\n       behaviour. The same goes for --color and --no-color.\n\nA concern might be that changing `--single-branch` in this way would be\ninconsistent with the overall style.\n"},{"id":"517032","messageId":"xmqqcyct1mtq.fsf@gitster.g","threadId":"63377","inReplyTo":"057e8f72-ea67-432b-a687-2b5af08fba05@app.fastmail.com","subject":"Re: doc: git-clone: Improve discoverability of --no-single-branch flag","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-04-30T19:17:05Z","receivedAt":"2025-04-30T19:17:08Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" <kristofferhaugsbakk@fastmail.com> writes:\n\n> Many options are documented as `--[no-]`.\n>\n>     git grep --fixed-string -- '--[no-]' Documentation/ ':(exclude)Documentation/RelNotes/'\n>\n> This is explained in gitcli(7), “Enhanced Option Parser” (for some\n> commands), “Negating options”:\n>\n>        Options with long option names can be negated by prefixing\n>        --no-. For example, git branch has the option --track which is on\n>        by default. You can use --no-track to override that\n>        behaviour. The same goes for --color and --no-color.\n>\n> A concern might be that changing `--single-branch` in this way would be\n> inconsistent with the overall style.\n\nA pair of quick counts:\n\n    $ git grep -E -e '^`?--no-' Documentation/ | wc -l\n    189\n    $ git grep -E -e '^`?--\\[no-\\]' Documentation/ | wc -l\n    80\n\nI think we should try to unify to the following style:\n\n    `--frotz=<string>`::\n    `--no-frotz`::\n\tWhen `--frotz` is given, the command does THIS using the\n        given argument <string> IN THIS WAY.  The default is not to\n        to THIS, unless SUCH AND SUCH CONDITION, in which case THAT\n        is used implicitly as <string>.  To disable THIS even when\n        SUCH AND SUCH CONDITION is met, use `--no-frotz`.\n\nThat is:\n\n * Both positive and negative form are given separately as a\n   headline item, so that \"grep\" would work well;\n\n * The description should be unified, so that it is clear to readers\n   what happens when the positive form is given, when the negative\n   form is given, and when neither is given.\n\n * Mark-up the text that the users MUST input literally inside a\n   pair of backquotes.\n\nWhich means that existing \"--[no-]opt::\" heading should become two\nlines, \"`--opt`::\" and \"`--no-opt`::\".\n\nThanks.\n"},{"id":"517056","messageId":"CALnO6CBjd=-9OZfQ_Mhq7r0Y=gXKcb5WNOT+-qPAs_LNsayi0Q@mail.gmail.com","threadId":"63377","inReplyTo":"xmqqcyct1mtq.fsf@gitster.g","subject":"Re: doc: git-clone: Improve discoverability of --no-single-branch flag","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-05-01T18:10:28Z","receivedAt":"2025-05-01T18:10:42Z","isPatch":false,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Wed, Apr 30, 2025 at 3:19 PM Junio C Hamano <gitster@pobox.com> wrote:\n>\n> \"Kristoffer Haugsbakk\" <kristofferhaugsbakk@fastmail.com> writes:\n>\n> > Many options are documented as `--[no-]`.\n> >\n> >     git grep --fixed-string -- '--[no-]' Documentation/ ':(exclude)Documentation/RelNotes/'\n> >\n> > This is explained in gitcli(7), “Enhanced Option Parser” (for some\n> > commands), “Negating options”:\n> >\n> >        Options with long option names can be negated by prefixing\n> >        --no-. For example, git branch has the option --track which is on\n> >        by default. You can use --no-track to override that\n> >        behaviour. The same goes for --color and --no-color.\n> >\n> > A concern might be that changing `--single-branch` in this way would be\n> > inconsistent with the overall style.\n>\n> A pair of quick counts:\n>\n>     $ git grep -E -e '^`?--no-' Documentation/ | wc -l\n>     189\n>     $ git grep -E -e '^`?--\\[no-\\]' Documentation/ | wc -l\n>     80\n>\n> I think we should try to unify to the following style:\n>\n>     `--frotz=<string>`::\n>     `--no-frotz`::\n>         When `--frotz` is given, the command does THIS using the\n>         given argument <string> IN THIS WAY.  The default is not to\n>         to THIS, unless SUCH AND SUCH CONDITION, in which case THAT\n>         is used implicitly as <string>.  To disable THIS even when\n>         SUCH AND SUCH CONDITION is met, use `--no-frotz`.\n>\n> That is:\n>\n>  * Both positive and negative form are given separately as a\n>    headline item, so that \"grep\" would work well;\n>\n>  * The description should be unified, so that it is clear to readers\n>    what happens when the positive form is given, when the negative\n>    form is given, and when neither is given.\n>\n>  * Mark-up the text that the users MUST input literally inside a\n>    pair of backquotes.\n>\n> Which means that existing \"--[no-]opt::\" heading should become two\n> lines, \"`--opt`::\" and \"`--no-opt`::\".\n>\n> Thanks.\n>\n\nSee also https://lore.kernel.org/git/xmqqjzanzy8k.fsf@gitster.g/,\nwhere I had some similar questions (and got similar answers). We also\nmerged 4ad47d2de3 (gitcli: document that command line trumps config\nand env, 2025-01-16) as a result.\n\nIf I'm reading right, this suggestion differs from the previous\nconversation that it's worth splitting --[no-]opt into --opt/--no-opt,\nwhich might be valuable for searches of the kind Lino described.\n\nI did eventually push beeabf89 (vim: try harder to find long options,\n2025-01-19) [1] to my Dotfiles to work around the current\ndocumentation patterns. I press either `-x` or `_XXX` when searching\nfor an option (short x, long XXX) in a manual page with those Vim\nkeybindings, but hopefully the patterns are useful to other people.\nFor long options, that's\n\n/^\\C\\v\\s*(-[^,]*,\\s*)?--(\\[no-\\])?\n\n[1]: https://github.com/benknoble/Dotfiles/commit/beeabf89\n\n-- \nD. Ben Knoble\n"}]}