{"thread":{"id":"59976","subject":"[PATCH] doc: remove mentions of .gitmodules !command syntax","startedAt":"2023-07-12T16:01:27Z","lastAt":"2023-07-25T21:56:24Z","messageCount":22,"participants":["pvutov@imap.cc","Junio C Hamano","Petar Vutov"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"479411","messageId":"20230712160216.855054-1-pvutov@imap.cc","threadId":"59976","inReplyTo":null,"subject":"[PATCH] doc: remove mentions of .gitmodules !command syntax","fromName":"","fromEmail":"pvutov@imap.cc","sentAt":"2023-07-12T16:02:03Z","receivedAt":"2023-07-12T16:01:27Z","isPatch":true,"sender":{"key":"pvutov@imap.cc","avatar":"https://avatars.githubusercontent.com/u/11945431?v=4"},"body":"From: Petar Vutov \n\nTo mitigate CVE-2019-19604, the capability to configure\n`git submodule update` to execute custom commands was\nremoved in v2.20.2.\n\nThe git-submodule documentation still mentions the now-unsupported\nsyntax, which is misleading.\n\nRemove the leftover documentation.\n\nSigned-off-by: Petar Vutov \n---\n Documentation/git-submodule.txt | 6 ------\n 1 file changed, 6 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 4d3ab6b9f9..b40ac72f75 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -163,12 +163,6 @@ checked out in the submodule.\n The following 'update' procedures are only available via the\n `submodule..update` configuration variable:\n \n-\tcustom command;; arbitrary shell command that takes a single\n-\t argument (the sha1 of the commit recorded in the\n-\t superproject) is executed. When `submodule..update`\n-\t is set to '!command', the remainder after the exclamation mark\n-\t is the custom command.\n-\n \tnone;; the submodule is not updated.\n \n If the submodule is not yet initialized, and you just want to use the\n-- \n2.41.0\n\n"},{"id":"479413","messageId":"xmqqleflt75z.fsf@gitster.g","threadId":"59976","inReplyTo":"20230712160216.855054-1-pvutov@imap.cc","subject":"Re: [PATCH] doc: remove mentions of .gitmodules !command syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-07-12T16:40:24Z","receivedAt":"2023-07-12T16:40:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"pvutov@imap.cc writes:\n\n> From: Petar Vutov \n>\n> To mitigate CVE-2019-19604, the capability to configure\n> `git submodule update` to execute custom commands was\n> removed in v2.20.2.\n>\n> The git-submodule documentation still mentions the now-unsupported\n> syntax, which is misleading.\n>\n> Remove the leftover documentation.\n\nThe change during v2.20.2 timeperiod you have in mind may be\ne904deb8 (submodule: reject submodule.update = !command in\n.gitmodules, 2019-12-05). The key phrase is \"in .gitmodules\"\nas it did not forbid writing update command in the configuration.\n\nThe pre-context lines of your patch (see below) say that the 'custom\ncommand' option and 'none' option are only available via the\n`submodule..update` configuration variable. IOW, this part of\nthe documentation does not talk about the .gitmodules file---it\ntalks about what you can say in the configuration file (which is\nunder your local control).\n\nI think the existing text that came from fc01a5d2 (submodule update\ndocumentation: don't repeat ourselves, 2016-12-27) may be\nmisleading, and may has room for improvement, but I do not think it\nis wrong per-se. If we remove it, there is nowhere else that teaches\nusers !cmd can be set in their configuration files, or is there?\n\nThanks.\n\n> Signed-off-by: Petar Vutov \n> ---\n> Documentation/git-submodule.txt | 6 ------\n> 1 file changed, 6 deletions(-)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 4d3ab6b9f9..b40ac72f75 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -163,12 +163,6 @@ checked out in the submodule.\n> The following 'update' procedures are only available via the\n> `submodule..update` configuration variable:\n> \n> -\tcustom command;; arbitrary shell command that takes a single\n> -\t argument (the sha1 of the commit recorded in the\n> -\t superproject) is executed. When `submodule..update`\n> -\t is set to '!command', the remainder after the exclamation mark\n> -\t is the custom command.\n> -\n> \tnone;; the submodule is not updated.\n> \n> If the submodule is not yet initialized, and you just want to use the\n"},{"id":"479415","messageId":"d775437e-7fa3-189b-a1c3-4fd358dd9768@imap.cc","threadId":"59976","inReplyTo":"xmqqleflt75z.fsf@gitster.g","subject":"Re: [PATCH] doc: remove mentions of .gitmodules !command syntax","fromName":"Petar Vutov","fromEmail":"pvutov@imap.cc","sentAt":"2023-07-12T17:30:50Z","receivedAt":"2023-07-12T17:30:02Z","isPatch":true,"sender":{"key":"pvutov@imap.cc","avatar":"https://avatars.githubusercontent.com/u/11945431?v=4"},"body":"On 7/12/23 18:40, Junio C Hamano wrote:\n> pvutov@imap.cc writes:\n> \n>> From: Petar Vutov \n>>\n>> To mitigate CVE-2019-19604, the capability to configure\n>> `git submodule update` to execute custom commands was\n>> removed in v2.20.2.\n>>\n>> The git-submodule documentation still mentions the now-unsupported\n>> syntax, which is misleading.\n>>\n>> Remove the leftover documentation.\n> \n> The change during v2.20.2 timeperiod you have in mind may be\n> e904deb8 (submodule: reject submodule.update = !command in\n> .gitmodules, 2019-12-05). The key phrase is \"in .gitmodules\"\n> as it did not forbid writing update command in the configuration.\n> \n> The pre-context lines of your patch (see below) say that the 'custom\n> command' option and 'none' option are only available via the\n> `submodule..update` configuration variable. IOW, this part of\n> the documentation does not talk about the .gitmodules file---it\n> talks about what you can say in the configuration file (which is\n> under your local control).\n> \n> I think the existing text that came from fc01a5d2 (submodule update\n> documentation: don't repeat ourselves, 2016-12-27) may be\n> misleading, and may has room for improvement, but I do not think it\n> is wrong per-se. If we remove it, there is nowhere else that teaches\n> users !cmd can be set in their configuration files, or is there?\n> \n> Thanks.\n\nThanks for the review. I was not aware of the .gitconfig use case.\nI hit that paragraph while trying to enforce sparse-checkout\nvia .gitmodules. Yet the gitmodules doc is clear enough:\n\n\"See description of update command in git-submodule[1] for their \nmeaning. For security reasons, the !command form is not accepted here.\"\n\nClearly I followed the link in the first sentence without reading the \nsecond :)\n\nPerhaps the term \"configuration variable\" in\n\n\"The following update procedures are only available via the \nsubmodule..update configuration variable:\"\n\nis more specific and technical than immediately obvious - I would have \nexpected the contents of .gitmodules to be a form of (repository) \nconfiguration. But that is just bikeshedding.\n\n> \n>> Signed-off-by: Petar Vutov \n>> ---\n>> Documentation/git-submodule.txt | 6 ------\n>> 1 file changed, 6 deletions(-)\n>>\n>> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n>> index 4d3ab6b9f9..b40ac72f75 100644\n>> --- a/Documentation/git-submodule.txt\n>> +++ b/Documentation/git-submodule.txt\n>> @@ -163,12 +163,6 @@ checked out in the submodule.\n>> The following 'update' procedures are only available via the\n>> `submodule..update` configuration variable:\n>> \n>> -\tcustom command;; arbitrary shell command that takes a single\n>> -\t argument (the sha1 of the commit recorded in the\n>> -\t superproject) is executed. When `submodule..update`\n>> -\t is set to '!command', the remainder after the exclamation mark\n>> -\t is the custom command.\n>> -\n>> \tnone;; the submodule is not updated.\n>> \n>> If the submodule is not yet initialized, and you just want to use the\n"},{"id":"479416","messageId":"xmqqfs5tt3qz.fsf@gitster.g","threadId":"59976","inReplyTo":"d775437e-7fa3-189b-a1c3-4fd358dd9768@imap.cc","subject":"Re: [PATCH] doc: remove mentions of .gitmodules !command syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-07-12T17:54:12Z","receivedAt":"2023-07-12T17:54:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petar Vutov writes:\n\n> Perhaps the term \"configuration variable\" in\n>\n> \"The following update procedures are only available via the\n> submodule..update configuration variable:\"\n>\n> is more specific and technical than immediately obvious - I would have\n> expected the contents of .gitmodules to be a form of (repository)\n> configuration. But that is just bikeshedding.\n\nNot necessarily. It is always good to learn how \"normal people\"\n(read: those other than who develop and write documentation for Git)\nwould react to and understand what we write in the manual pages, as\nthat is the only way we can find what is confusing, ambiguous and\ncan be improved.\n\nPerhaps\n\n \"... available via the ... configuration variable, and cannot be\n used in the .gitmodules file\"\n\nwould have helped you?\n\nThanks.\n"},{"id":"479418","messageId":"7090349c-4485-d5c4-1f26-190974864f72@imap.cc","threadId":"59976","inReplyTo":"xmqqfs5tt3qz.fsf@gitster.g","subject":"Re: [PATCH] doc: remove mentions of .gitmodules !command syntax","fromName":"Petar Vutov","fromEmail":"pvutov@imap.cc","sentAt":"2023-07-12T18:48:10Z","receivedAt":"2023-07-12T18:47:22Z","isPatch":true,"sender":{"key":"pvutov@imap.cc","avatar":"https://avatars.githubusercontent.com/u/11945431?v=4"},"body":"\n\nOn 7/12/23 19:54, Junio C Hamano wrote:\n> \n> Perhaps\n> \n> \"... available via the ... configuration variable, and cannot be\n> used in the .gitmodules file\"\n> \n> would have helped you?\n> \n> Thanks.\n\nI think that addition is good and makes the intent clearer.\n\nBut it's slightly wrong - only 'custom command' cannot be used in \n.gitmodules. 'none' is legal (and mentioned in the gitmodules doc as such).\n\nWhat about something like this?\n\n From 7b2fcd9a56b4954863cc74e1cf89a4b9d9d3ad52 Mon Sep 17 00:00:00 2001\nFrom: Petar Vutov \nDate: Wed, 12 Jul 2023 20:40:10 +0200\nSubject: [PATCH] docs: highlight that .gitmodules does not support !command\n\nThe `custom command` and `none` entries are described as sharing the\nsame limitations, but one is allowed in .gitmodules and the other is\nnot. Instead, describe their limitations separately and with slightly\nmore detail.\n\nSigned-off-by: Petar Vutov \n---\n Documentation/git-submodule.txt | 9 ++++++---\n 1 file changed, 6 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt \nb/Documentation/git-submodule.txt\nindex 4d3ab6b9f9..eb024a1531 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -160,16 +160,19 @@ checked out in the submodule.\n \tmerge;; the commit recorded in the superproject will be merged\n \t into the current branch in the submodule.\n\n-The following 'update' procedures are only available via the\n-`submodule..update` configuration variable:\n-\n \tcustom command;; arbitrary shell command that takes a single\n \t argument (the sha1 of the commit recorded in the\n \t superproject) is executed. When `submodule..update`\n \t is set to '!command', the remainder after the exclamation mark\n \t is the custom command.\n++\n+Custom commands are only available via the `submodule..update`\n+configuration variable. They cannot be used in the .gitmodules file.\n\n \tnone;; the submodule is not updated.\n++\n+The `none` update procedure is only available via the .gitmodules file\n+or the `submodule..update` configuration variable.\n\n If the submodule is not yet initialized, and you just want to use the\n setting as stored in `.gitmodules`, you can automatically initialize the\n-- \n2.41.0\n\n\n"},{"id":"479422","messageId":"xmqqa5w0swcs.fsf@gitster.g","threadId":"59976","inReplyTo":"7090349c-4485-d5c4-1f26-190974864f72@imap.cc","subject":"Re: [PATCH] doc: remove mentions of .gitmodules !command syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-07-12T20:33:55Z","receivedAt":"2023-07-12T20:34:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petar Vutov writes:\n\n> On 7/12/23 19:54, Junio C Hamano wrote:\n>> Perhaps\n>> \"... available via the ... configuration variable, and cannot\n>> be\n>> used in the .gitmodules file\"\n>> would have helped you?\n>> Thanks.\n>\n> I think that addition is good and makes the intent clearer.\n>\n> But it's slightly wrong - only 'custom command' cannot be used in\n> .gitmodules. 'none' is legal (and mentioned in the gitmodules doc as\n> such).\n\nHmph, that will be a bugfix for fc01a5d2 (submodule update\ndocumentation: don't repeat ourselves, 2016-12-27). I think you are\ntechnically correct.\n\n Side note: but is there a useful use case to set it to 'none' in\n \".gitmodules\" in the first place? If there is not, saying that\n \"'none' is only useful in the configuration files\" is not quite\n wrong per-se.\n\n> \tmerge;; the commit recorded in the superproject will be merged\n> \t into the current branch in the submodule.\n>\n> -The following 'update' procedures are only available via the\n> -`submodule..update` configuration variable:\n> -\n> \tcustom command;; arbitrary shell command that takes a single\n> \t argument (the sha1 of the commit recorded in the\n> \t superproject) is executed. When `submodule..update`\n> \t is set to '!command', the remainder after the exclamation mark\n> \t is the custom command.\n> ++\n> +Custom commands are only available via the `submodule..update`\n> +configuration variable. They cannot be used in the .gitmodules file.\n\nSounds good. s/available/allowed/, perhaps.\n\n> \tnone;; the submodule is not updated.\n> ++\n> +The `none` update procedure is only available via the .gitmodules file\n> +or the `submodule..update` configuration variable.\n\nThis side we do not need \"only\" anywhere in the sentence, do we?\n\nThanks.\n"},{"id":"479468","messageId":"7ce31744-8c9d-da75-126c-e92dfbb4cf16@imap.cc","threadId":"59976","inReplyTo":"xmqqa5w0swcs.fsf@gitster.g","subject":"Re: [PATCH] doc: remove mentions of .gitmodules !command syntax","fromName":"Petar Vutov","fromEmail":"pvutov@imap.cc","sentAt":"2023-07-13T19:20:17Z","receivedAt":"2023-07-13T19:19:50Z","isPatch":true,"sender":{"key":"pvutov@imap.cc","avatar":"https://avatars.githubusercontent.com/u/11945431?v=4"},"body":"On 7/12/23 22:33, Junio C Hamano wrote:\n> \n> Side note: but is there a useful use case to set it to 'none' in\n> \".gitmodules\" in the first place? If there is not, saying that\n> \"'none' is only useful in the configuration files\" is not quite\n> wrong per-se.\n\nA twisted person might use it to commit a truly empty folder, without \neven a .gitkeep file. Whether that's a useful use case, I don't know.\n\n> \n> Sounds good. s/available/allowed/, perhaps.\n> \n>> \tnone;; the submodule is not updated.\n>> ++\n>> +The `none` update procedure is only available via the .gitmodules file\n>> +or the `submodule..update` configuration variable.\n> \n> This side we do not need \"only\" anywhere in the sentence, do we?\n> \n> Thanks.\n\nI will address both of those and include your bugfix blurb in v3. Still \nfiguring out how to properly reference the previous patches using \ngit-send-email..\n"},{"id":"479469","messageId":"20230713193342.1053968-1-pvutov@imap.cc","threadId":"59976","inReplyTo":"d775437e-7fa3-189b-a1c3-4fd358dd9768@imap.cc","subject":"[PATCH v3 1/1] docs: highlight that .gitmodules does not support !command","fromName":"","fromEmail":"pvutov@imap.cc","sentAt":"2023-07-13T19:33:42Z","receivedAt":"2023-07-13T19:33:00Z","isPatch":true,"sender":{"key":"pvutov@imap.cc","avatar":"https://avatars.githubusercontent.com/u/11945431?v=4"},"body":"From: Petar Vutov \n\nBugfix for fc01a5d2 (submodule update documentation: don't repeat\nourselves, 2016-12-27).\n\nThe `custom command` and `none` entries are described as sharing the\nsame limitations, but one is allowed in .gitmodules and the other is\nnot. Instead, describe their limitations separately and in slightly\nmore detail.\n\nSigned-off-by: Petar Vutov \n---\n\nChanges from v1:\nDon't delete the documentation for `!command`. Instead, highlight\nthe differences in the limitations of `none` and `!command`.\n\nChanges from v2:\nImprove phrasing.\nAdd the bugfix blurb in the commit message.\n\n Documentation/git-submodule.txt | 9 ++++++---\n 1 file changed, 6 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 4d3ab6b9f9..69ee2cd6b0 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -160,16 +160,19 @@ checked out in the submodule.\n \tmerge;; the commit recorded in the superproject will be merged\n \t into the current branch in the submodule.\n \n-The following 'update' procedures are only available via the\n-`submodule..update` configuration variable:\n-\n \tcustom command;; arbitrary shell command that takes a single\n \t argument (the sha1 of the commit recorded in the\n \t superproject) is executed. When `submodule..update`\n \t is set to '!command', the remainder after the exclamation mark\n \t is the custom command.\n++\n+Custom commands are only allowed in the `submodule..update`\n+git-config variable. They cannot be used in the .gitmodules file.\n \n \tnone;; the submodule is not updated.\n++\n+The `none` update procedure is allowed in the .gitmodules file\n+or the `submodule..update` git-config variable.\n \n If the submodule is not yet initialized, and you just want to use the\n setting as stored in `.gitmodules`, you can automatically initialize the\n-- \n2.41.0\n\n"},{"id":"479470","messageId":"xmqqh6q7ppwi.fsf@gitster.g","threadId":"59976","inReplyTo":"7ce31744-8c9d-da75-126c-e92dfbb4cf16@imap.cc","subject":"Re: [PATCH] doc: remove mentions of .gitmodules !command syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-07-13T19:33:49Z","receivedAt":"2023-07-13T19:34:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petar Vutov writes:\n\n> I will address both of those and include your bugfix blurb in\n> v3. Still figuring out how to properly reference the previous patches\n> using git-send-email..\n\n$ git send-email --in-reply-to='<7090349c-4485-d5c4-1f26-190974864f72@imap.cc>' ...\n\n"},{"id":"479471","messageId":"xmqqcz0vppoc.fsf@gitster.g","threadId":"59976","inReplyTo":"20230713193342.1053968-1-pvutov@imap.cc","subject":"Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-07-13T19:38:43Z","receivedAt":"2023-07-13T19:38:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"pvutov@imap.cc writes:\n\n> From: Petar Vutov \n>\n> Bugfix for fc01a5d2 (submodule update documentation: don't repeat\n> ourselves, 2016-12-27).\n>\n> The `custom command` and `none` entries are described as sharing the\n> same limitations, but one is allowed in .gitmodules and the other is\n> not. Instead, describe their limitations separately and in slightly\n> more detail.\n\nSounds sensible.\n\n>\n> Signed-off-by: Petar Vutov \n> ---\n>\n> Changes from v1:\n> Don't delete the documentation for `!command`. Instead, highlight\n> the differences in the limitations of `none` and `!command`.\n>\n> Changes from v2:\n> Improve phrasing.\n> Add the bugfix blurb in the commit message.\n>\n> Documentation/git-submodule.txt | 9 ++++++---\n> 1 file changed, 6 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 4d3ab6b9f9..69ee2cd6b0 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -160,16 +160,19 @@ checked out in the submodule.\n> \tmerge;; the commit recorded in the superproject will be merged\n> \t into the current branch in the submodule.\n> \n> -The following 'update' procedures are only available via the\n> -`submodule..update` configuration variable:\n> -\n> \tcustom command;; arbitrary shell command that takes a single\n> \t argument (the sha1 of the commit recorded in the\n> \t superproject) is executed. When `submodule..update`\n> \t is set to '!command', the remainder after the exclamation mark\n> \t is the custom command.\n> ++\n> +Custom commands are only allowed in the `submodule..update`\n> +git-config variable. They cannot be used in the .gitmodules file.\n> \n> \tnone;; the submodule is not updated.\n> ++\n> +The `none` update procedure is allowed in the .gitmodules file\n> +or the `submodule..update` git-config variable.\n\nBut the usual ones like \"merge\" are also allowed in both places.\nDoes this still need to be said?\n\nI wonder if it makes more sense to swap the order of these two\nentries, showing \"none\" without any additional text first, and\nthen describe \"custom command\" with the note, exactly like you\ndid above.\n\n\n\n"},{"id":"479472","messageId":"a8bde495-57fc-6a70-e325-6e2a52f40552@imap.cc","threadId":"59976","inReplyTo":"20230713193342.1053968-1-pvutov@imap.cc","subject":"Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command","fromName":"Petar Vutov","fromEmail":"pvutov@imap.cc","sentAt":"2023-07-13T19:46:55Z","receivedAt":"2023-07-13T19:46:04Z","isPatch":true,"sender":{"key":"pvutov@imap.cc","avatar":"https://avatars.githubusercontent.com/u/11945431?v=4"},"body":"Oops, this was supposed to go under \n<7090349c-4485-d5c4-1f26-190974864f72@imap.cc>..\n\nSide question in this side thread: I was tempted to change the mention \nof \"configuration variable\" with \"git-config variable\", to highlight the \nnarrow meaning of the term. But I grepped and that term is used \neverywhere in the documentation. Changing it only in this section would \nbe inconsistent.\n\nIf I were to go through all those mentions and figure out which \n\"configuration variable\" mentions refer exclusively to `git-config`, wis \nthere interest in changing them to something like \"git-config variable\" \nin a potential future patch? Or do we like the term \"configuration \nvariable\"?\n"},{"id":"479473","messageId":"xmqqwmz3oacg.fsf@gitster.g","threadId":"59976","inReplyTo":"a8bde495-57fc-6a70-e325-6e2a52f40552@imap.cc","subject":"Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-07-13T19:55:11Z","receivedAt":"2023-07-13T19:55:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petar Vutov writes:\n\n> Oops, this was supposed to go under\n> <7090349c-4485-d5c4-1f26-190974864f72@imap.cc>..\n>\n> Side question in this side thread: I was tempted to change the mention\n> of \"configuration variable\" with \"git-config variable\", to highlight\n> the narrow meaning of the term. But I grepped and that term is used\n> everywhere in the documentation. Changing it only in this section\n> would be inconsistent.\n\nDon't. People should be familiar with \"configuration variable\", but\nmay not be with \"git-config variable\".\n\nHow about doing it this way? I moved 'none' up, as it is effective\nin `.gitmodules` and as a configuration variable, just like all\nothers, and then completely rewrote the somewhat awkward explanation\nof the custom command thing.\n\n----- >8 --------- >8 --------- >8 --------- >8 ----\nSubject: submodule: clarify that \"!custom command\" is the only oddball\n\nWe singled out 'none' and 'custom command' as submodule update modes\nthat cannot be specified in the .gitmodules file, but 'none' can\nappear there, and use of a custom command is the only oddball.\n\nMove the description of 'none' up, clarify how the custom command is\nused, and explicitly say it cannot be used in the `.gitmodules` file.\n\nStrictly speaking, the last one should not be needed, as we already\nsay `configuration variable`, but to new readers, the distinction\nbetween the configuration variable and settings that appear in the\n.gitmodules file may not be apparent; hopefully the new text will\nhelp them understand where it can(not) be used.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-submodule.txt | 16 +++++++---------\n 1 file changed, 7 insertions(+), 9 deletions(-)\n\ndiff --git c/Documentation/git-submodule.txt w/Documentation/git-submodule.txt\nindex 4d3ab6b9f9..391ff0dbf2 100644\n--- c/Documentation/git-submodule.txt\n+++ w/Documentation/git-submodule.txt\n@@ -160,17 +160,15 @@ checked out in the submodule.\n \tmerge;; the commit recorded in the superproject will be merged\n \t into the current branch in the submodule.\n \n-The following 'update' procedures are only available via the\n-`submodule..update` configuration variable:\n-\n-\tcustom command;; arbitrary shell command that takes a single\n-\t argument (the sha1 of the commit recorded in the\n-\t superproject) is executed. When `submodule..update`\n-\t is set to '!command', the remainder after the exclamation mark\n-\t is the custom command.\n-\n \tnone;; the submodule is not updated.\n \n+\tcustom command;; When the `submodule..update`\n+\t configuration variable is set to `!custom command`, the\n+\t object name of the commit recorded in the superproject\n+\t for the submodule is appended to the `custom command`\n+\t string and gets executed. Note that this mechanism\n+\t cannot be used in the `.gitmodules` file.\n+\n If the submodule is not yet initialized, and you just want to use the\n setting as stored in `.gitmodules`, you can automatically initialize the\n submodule with the `--init` option.\n"},{"id":"479477","messageId":"9de918bc-6913-0486-02dd-5b4028a7fe1b@imap.cc","threadId":"59976","inReplyTo":"xmqqwmz3oacg.fsf@gitster.g","subject":"Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command","fromName":"Petar Vutov","fromEmail":"pvutov@imap.cc","sentAt":"2023-07-13T20:34:16Z","receivedAt":"2023-07-13T20:33:28Z","isPatch":true,"sender":{"key":"pvutov@imap.cc","avatar":"https://avatars.githubusercontent.com/u/11945431?v=4"},"body":"On 7/13/23 21:55, Junio C Hamano wrote:\n> Petar Vutov writes:\n> \n> Don't. People should be familiar with \"configuration variable\", but\n> may not be with \"git-config variable\".\n\nRight, on closer inspection this collision with .gitmodules is rather \nniche to start with. Few things in .gitconfig are also legal in .gitmodules.\n\n> \n> -The following 'update' procedures are only available via the\n> -`submodule..update` configuration variable:\n> -\n> -\tcustom command;; arbitrary shell command that takes a single\n> -\t argument (the sha1 of the commit recorded in the\n> -\t superproject) is executed. When `submodule..update`\n> -\t is set to '!command', the remainder after the exclamation mark\n> -\t is the custom command.\n> -\n> \tnone;; the submodule is not updated.\n> \n> +\tcustom command;; When the `submodule..update`\n> +\t configuration variable is set to `!custom command`, the\n> +\t object name of the commit recorded in the superproject\n> +\t for the submodule is appended to the `custom command`\n> +\t string and gets executed. Note that this mechanism\n> +\t cannot be used in the `.gitmodules` file.\n> +\n> If the submodule is not yet initialized, and you just want to use the\n> setting as stored in `.gitmodules`, you can automatically initialize the\n> submodule with the `--init` option.\n\nI prefer the original description as it uses shorter sentences. I can't \nhold that 5-liner in my head :)\n\nBut now I really am bikeshedding, and I've taken enough of your time. I \nwill send a v4 with just the .gitmodules disclaimer, no rewrite, in case \nyou end up agreeing.\n"},{"id":"479478","messageId":"20230713203421.1061589-1-pvutov@imap.cc","threadId":"59976","inReplyTo":"20230713193342.1053968-1-pvutov@imap.cc","subject":"[PATCH v4] docs: highlight that .gitmodules does not support !command","fromName":"","fromEmail":"pvutov@imap.cc","sentAt":"2023-07-13T20:34:21Z","receivedAt":"2023-07-13T20:33:31Z","isPatch":true,"sender":{"key":"pvutov@imap.cc","avatar":"https://avatars.githubusercontent.com/u/11945431?v=4"},"body":"From: Petar Vutov \n\nBugfix for fc01a5d2 (submodule update documentation: don't repeat\nourselves, 2016-12-27).\n\nThe `custom command` and `none` entries are described as sharing the\nsame limitations, but one is allowed in .gitmodules and the other is\nnot. Instead, highlight the limitation of `custom command` only.\n\nSigned-off-by: Petar Vutov \n---\n\nChanges from v1:\nDon't delete the documentation for `!command`. Instead, highlight\nthe differences in the limitations of `none` and `!command`.\n\nChanges from v2:\nImprove phrasing.\nAdd the bugfix blurb in the commit message.\n\nChanges from v3:\nKeep the description of `none` unchanged and just move it up.\n\n Documentation/git-submodule.txt | 8 +++-----\n 1 file changed, 3 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 4d3ab6b9f9..b3303afb8f 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -160,16 +160,14 @@ checked out in the submodule.\n \tmerge;; the commit recorded in the superproject will be merged\n \t into the current branch in the submodule.\n \n-The following 'update' procedures are only available via the\n-`submodule..update` configuration variable:\n+\tnone;; the submodule is not updated.\n \n \tcustom command;; arbitrary shell command that takes a single\n \t argument (the sha1 of the commit recorded in the\n \t superproject) is executed. When `submodule..update`\n \t is set to '!command', the remainder after the exclamation mark\n-\t is the custom command.\n-\n-\tnone;; the submodule is not updated.\n+\t is the custom command. Note that this mechanism\n+\t cannot be used in the .gitmodules file.\n \n If the submodule is not yet initialized, and you just want to use the\n setting as stored in `.gitmodules`, you can automatically initialize the\n-- \n2.41.0\n\n"},{"id":"479480","messageId":"xmqqa5vzo7jy.fsf@gitster.g","threadId":"59976","inReplyTo":"9de918bc-6913-0486-02dd-5b4028a7fe1b@imap.cc","subject":"Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-07-13T20:55:29Z","receivedAt":"2023-07-13T20:55:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petar Vutov writes:\n\n> I prefer the original description as it uses shorter sentences. I\n> can't hold that 5-liner in my head :)\n\nBut you are comparing oranges and apples, aren't you? You are not\ncounting \"oh by the way this cannot be in .gitmodules\" as part of 5.\n\n> But now I really am bikeshedding, and I've taken enough of your\n> time. I will send a v4 with just the .gitmodules disclaimer, no\n> rewrite, in case you end up agreeing.\n\nAfter reading the original again and again, I hate more and more the\nway the original wasted too many words to refer to one thing twice\n(e.g. \"arbitrary command\" and then \"is the custom command\", \"a\nsingle argument\" and then the parenthesized explanation of it)\nwithout adding any clarity.\n\n"},{"id":"479483","messageId":"xmqqv8enmr21.fsf@gitster.g","threadId":"59976","inReplyTo":"xmqqa5vzo7jy.fsf@gitster.g","subject":"Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-07-13T21:37:10Z","receivedAt":"2023-07-13T21:37:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> After reading the original again and again, I hate more and more the\n> way the original wasted too many words to refer to one thing twice\n> (e.g. \"arbitrary command\" and then \"is the custom command\", \"a\n> single argument\" and then the parenthesized explanation of it)\n> without adding any clarity.\n\nAnother thing I noticed is that this section is ONLY talking about\nthe configuration variable, so everything both of us have been\nsaying misses the point. The preamble before the choices\n(\"checkout\", \"rebase\", \"merge\", \"custom\" and \"none\") are listed read\nlike so:\n\n update [--init] [--remote] [-N|--no-f...\n +\n --\n Update the registered submodules to match what the superproject\n expects by cloning missing submodules, fetching missing commits\n in submodules and updating the working tree of\n the submodules. The \"updating\" can be done in several ways depending\n on command line options and the value of `submodule..update`\n configuration variable. The command line option takes precedence over\n the configuration variable. If neither is given, a 'checkout' is performed.\n The 'update' procedures supported both from the command line as well as\n through the `submodule..update` configuration are:\n\nThen why do we even think about referring to \".gitmodules\" here? It\nis because of this behaviour that is described elsewhere:\n\n init [--] [...]::\n Initialize the submodules recorded in the index (which were\n added and committed elsewhere) by setting `submodule.$name.url`\n in .git/config. It uses the same setting from `.gitmodules` as\n a template. If the URL is relative, it will be resolved using\n the default remote. If there is no default remote, the current\n repository will be assumed to be upstream.\n +\n Optional arguments limit which submodules will be initialized.\n If no path is specified and submodule.active has been configured, submodules\n configured to be active will be initialized, otherwise all submodules are\n initialized.\n +\n When present, it will also copy the value of `submodule.$name.update`.\n\nand this description is very flawed. It says \"X is copied\", but not\n\"X is copied from A to B\". It also does not say that even if you\nhave a custom command there, it does not get copied.\n\nIt copies submodule..update from the \".gitmodules\" to the\nconfiguraiton. And that is the reason why, the configuration may\nhave \"submodule..update\" in it after running \"git init\" to\ninitialize a submodule. And that is why the choices of update\nmethods listed in the part your patch touched talked about things\nthat can both appear in .gitmodules and the configuration. But the\nlinkage is quite indirect.\n\nSo, here is another round, this time the primary change is to stop\ntalking about `.gitmodules` in the \"update\" section, but explain how\n`.gitmodules` file is used in the \"init\" section.\n\n Documentation/git-submodule.txt | 16 +++++++++-------\n 1 file changed, 9 insertions(+), 7 deletions(-)\n\ndiff --git c/Documentation/git-submodule.txt w/Documentation/git-submodule.txt\nindex 4d3ab6b9f9..5248840b18 100644\n--- c/Documentation/git-submodule.txt\n+++ w/Documentation/git-submodule.txt\n@@ -95,7 +95,7 @@ too (and can also report changes to a submodule's work tree).\n init [--] [...]::\n \tInitialize the submodules recorded in the index (which were\n \tadded and committed elsewhere) by setting `submodule.$name.url`\n-\tin .git/config. It uses the same setting from `.gitmodules` as\n+\tin `.git/config`, using the same setting from `.gitmodules` as\n \ta template. If the URL is relative, it will be resolved using\n \tthe default remote. If there is no default remote, the current\n \trepository will be assumed to be upstream.\n@@ -105,9 +105,12 @@ If no path is specified and submodule.active has been configured, submodules\n configured to be active will be initialized, otherwise all submodules are\n initialized.\n +\n-When present, it will also copy the value of `submodule.$name.update`.\n-This command does not alter existing information in .git/config.\n-You can then customize the submodule clone URLs in .git/config\n+It will also copy the value of `submodule.$name.update`, if present in\n+the `.gitmodules` file, to `.git/config`, but (1) this command does not\n+alter existing information in `.git/config`, and (2) `submodule.$name.update`\n+that is set to a custom command is *not* copied for security reasons.\n++\n+You can then customize the submodule clone URLs in `.git/config`\n for your local setup and proceed to `git submodule update`;\n you can also just use `git submodule update --init` without\n the explicit 'init' step if you do not intend to customize\n@@ -143,6 +146,8 @@ the submodules. The \"updating\" can be done in several ways depending\n on command line options and the value of `submodule..update`\n configuration variable. The command line option takes precedence over\n the configuration variable. If neither is given, a 'checkout' is performed.\n+(note: what is in `.gitmodules` file is irrelevant at this point;\n+see `git submodule init` above for how `.gitmodules` is used).\n The 'update' procedures supported both from the command line as well as\n through the `submodule..update` configuration are:\n \n@@ -160,9 +165,6 @@ checked out in the submodule.\n \tmerge;; the commit recorded in the superproject will be merged\n \t into the current branch in the submodule.\n \n-The following 'update' procedures are only available via the\n-`submodule..update` configuration variable:\n-\n \tcustom command;; arbitrary shell command that takes a single\n \t argument (the sha1 of the commit recorded in the\n \t superproject) is executed. When `submodule..update`\n"},{"id":"479490","messageId":"0e566b2b-8e61-3895-59a6-292dfc46bd4f@imap.cc","threadId":"59976","inReplyTo":"xmqqv8enmr21.fsf@gitster.g","subject":"Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command","fromName":"Petar Vutov","fromEmail":"pvutov@imap.cc","sentAt":"2023-07-13T21:47:59Z","receivedAt":"2023-07-13T21:47:10Z","isPatch":true,"sender":{"key":"pvutov@imap.cc","avatar":"https://avatars.githubusercontent.com/u/11945431?v=4"},"body":"Thanks. I'll digest this and reply tomorrow. Until then, I remembered \nsomething:\n\nOn 7/13/23 23:37, Junio C Hamano wrote:\n> \n> -The following 'update' procedures are only available via the\n> -`submodule..update` configuration variable:\n> -\n\nOriginally I was trying to write a disclaimer about `none` because the \ncurrent documentation we're removing seems to be trying to say something \nlike this:\n\n\"The following `update` procedures are not supported via the command \nline: none, custom command\"\n\nIt's referencing this bit at the top:\n\n > The 'update' procedures supported both from the command line as well as\n > through the `submodule..update` configuration are:\n\n\n"},{"id":"479495","messageId":"xmqqcz0vla47.fsf@gitster.g","threadId":"59976","inReplyTo":"0e566b2b-8e61-3895-59a6-292dfc46bd4f@imap.cc","subject":"Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-07-13T22:28:24Z","receivedAt":"2023-07-13T22:28:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petar Vutov writes:\n\n> Thanks. I'll digest this and reply tomorrow.\n\nThanks.\n\n> \"The following `update` procedures are not supported via the command\n> line: none, custom command\"\n\nAh, that is a good thing to notice. Yes, the command line override\nis also something we need to explain.\n"},{"id":"479536","messageId":"0d29ac42-4e8f-71b6-b85f-00de182e2957@imap.cc","threadId":"59976","inReplyTo":"xmqqv8enmr21.fsf@gitster.g","subject":"Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command","fromName":"Petar Vutov","fromEmail":"pvutov@imap.cc","sentAt":"2023-07-14T22:03:31Z","receivedAt":"2023-07-14T22:02:49Z","isPatch":true,"sender":{"key":"pvutov@imap.cc","avatar":"https://avatars.githubusercontent.com/u/11945431?v=4"},"body":"On 7/13/23 23:37, Junio C Hamano wrote:\n> So, here is another round, this time the primary change is to stop\n> talking about `.gitmodules` in the \"update\" section, but explain how\n> `.gitmodules` file is used in the \"init\" section.\n\nLooks good to me.\n\nI applied your patch and then made some additions, which I'll append at \nthe end of this message. Summary:\n\n* Added your rewrite from yesterday. I like that it's more precise than \nthe current docs, but I struggle with the complexity of the first \nsentence. I wanted to make it easier to follow by splitting it in two \nsomehow. Instead I ended up with an introductory sentence summarizing \nthe functionality with small words.\n\n* In gitmodules.txt, moved the security disclaimer so people are more \nlikely to see it before they follow the link to git-submodule.txt.\n\n* Explicitly called out `none` and `custom command` as being unusable on \nthe command line (and in .gitmodules). I expect that you won't want that \n.gitmodules mention anymore, but I left it in for now, up to you.\n\nBy the way, I ran into an SO question where some people were discussing \nthe same issue: https://stackoverflow.com/q/65744067/876832\n\nThe diff below is based on top of your patch from yesterday, since I \nassume that you don't want to look at a mishmash of both patches.\n\n---\n Documentation/git-submodule.txt | 19 ++++++++++++-------\n Documentation/gitmodules.txt | 6 +++---\n 2 files changed, 15 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt \nb/Documentation/git-submodule.txt\nindex 5248840b18..695730609a 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -165,13 +165,18 @@ checked out in the submodule.\n \tmerge;; the commit recorded in the superproject will be merged\n \t into the current branch in the submodule.\n\n-\tcustom command;; arbitrary shell command that takes a single\n-\t argument (the sha1 of the commit recorded in the\n-\t superproject) is executed. When `submodule..update`\n-\t is set to '!command', the remainder after the exclamation mark\n-\t is the custom command.\n-\n-\tnone;; the submodule is not updated.\n+The following update procedures have additional limitations:\n+\n+\tcustom command;; mechanism for running arbitrary commands with the\n+\t commit ID as an argument. Specifically, if the\n+\t `submodule..update` configuration variable is set to\n+\t `!custom command`, the object name of the commit recorded in the\n+\t superproject for the submodule is appended to the `custom command`\n+\t string and executed. Note that this mechanism is not supported in\n+\t the `.gitmodules` file or on the command line.\n+\n+\tnone;; the submodule is not updated. This update procedure is not\n+\t allowed on the command line.\n\n If the submodule is not yet initialized, and you just want to use the\n setting as stored in `.gitmodules`, you can automatically initialize the\ndiff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt\nindex dcee09b500..d9bec8b187 100644\n--- a/Documentation/gitmodules.txt\n+++ b/Documentation/gitmodules.txt\n@@ -43,9 +43,9 @@ submodule..update::\n \tcommand in the superproject. This is only used by `git\n \tsubmodule init` to initialize the configuration variable of\n \tthe same name. Allowed values here are 'checkout', 'rebase',\n-\t'merge' or 'none'. See description of 'update' command in\n-\tlinkgit:git-submodule[1] for their meaning. For security\n-\treasons, the '!command' form is not accepted here.\n+\t'merge' or 'none', but not '!command' (for security reasons).\n+\tSee the description of the 'update' command in\n+\tlinkgit:git-submodule[1] for more details.\n\n submodule..branch::\n \tA remote branch name for tracking updates in the upstream submodule.\n-- \n2.41.0\n\n"},{"id":"479846","messageId":"xmqq8rb3n9du.fsf@gitster.g","threadId":"59976","inReplyTo":"0d29ac42-4e8f-71b6-b85f-00de182e2957@imap.cc","subject":"Re: [PATCH v3 1/1] docs: highlight that .gitmodules does not support !command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-07-25T18:17:33Z","receivedAt":"2023-07-25T18:17:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petar Vutov writes:\n\n> I applied your patch and then made some additions, which I'll append\n> at the end of this message. Summary:\n>\n> * Added your rewrite from yesterday. I like that it's more precise\n> than the current docs, but I struggle with the complexity of the\n> first sentence. I wanted to make it easier to follow by splitting it\n> in two somehow. Instead I ended up with an introductory sentence\n> summarizing the functionality with small words.\n>\n> * In gitmodules.txt, moved the security disclaimer so people are more\n> likely to see it before they follow the link to git-submodule.txt.\n>\n> * Explicitly called out `none` and `custom command` as being unusable\n> on the command line (and in .gitmodules). I expect that you won't\n> want that .gitmodules mention anymore, but I left it in for now, up\n> to you.\n>\n> The diff below is based on top of your patch from yesterday, since I\n> assume that you don't want to look at a mishmash of both patches.\n\nSorry for a very slow response; I seem to have missed this one.\n\nThe end result looks good. Care to wrap it up into a single patch\n(iow, make a \"mishmash of both patches\") with a good log message so\nwe can move the topic forward?\n\nThanks.\n\n> diff --git a/Documentation/git-submodule.txt\n> b/Documentation/git-submodule.txt\n> index 5248840b18..695730609a 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -165,13 +165,18 @@ checked out in the submodule.\n> \tmerge;; the commit recorded in the superproject will be merged\n> \t into the current branch in the submodule.\n>\n> -\tcustom command;; arbitrary shell command that takes a single\n> -\t argument (the sha1 of the commit recorded in the\n> -\t superproject) is executed. When `submodule..update`\n> -\t is set to '!command', the remainder after the exclamation mark\n> -\t is the custom command.\n> -\n> -\tnone;; the submodule is not updated.\n> +The following update procedures have additional limitations:\n> +\n> +\tcustom command;; mechanism for running arbitrary commands with the\n> +\t commit ID as an argument. Specifically, if the\n> +\t `submodule..update` configuration variable is set to\n> +\t `!custom command`, the object name of the commit recorded in the\n> +\t superproject for the submodule is appended to the `custom command`\n> +\t string and executed. Note that this mechanism is not supported in\n> +\t the `.gitmodules` file or on the command line.\n> +\n> +\tnone;; the submodule is not updated. This update procedure is not\n> +\t allowed on the command line.\n>\n> If the submodule is not yet initialized, and you just want to use the\n> setting as stored in `.gitmodules`, you can automatically initialize the\n> diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt\n> index dcee09b500..d9bec8b187 100644\n> --- a/Documentation/gitmodules.txt\n> +++ b/Documentation/gitmodules.txt\n> @@ -43,9 +43,9 @@ submodule..update::\n> \tcommand in the superproject. This is only used by `git\n> \tsubmodule init` to initialize the configuration variable of\n> \tthe same name. Allowed values here are 'checkout', 'rebase',\n> -\t'merge' or 'none'. See description of 'update' command in\n> -\tlinkgit:git-submodule[1] for their meaning. For security\n> -\treasons, the '!command' form is not accepted here.\n> +\t'merge' or 'none', but not '!command' (for security reasons).\n> +\tSee the description of the 'update' command in\n> +\tlinkgit:git-submodule[1] for more details.\n>\n> submodule..branch::\n> \tA remote branch name for tracking updates in the upstream submodule.\n"},{"id":"479862","messageId":"20230725212218.711116-1-pvutov@imap.cc","threadId":"59976","inReplyTo":"xmqq8rb3n9du.fsf@gitster.g","subject":"[PATCH v5] doc: highlight that .gitmodules does not support !command","fromName":"","fromEmail":"pvutov@imap.cc","sentAt":"2023-07-25T21:22:18Z","receivedAt":"2023-07-25T21:21:24Z","isPatch":true,"sender":{"key":"pvutov@imap.cc","avatar":"https://avatars.githubusercontent.com/u/11945431?v=4"},"body":"From: Petar Vutov \n\nBugfix for fc01a5d2 (submodule update documentation: don't repeat\nourselves, 2016-12-27).\n\nThe `custom command` and `none` options are described as sharing the\nsame limitations, but one is allowed in .gitmodules and the other is\nnot.\n\nRewrite the description for custom commands to be more precise,\nand make it easier for readers to notice that custom commands cannot\nbe used in the .gitmodules file.\n\nSigned-off-by: Petar Vutov \n---\nCombines the custom command description rewrite by Junio C Hamano and\nmy proposed changes into a single patch.\n\nApologies for the \"From:\" line at the top - I don't know if it is safe to\nremove it, and I can't figure out how set my name in git-send-email so\nthat the line is not automatically added.\n\n Documentation/git-submodule.txt | 31 +++++++++++++++++++------------\n Documentation/gitmodules.txt | 6 +++---\n 2 files changed, 22 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 4d3ab6b9f9..695730609a 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -95,7 +95,7 @@ too (and can also report changes to a submodule's work tree).\n init [--] [...]::\n \tInitialize the submodules recorded in the index (which were\n \tadded and committed elsewhere) by setting `submodule.$name.url`\n-\tin .git/config. It uses the same setting from `.gitmodules` as\n+\tin `.git/config`, using the same setting from `.gitmodules` as\n \ta template. If the URL is relative, it will be resolved using\n \tthe default remote. If there is no default remote, the current\n \trepository will be assumed to be upstream.\n@@ -105,9 +105,12 @@ If no path is specified and submodule.active has been configured, submodules\n configured to be active will be initialized, otherwise all submodules are\n initialized.\n +\n-When present, it will also copy the value of `submodule.$name.update`.\n-This command does not alter existing information in .git/config.\n-You can then customize the submodule clone URLs in .git/config\n+It will also copy the value of `submodule.$name.update`, if present in\n+the `.gitmodules` file, to `.git/config`, but (1) this command does not\n+alter existing information in `.git/config`, and (2) `submodule.$name.update`\n+that is set to a custom command is *not* copied for security reasons.\n++\n+You can then customize the submodule clone URLs in `.git/config`\n for your local setup and proceed to `git submodule update`;\n you can also just use `git submodule update --init` without\n the explicit 'init' step if you do not intend to customize\n@@ -143,6 +146,8 @@ the submodules. The \"updating\" can be done in several ways depending\n on command line options and the value of `submodule..update`\n configuration variable. The command line option takes precedence over\n the configuration variable. If neither is given, a 'checkout' is performed.\n+(note: what is in `.gitmodules` file is irrelevant at this point;\n+see `git submodule init` above for how `.gitmodules` is used).\n The 'update' procedures supported both from the command line as well as\n through the `submodule..update` configuration are:\n \n@@ -160,16 +165,18 @@ checked out in the submodule.\n \tmerge;; the commit recorded in the superproject will be merged\n \t into the current branch in the submodule.\n \n-The following 'update' procedures are only available via the\n-`submodule..update` configuration variable:\n+The following update procedures have additional limitations:\n \n-\tcustom command;; arbitrary shell command that takes a single\n-\t argument (the sha1 of the commit recorded in the\n-\t superproject) is executed. When `submodule..update`\n-\t is set to '!command', the remainder after the exclamation mark\n-\t is the custom command.\n+\tcustom command;; mechanism for running arbitrary commands with the\n+\t commit ID as an argument. Specifically, if the\n+\t `submodule..update` configuration variable is set to\n+\t `!custom command`, the object name of the commit recorded in the\n+\t superproject for the submodule is appended to the `custom command`\n+\t string and executed. Note that this mechanism is not supported in\n+\t the `.gitmodules` file or on the command line.\n \n-\tnone;; the submodule is not updated.\n+\tnone;; the submodule is not updated. This update procedure is not\n+\t allowed on the command line.\n \n If the submodule is not yet initialized, and you just want to use the\n setting as stored in `.gitmodules`, you can automatically initialize the\ndiff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt\nindex dcee09b500..d9bec8b187 100644\n--- a/Documentation/gitmodules.txt\n+++ b/Documentation/gitmodules.txt\n@@ -43,9 +43,9 @@ submodule..update::\n \tcommand in the superproject. This is only used by `git\n \tsubmodule init` to initialize the configuration variable of\n \tthe same name. Allowed values here are 'checkout', 'rebase',\n-\t'merge' or 'none'. See description of 'update' command in\n-\tlinkgit:git-submodule[1] for their meaning. For security\n-\treasons, the '!command' form is not accepted here.\n+\t'merge' or 'none', but not '!command' (for security reasons).\n+\tSee the description of the 'update' command in\n+\tlinkgit:git-submodule[1] for more details.\n \n submodule..branch::\n \tA remote branch name for tracking updates in the upstream submodule.\n-- \n2.41.0\n\n"},{"id":"479866","messageId":"xmqqv8e7hczm.fsf@gitster.g","threadId":"59976","inReplyTo":"20230725212218.711116-1-pvutov@imap.cc","subject":"Re: [PATCH v5] doc: highlight that .gitmodules does not support !command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-07-25T21:56:13Z","receivedAt":"2023-07-25T21:56:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"pvutov@imap.cc writes:\n\n> From: Petar Vutov \n>\n> Bugfix for fc01a5d2 (submodule update documentation: don't repeat\n> ourselves, 2016-12-27).\n>\n> The `custom command` and `none` options are described as sharing the\n> same limitations, but one is allowed in .gitmodules and the other is\n> not.\n>\n> Rewrite the description for custom commands to be more precise,\n> and make it easier for readers to notice that custom commands cannot\n> be used in the .gitmodules file.\n>\n> Signed-off-by: Petar Vutov \n> ---\n> Combines the custom command description rewrite by Junio C Hamano and\n> my proposed changes into a single patch.\n\nThanks. Willl queue. Let's move it forward.\n"}]}