{"thread":{"id":"59796","subject":"[PATCH] git-clone.txt: document -4 and -6","startedAt":"2023-05-27T13:18:32Z","lastAt":"2024-01-02T22:25:12Z","messageCount":7,"participants":["Jakub Wilk","Junio C Hamano","Taylor Blau"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"477755","messageId":"20230527123849.5990-1-jwilk@jwilk.net","threadId":"59796","inReplyTo":null,"subject":"[PATCH] git-clone.txt: document -4 and -6","fromName":"Jakub Wilk","fromEmail":"jwilk@jwilk.net","sentAt":"2023-05-27T12:38:49Z","receivedAt":"2023-05-27T13:18:32Z","isPatch":true,"sender":{"key":"jwilk@jwilk.net","avatar":"https://avatars.githubusercontent.com/u/141546?v=4"},"body":"These options were added in c915f11eb4 (\"connect & http: support -4 and\n-6 switches for remote operations\").\n\nSigned-off-by: Jakub Wilk \n---\n Documentation/git-clone.txt | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex c37c4a37f7..e6f0329510 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -316,6 +316,14 @@ or `--mirror` is given)\n \tThe number of submodules fetched at the same time.\n \tDefaults to the `submodule.fetchJobs` option.\n \n+-4::\n+--ipv4::\n+\tUse IPv4 addresses only, ignoring IPv6 addresses.\n+\n+-6::\n+--ipv6::\n+\tUse IPv6 addresses only, ignoring IPv4 addresses.\n+\n ::\n \tThe (possibly remote) repository to clone from. See the\n \t<> section below for more information on specifying\n-- \n2.25.1\n\n"},{"id":"477854","messageId":"xmqq1qivd8d0.fsf@gitster.g","threadId":"59796","inReplyTo":"20230527123849.5990-1-jwilk@jwilk.net","subject":"Re: [PATCH] git-clone.txt: document -4 and -6","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-06-01T06:06:35Z","receivedAt":"2023-06-01T06:06:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Wilk writes:\n\n> These options were added in c915f11eb4 (\"connect & http: support -4 and\n> -6 switches for remote operations\").\n>\n> Signed-off-by: Jakub Wilk \n> ---\n> Documentation/git-clone.txt | 8 ++++++++\n> 1 file changed, 8 insertions(+)\n\nThe patch is not _wrong_ per-se, but there are other options that\nare common among the \"fetch\" family of commands. I counted at least\nthese should be shared between \"fetch\" and \"clone\", by splitting\nthem out of \"fetch-options.txt\" into a new file, and including that\nnew file from \"fetch-options.txt\" and \"git-clone.txt\". Those marked\nwith (?) are described in different phrasing between \"clone\" and\n\"fetch\", and may fall into the \"let's keep them separate, because\nthey mean different things\" category (later):\n\n * --jobs\n * --upload-pack\n * --quiet (?)\n * --verbose (?)\n * --progress\n * --server-option\n * --ipv[46]\n\nNote that these happen to share the same name, but to \"clone\" and\n\"fetch\" they different things, so leaving them separate is the right\nthing to do.\n\n * --no-tags\n * --recurse-submodules\n\nThanks.\n"},{"id":"486207","messageId":"20240102185842.bbcd7sqezsj5locs@jwilk.net","threadId":"59796","inReplyTo":"xmqq1qivd8d0.fsf@gitster.g","subject":"Re: [PATCH] git-clone.txt: document -4 and -6","fromName":"Jakub Wilk","fromEmail":"jwilk@jwilk.net","sentAt":"2024-01-02T18:58:42Z","receivedAt":"2024-01-02T18:58:47Z","isPatch":true,"sender":{"key":"jwilk@jwilk.net","avatar":"https://avatars.githubusercontent.com/u/141546?v=4"},"body":"* Junio C Hamano , 2023-06-01 15:06:\n>The patch is not _wrong_ per-se, but there are other options that are \n>common among the \"fetch\" family of commands. I counted at least these \n>should be shared between \"fetch\" and \"clone\", by splitting them out of \n>\"fetch-options.txt\" into a new file, and including that new file from \n>\"fetch-options.txt\" and \"git-clone.txt\".\n\nAgreed such a split would be better, but I don't have energy to \nimplement it.\n\n-- \nJakub Wilk\n"},{"id":"486211","messageId":"ZZRqgmDycyAXCrGZ@nand.local","threadId":"59796","inReplyTo":"xmqq1qivd8d0.fsf@gitster.g","subject":"Re: [PATCH] git-clone.txt: document -4 and -6","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-01-02T19:56:50Z","receivedAt":"2024-01-02T19:56:52Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Thu, Jun 01, 2023 at 03:06:35PM +0900, Junio C Hamano wrote:\n> Jakub Wilk writes:\n>\n> > These options were added in c915f11eb4 (\"connect & http: support -4 and\n> > -6 switches for remote operations\").\n> >\n> > Signed-off-by: Jakub Wilk \n> > ---\n> > Documentation/git-clone.txt | 8 ++++++++\n> > 1 file changed, 8 insertions(+)\n>\n> The patch is not _wrong_ per-se, but there are other options that\n> are common among the \"fetch\" family of commands. I counted at least\n> these should be shared between \"fetch\" and \"clone\", by splitting\n> them out of \"fetch-options.txt\" into a new file, and including that\n> new file from \"fetch-options.txt\" and \"git-clone.txt\". Those marked\n> with (?) are described in different phrasing between \"clone\" and\n> \"fetch\", and may fall into the \"let's keep them separate, because\n> they mean different things\" category (later):\n>\n> * --jobs\n> * --upload-pack\n> * --quiet (?)\n> * --verbose (?)\n> * --progress\n> * --server-option\n> * --ipv[46]\n>\n> Note that these happen to share the same name, but to \"clone\" and\n> \"fetch\" they different things, so leaving them separate is the right\n> thing to do.\n>\n> * --no-tags\n> * --recurse-submodules\n\nI wrote this ugly shell incantation to find an exhaustive list of\npotentially shareable options:\n\n $ grep '^-.*::$' ]*>//' |\n grep -Eo '^[^=]+' | awk -F] '\n /\\[no-\\]/ { print \"--\" $2; print \"--no-\" $2; next }\n { print $0 }\n ' |\n while read arg\n do\n if grep -Fwq -- $arg Documentation/fetch-options.txt &&\n grep -Fwq -- $arg Documentation/git-clone.txt\n then\n echo $arg;\n fi\n done\n\nIt turned up the following results:\n\n -a\n --depth\n --shallow-since\n --shallow-exclude\n --no-tags\n --recurse-submodules\n -j, --jobs\n -u, --upload-pack\n -q, --quiet\n -v, --verbose\n --progress\n -o, --server-option\n\n-a is a false-positive (it comes from \"you can simply run `git repack\n-a`\", which is in the clone documentation).\n\nEven though depth, and the shallow options are shared by both fetch and\nclone, they have different wording in each context, so they should be\nkept separate.\n\nI agree with your thinking that `--no-tags` and `--recurse-submodules`\nshould be kept separate.\n\nThat makes our two lists equal (modulo the --ipv[46] options, which were\npreviously not documented in git-clone(1) until this patch).\n\nThanks,\nTaylor\n"},{"id":"486219","messageId":"ZZRzxZNb2Aq+2feW@nand.local","threadId":"59796","inReplyTo":"ZZRqgmDycyAXCrGZ@nand.local","subject":"Re: [PATCH] git-clone.txt: document -4 and -6","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-01-02T20:36:21Z","receivedAt":"2024-01-02T20:36:23Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Tue, Jan 02, 2024 at 02:56:50PM -0500, Taylor Blau wrote:\n> It turned up the following results:\n>\n> -a\n> --depth\n> --shallow-since\n> --shallow-exclude\n> --no-tags\n> --recurse-submodules\n> -j, --jobs\n> -u, --upload-pack\n> -q, --quiet\n> -v, --verbose\n> --progress\n> -o, --server-option\n\nHmm. I think the story is a little more complicated. Just looking at the\nones that we agree on:\n\n * -j, --jobs\n * -u, --upload-pack\n * --progress\n * -o, --server-option\n * --[ipv]4\n * --[ipv]6\n\nNote that the 'clone' and 'fetch' versions for many of these options\nhave different wording. For example, in Documentation/git-clone.txt we\nhave:\n\n -j::\n --jobs=::\n Number of parallel children to be used for all forms of fetching.\n\nWhereas the description in the original fetch-options.txt is more\nverbose.\n\nIn fact, the story is even more complicated than that, since even though\nthe 'push' builtin would benefit from having a shared source of\ndocumentation for the --ipv4 and --ipv6 options, 'push' does not have a\n--jobs option.\n\n'clone', 'fetch', and 'pull' all share an '--upload-pack' option as you\nnote, though 'push' naturally doesn't (so we would need another ifdef\nthere, too). But the instances in 'clone', 'fetch', and 'pull' all\ndiffer in their wording (e.g., the 'clone' documentation says \"the\nrepository to clone from ...\" but the others say \"the repository to\nfetch from ...\").\n\n--progress could be shared, as could --server-option, and the two\n--ipv4/6 options. But the number of nested ifdefs necessary to share the\nother options probably dose not justify the effort to do so.\n\nThanks,\nTaylor\n"},{"id":"486221","messageId":"xmqqr0izcrfm.fsf@gitster.g","threadId":"59796","inReplyTo":"ZZRzxZNb2Aq+2feW@nand.local","subject":"Re: [PATCH] git-clone.txt: document -4 and -6","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-01-02T22:15:57Z","receivedAt":"2024-01-02T22:16:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Taylor Blau writes:\n\n> Note that the 'clone' and 'fetch' versions for many of these options\n> have different wording. For example, in Documentation/git-clone.txt we\n> have:\n>\n> -j::\n> --jobs=::\n> Number of parallel children to be used for all forms of fetching.\n>\n> Whereas the description in the original fetch-options.txt is more\n> verbose.\n\nYes, so it will be impossible to unify without changing the\nresulting text. But unless one description is clearly better for\none subcommand while the other description is also clearly better\nfor the other subcommand, we should be able to pick a better one\nthat would serve both subcommands, and that way we would improve\ndescription for one subcommand while keeping the other one the same,\nright?\n\n> In fact, the story is even more complicated than that, since even though\n> the 'push' builtin would benefit from having a shared source of\n> documentation for the --ipv4 and --ipv6 options, 'push' does not have a\n> --jobs option.\n\nSure, it won't be just \"write what is shared across all the transfer\ncommands in a single file and include it from all\". The direction\nof transfer is a reason why the options may differ, of course, so we\nmay need to have two (or three) include files if we want to go that\nroute.\n\n> --progress could be shared, as could --server-option, and the two\n> --ipv4/6 options. But the number of nested ifdefs necessary to share the\n> other options probably dose not justify the effort to do so.\n"},{"id":"486223","messageId":"ZZSNRk6W7VC23LaC@nand.local","threadId":"59796","inReplyTo":"xmqqr0izcrfm.fsf@gitster.g","subject":"Re: [PATCH] git-clone.txt: document -4 and -6","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-01-02T22:25:10Z","receivedAt":"2024-01-02T22:25:12Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Tue, Jan 02, 2024 at 02:15:57PM -0800, Junio C Hamano wrote:\n> Taylor Blau writes:\n>\n> > Note that the 'clone' and 'fetch' versions for many of these options\n> > have different wording. For example, in Documentation/git-clone.txt we\n> > have:\n> >\n> > -j::\n> > --jobs=::\n> > Number of parallel children to be used for all forms of fetching.\n> >\n> > Whereas the description in the original fetch-options.txt is more\n> > verbose.\n>\n> Yes, so it will be impossible to unify without changing the\n> resulting text. But unless one description is clearly better for\n> one subcommand while the other description is also clearly better\n> for the other subcommand, we should be able to pick a better one\n> that would serve both subcommands, and that way we would improve\n> description for one subcommand while keeping the other one the same,\n> right?\n\nRight. I meant to illustrate merely that this would probably involve\nsome word-smithing instead of just pure cut-and-paste, so that it may\nnot be worth the effort.\n\nThanks,\nTaylor\n"}]}