{"thread":{"id":"46812","subject":"[PATCH] Documentation/config: clarify the meaning of submodule..update","startedAt":"2017-09-22T21:28:27Z","lastAt":"2017-09-26T01:31:08Z","messageCount":12,"participants":["Stefan Beller","Jonathan Nieder","Junio C Hamano","Brandon Williams"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"328689","messageId":"20170922212818.9958-1-sbeller@google.com","threadId":"46812","inReplyTo":null,"subject":"[PATCH] Documentation/config: clarify the meaning of submodule..update","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-09-22T21:28:18Z","receivedAt":"2017-09-22T21:28:27Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"With more commands (that potentially change a submodule) paying attention\nto submodules as well as the recent discussion[1] on submodule..update,\nlet's spell out that submodule..update is strictly to be used\nfor configuring the \"submodule update\" command and not to be obeyed\nby other commands.\n\nThese other commands usually have a strict meaning of what they should\ndo (i.e. checkout, reset, rebase, merge) as well as have their name\noverlapping with the modes possible for submodule..update.\n\n[1] https://public-inbox.org/git/4283F0B0-BC1C-4ED1-8126-7E512D84484B@gmail.com/\n\nSigned-off-by: Stefan Beller \n---\n Documentation/config.txt | 7 +++----\n 1 file changed, 3 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex dc4e3f58a2..b0ded777fe 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -3085,10 +3085,9 @@ submodule..url::\n \tSee linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n \n submodule..update::\n-\tThe default update procedure for a submodule. This variable\n-\tis populated by `git submodule init` from the\n-\tlinkgit:gitmodules[5] file. See description of 'update'\n-\tcommand in linkgit:git-submodule[1].\n+\tThe method how a submodule is updated via 'git submodule update'.\n+\tIt is populated by `git submodule init` from the linkgit:gitmodules[5]\n+\tfile. See description of 'update' command in linkgit:git-submodule[1].\n \n submodule..branch::\n \tThe remote branch name for a submodule, used by `git submodule\n-- \n2.14.0.rc0.3.g6c2e499285\n\n"},{"id":"328691","messageId":"20170922213740.GL27425@aiede.mtv.corp.google.com","threadId":"46812","inReplyTo":"20170922212818.9958-1-sbeller@google.com","subject":"Re: [PATCH] Documentation/config: clarify the meaning of submodule..update","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-09-22T21:37:40Z","receivedAt":"2017-09-22T21:37:48Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nStefan Beller wrote:\n\n> With more commands (that potentially change a submodule) paying attention\n> to submodules as well as the recent discussion[1] on submodule..update,\n> let's spell out that submodule..update is strictly to be used\n> for configuring the \"submodule update\" command and not to be obeyed\n> by other commands.\n\nGood idea, thank you.\n\nYou'll want to update Documentation/gitmodules.txt, too.\n\nI think this can go further: it should say explicitly that commands\nlike \"git checkout --recurse-submodules\" do not pay attention to this\noption.\n\n> These other commands usually have a strict meaning of what they should\n> do (i.e. checkout, reset, rebase, merge) as well as have their name\n> overlapping with the modes possible for submodule..update.\n>\n> [1] https://public-inbox.org/git/4283F0B0-BC1C-4ED1-8126-7E512D84484B@gmail.com/\n\nCan you summarize what this discussion concluded with so the reader\ndoes not have to look far to understand it?\n\n> Signed-off-by: Stefan Beller \n\nReported-by: Lars Schneider \n\n> ---\n> Documentation/config.txt | 7 +++----\n> 1 file changed, 3 insertions(+), 4 deletions(-)\n>\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index dc4e3f58a2..b0ded777fe 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -3085,10 +3085,9 @@ submodule..url::\n> \tSee linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n> \n> submodule..update::\n> -\tThe default update procedure for a submodule. This variable\n> -\tis populated by `git submodule init` from the\n> -\tlinkgit:gitmodules[5] file. See description of 'update'\n> -\tcommand in linkgit:git-submodule[1].\n> +\tThe method how a submodule is updated via 'git submodule update'.\n> +\tIt is populated by `git submodule init` from the linkgit:gitmodules[5]\n> +\tfile. See description of 'update' command in linkgit:git-submodule[1].\n> \n\nWording nits: s/The method how/The method by which/; s/via/by/\n\nMore importantly, can this be more explicit about how it is meant to\nbe used? E.g. to say\n\n 1. This only affects \"git submodule update\" and doesn't affect\n commands like \"git checkout --recurse-submodules\".\n\n 2. It exists for historical reasons; settings like submodule.active\n and pull.rebase are more likely to be what someone is looking for.\n\nThanks and hope that helps,\nJonathan\n"},{"id":"328696","messageId":"20170922225250.19705-1-sbeller@google.com","threadId":"46812","inReplyTo":"20170922213740.GL27425@aiede.mtv.corp.google.com","subject":"[PATCHv2] Documentation/config: clarify the meaning of submodule..update","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-09-22T22:52:50Z","receivedAt":"2017-09-22T22:53:01Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"With more commands (that potentially change a submodule) paying attention\nto submodules as well as the recent discussion[1] on\nsubmodule..update, let's spell out that submodule..update\nis strictly to be used for configuring the \"submodule update\" command\nand not to be obeyed by other commands.\n\nThese other commands usually have a strict meaning of what they should\ndo (i.e. checkout, reset, rebase, merge) as well as have their name\noverlapping with the modes possible for submodule..update.\n\n[1] https://public-inbox.org/git/4283F0B0-BC1C-4ED1-8126-7E512D84484B@gmail.com/\n submodule..update was set to \"none\", triggering unexpected\n behavior as the submodule was thought to never be touched.\n However a newer version of Git taught 'git pull --rebase' to also\n populate and rebase submodules if they were active.\n The newer options such as submodule.active and command specific\n flags would not have triggered unexpected behavior.\n\nReported-by: Lars Schneider \nSigned-off-by: Stefan Beller \n---\n Documentation/config.txt | 12 ++++++++----\n 1 file changed, 8 insertions(+), 4 deletions(-)\n\nJonathan writes:\n> You'll want to update Documentation/gitmodules.txt, too.\n\nNo. /grumpycat\n\nIt should already be fine, as I read it as if it is only relevant to \n\"git submodule update\" there, already:\n\n submodule..update::\n\tDefines the default update procedure for the named submodule,\n\ti.e. how the submodule is updated by \"git 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. Note that the\n\t'!command' form is intentionally ignored here for security\n\treasons.\n \n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex dc4e3f58a2..1ac0ae6adb 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -3085,10 +3085,14 @@ submodule..url::\n \tSee linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n \n submodule..update::\n-\tThe default update procedure for a submodule. This variable\n-\tis populated by `git submodule init` from the\n-\tlinkgit:gitmodules[5] file. See description of 'update'\n-\tcommand in linkgit:git-submodule[1].\n+\tThe method by which a submodule is updated by 'git submodule update',\n+\twhich is the only affected command, others such as\n+\t'git checkout --recurse-submodules' are unaffected. It exists for\n+\thistorical reasons, when 'git submodule' was the only command to\n+\tinteract with submodules; settings like `submodule.active`\n+\tand `pull.rebase` are more specific. It is populated by\n+\t`git submodule init` from the linkgit:gitmodules[5] file.\n+\tSee description of 'update' command in linkgit:git-submodule[1].\n \n submodule..branch::\n \tThe remote branch name for a submodule, used by `git submodule\n-- \n2.14.0.rc0.3.g6c2e499285\n\n"},{"id":"328698","messageId":"20170922225855.GM27425@aiede.mtv.corp.google.com","threadId":"46812","inReplyTo":"20170922225250.19705-1-sbeller@google.com","subject":"Re: [PATCHv2] Documentation/config: clarify the meaning of submodule..update","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-09-22T22:58:55Z","receivedAt":"2017-09-22T22:59:03Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Stefan Beller wrote:\n\n> Reported-by: Lars Schneider \n> Signed-off-by: Stefan Beller \n> ---\n> Documentation/config.txt | 12 ++++++++----\n> 1 file changed, 8 insertions(+), 4 deletions(-)\n>\n> Jonathan writes:\n\n>> You'll want to update Documentation/gitmodules.txt, too.\n>\n> No. /grumpycat\n>\n> It should already be fine, as I read it as if it is only relevant to \n> \"git submodule update\" there, already:\n>\n> submodule..update::\n> \tDefines the default update procedure for the named submodule,\n> \ti.e. how the submodule is updated by \"git 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. Note that the\n> \t'!command' form is intentionally ignored here for security\n> \treasons.\n\nI disagree. Actually, I think the git-config(1) blurb could just\npoint here, and that the text here ought to be clear about what\ncommands it affects and how an end user would use it.\n"},{"id":"328751","messageId":"xmqq1smxj7md.fsf@gitster.mtv.corp.google.com","threadId":"46812","inReplyTo":"20170922225855.GM27425@aiede.mtv.corp.google.com","subject":"Re: [PATCHv2] Documentation/config: clarify the meaning of submodule..update","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-09-23T23:52:10Z","receivedAt":"2017-09-23T23:52:17Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Stefan Beller wrote:\n>\n>> Reported-by: Lars Schneider \n>> Signed-off-by: Stefan Beller \n>> ---\n>> Documentation/config.txt | 12 ++++++++----\n>> 1 file changed, 8 insertions(+), 4 deletions(-)\n>>\n>> Jonathan writes:\n>\n>>> You'll want to update Documentation/gitmodules.txt, too.\n>>\n>> No. /grumpycat\n>>\n>> It should already be fine, as I read it as if it is only relevant to \n>> \"git submodule update\" there, already:\n>>\n>> submodule..update::\n>> \tDefines the default update procedure for the named submodule,\n>> \ti.e. how the submodule is updated by \"git 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. Note that the\n>> \t'!command' form is intentionally ignored here for security\n>> \treasons.\n>\n> I disagree. Actually, I think the git-config(1) blurb could just\n> point here, and that the text here ought to be clear about what\n> commands it affects and how an end user would use it.\n\nI tend to agree with the consolidation. It's not like this patch\nmakes things worse, but as we've already diverted our attention to\nthis area and took time to review, if it is a simple update we can\nmake before we apply, that is better than having to remember and\ncome back to patch the result of this step further.\n\nIn any case, thanks for reporting, attempting to improve and\nreviewing, all.\n"},{"id":"328866","messageId":"20170925191011.29863-1-sbeller@google.com","threadId":"46812","inReplyTo":"xmqq1smxj7md.fsf@gitster.mtv.corp.google.com","subject":"[PATCH] Documentation: consolidate submodule..update","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-09-25T19:10:11Z","receivedAt":"2017-09-25T19:10:19Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"Have one place to explain the effects of setting submodule..update\ninstead of two.\n\nSigned-off-by: Stefan Beller \n---\n>> I disagree. Actually, I think the git-config(1) blurb could just\n>> point here, and that the text here ought to be clear about what\n>> commands it affects and how an end user would use it.\n>\n> I tend to agree with the consolidation.\n\nSomething like this?\n\n Documentation/config.txt | 9 +--------\n Documentation/gitmodules.txt | 20 +++++++++++---------\n 2 files changed, 12 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 1ac0ae6adb..0d5a296b6c 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -3085,14 +3085,7 @@ submodule..url::\n \tSee linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n \n submodule..update::\n-\tThe method by which a submodule is updated by 'git submodule update',\n-\twhich is the only affected command, others such as\n-\t'git checkout --recurse-submodules' are unaffected. It exists for\n-\thistorical reasons, when 'git submodule' was the only command to\n-\tinteract with submodules; settings like `submodule.active`\n-\tand `pull.rebase` are more specific. It is populated by\n-\t`git submodule init` from the linkgit:gitmodules[5] file.\n-\tSee description of 'update' command in linkgit:git-submodule[1].\n+\tSee `submodule..update` in linkgit:gitmodules[5].\n \n submodule..branch::\n \tThe remote branch name for a submodule, used by `git submodule\ndiff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt\nindex db5d47eb19..d156dee387 100644\n--- a/Documentation/gitmodules.txt\n+++ b/Documentation/gitmodules.txt\n@@ -38,15 +38,17 @@ submodule..url::\n In addition, there are a number of optional keys:\n \n submodule..update::\n-\tDefines the default update procedure for the named submodule,\n-\ti.e. how the submodule is updated by \"git 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. Note that the\n-\t'!command' form is intentionally ignored here for security\n-\treasons.\n+\tThe method by which a submodule is updated by 'git submodule update',\n+\twhich is the only affected command, others such as\n+\t'git checkout --recurse-submodules' are unaffected. It exists for\n+\thistorical reasons, when 'git submodule' was the only command to\n+\tinteract with submodules; settings like `submodule.active`\n+\tand `pull.rebase` are more specific. It is copied to the config\n+\tby `git submodule init` from the .gitmodules file.\n+\tAllowed values here are 'checkout', 'rebase', 'merge' or 'none'.\n+\tSee description of 'update' command in linkgit:git-submodule[1]\n+\tfor their meaning. Note that the '!command' form is intentionally\n+\tignored here for security reasons.\n \n submodule..branch::\n \tA remote branch name for tracking updates in the upstream submodule.\n-- \n2.14.0.rc0.3.g6c2e499285\n\n"},{"id":"328868","messageId":"20170925191726.GE35385@google.com","threadId":"46812","inReplyTo":"20170925191011.29863-1-sbeller@google.com","subject":"Re: [PATCH] Documentation: consolidate submodule..update","fromName":"Brandon Williams","fromEmail":"bmwill@google.com","sentAt":"2017-09-25T19:17:26Z","receivedAt":"2017-09-25T19:17:33Z","isPatch":true,"sender":{"key":"bwilliams.eng@gmail.com","avatar":null},"body":"On 09/25, Stefan Beller wrote:\n> Have one place to explain the effects of setting submodule..update\n> instead of two.\n> \n> Signed-off-by: Stefan Beller \n> ---\n> >> I disagree. Actually, I think the git-config(1) blurb could just\n> >> point here, and that the text here ought to be clear about what\n> >> commands it affects and how an end user would use it.\n> >\n> > I tend to agree with the consolidation.\n> \n> Something like this?\n\nI like the consolidation, its easier to keep up to date when its only in\none place.\n\n> \n> Documentation/config.txt | 9 +--------\n> Documentation/gitmodules.txt | 20 +++++++++++---------\n> 2 files changed, 12 insertions(+), 17 deletions(-)\n> \n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index 1ac0ae6adb..0d5a296b6c 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -3085,14 +3085,7 @@ submodule..url::\n> \tSee linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n> \n> submodule..update::\n> -\tThe method by which a submodule is updated by 'git submodule update',\n> -\twhich is the only affected command, others such as\n> -\t'git checkout --recurse-submodules' are unaffected. It exists for\n> -\thistorical reasons, when 'git submodule' was the only command to\n> -\tinteract with submodules; settings like `submodule.active`\n> -\tand `pull.rebase` are more specific. It is populated by\n> -\t`git submodule init` from the linkgit:gitmodules[5] file.\n> -\tSee description of 'update' command in linkgit:git-submodule[1].\n> +\tSee `submodule..update` in linkgit:gitmodules[5].\n> \n> submodule..branch::\n> \tThe remote branch name for a submodule, used by `git submodule\n> diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt\n> index db5d47eb19..d156dee387 100644\n> --- a/Documentation/gitmodules.txt\n> +++ b/Documentation/gitmodules.txt\n> @@ -38,15 +38,17 @@ submodule..url::\n> In addition, there are a number of optional keys:\n> \n> submodule..update::\n> -\tDefines the default update procedure for the named submodule,\n> -\ti.e. how the submodule is updated by \"git 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. Note that the\n> -\t'!command' form is intentionally ignored here for security\n> -\treasons.\n> +\tThe method by which a submodule is updated by 'git submodule update',\n> +\twhich is the only affected command, others such as\n> +\t'git checkout --recurse-submodules' are unaffected. It exists for\n> +\thistorical reasons, when 'git submodule' was the only command to\n> +\tinteract with submodules; settings like `submodule.active`\n> +\tand `pull.rebase` are more specific. It is copied to the config\n> +\tby `git submodule init` from the .gitmodules file.\n> +\tAllowed values here are 'checkout', 'rebase', 'merge' or 'none'.\n> +\tSee description of 'update' command in linkgit:git-submodule[1]\n> +\tfor their meaning. Note that the '!command' form is intentionally\n> +\tignored here for security reasons.\n\nThis probably needs to be tweaked a bit to say that the '!command' form\nis ignored by submodule init, in that it isn't copied over from the\n.gitmodules file, but if it is configured in your config it will be\nrespected by 'submodule update'.\n\n> \n> submodule..branch::\n> \tA remote branch name for tracking updates in the upstream submodule.\n> -- \n> 2.14.0.rc0.3.g6c2e499285\n> \n\n-- \nBrandon Williams\n"},{"id":"328889","messageId":"CAGZ79kZZJe=EYh7wecAWneVKrWoBLrPoWuMWmC219vzWVzP6mA@mail.gmail.com","threadId":"46812","inReplyTo":"20170925191726.GE35385@google.com","subject":"Re: [PATCH] Documentation: consolidate submodule..update","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-09-25T22:18:11Z","receivedAt":"2017-09-25T22:18:18Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Mon, Sep 25, 2017 at 12:17 PM, Brandon Williams wrote:\n> On 09/25, Stefan Beller wrote:\n>> Have one place to explain the effects of setting submodule..update\n>> instead of two.\n>>\n>> Signed-off-by: Stefan Beller \n>> ---\n>> >> I disagree. Actually, I think the git-config(1) blurb could just\n>> >> point here, and that the text here ought to be clear about what\n>> >> commands it affects and how an end user would use it.\n>> >\n>> > I tend to agree with the consolidation.\n>>\n>> Something like this?\n>\n> I like the consolidation, its easier to keep up to date when its only in\n> one place.\n\nAfter thinking about it further, I'd like to withdraw this patch\nfor now.\n\nThe reason is that this would also forward point to\ngit-submodule.txt, such that we'd still have 2 places\nin which it is explained. The current situation with explaining\nit in 3 places is not too bad as each place hints at their specific\ncircumstance:\ngit-submodule.txt explains the values to set itself.\ngitmodules.txt explains what the possible fields in that file are,\n and regarding this field it points out it is ignored in the init call.\nconfig.txt: actually describe the effects of the setting.\n\nI think we can keep it as-is for now.\n\nThanks,\nStefan\n"},{"id":"328890","messageId":"20170925222229.GG27425@aiede.mtv.corp.google.com","threadId":"46812","inReplyTo":"CAGZ79kZZJe=EYh7wecAWneVKrWoBLrPoWuMWmC219vzWVzP6mA@mail.gmail.com","subject":"Re: [PATCH] Documentation: consolidate submodule..update","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-09-25T22:22:29Z","receivedAt":"2017-09-25T22:22:38Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Stefan Beller wrote:\n> On Mon, Sep 25, 2017 at 12:17 PM, Brandon Williams wrote:\n>> On 09/25, Stefan Beller wrote:\n\n>>> Have one place to explain the effects of setting submodule..update\n>>> instead of two.\n>>>\n>>> Signed-off-by: Stefan Beller \n>>> ---\n>>>>> I disagree. Actually, I think the git-config(1) blurb could just\n>>>>> point here, and that the text here ought to be clear about what\n>>>>> commands it affects and how an end user would use it.\n>>>>\n>>>> I tend to agree with the consolidation.\n>>>\n>>> Something like this?\n>>\n>> I like the consolidation, its easier to keep up to date when its only in\n>> one place.\n>\n> After thinking about it further, I'd like to withdraw this patch\n> for now.\n>\n> The reason is that this would also forward point to\n> git-submodule.txt, such that we'd still have 2 places\n> in which it is explained. The current situation with explaining\n> it in 3 places is not too bad as each place hints at their specific\n> circumstance:\n> git-submodule.txt explains the values to set itself.\n> gitmodules.txt explains what the possible fields in that file are,\n> and regarding this field it points out it is ignored in the init call.\n> config.txt: actually describe the effects of the setting.\n>\n> I think we can keep it as-is for now.\n\nSorry, I got lost. Which state is as-is?\n\nAs a user, how do I find out what submodule.*.update is going to do\nand which commands will respect it?\n\nMaybe we should work on first wordsmithing the doc and then figuring\nout where it goes? The current state of the doc with (?) three\ndifferent texts, all wrong, doesn't seem like a good state to\npreserve.\n\nThanks,\nJonathan\n"},{"id":"328892","messageId":"CAGZ79kY4tAfYERj1V2AL+piqWe6nw0qA+AHqm5w6ch9WiL86pw@mail.gmail.com","threadId":"46812","inReplyTo":"20170925222229.GG27425@aiede.mtv.corp.google.com","subject":"Re: [PATCH] Documentation: consolidate submodule..update","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2017-09-25T22:42:15Z","receivedAt":"2017-09-25T22:42:24Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Mon, Sep 25, 2017 at 3:22 PM, Jonathan Nieder wrote:\n> Stefan Beller wrote:\n>> On Mon, Sep 25, 2017 at 12:17 PM, Brandon Williams wrote:\n>>> On 09/25, Stefan Beller wrote:\n>\n>>>> Have one place to explain the effects of setting submodule..update\n>>>> instead of two.\n>>>>\n>>>> Signed-off-by: Stefan Beller \n>>>> ---\n>>>>>> I disagree. Actually, I think the git-config(1) blurb could just\n>>>>>> point here, and that the text here ought to be clear about what\n>>>>>> commands it affects and how an end user would use it.\n>>>>>\n>>>>> I tend to agree with the consolidation.\n>>>>\n>>>> Something like this?\n>>>\n>>> I like the consolidation, its easier to keep up to date when its only in\n>>> one place.\n>>\n>> After thinking about it further, I'd like to withdraw this patch\n>> for now.\n>>\n>> The reason is that this would also forward point to\n>> git-submodule.txt, such that we'd still have 2 places\n>> in which it is explained. The current situation with explaining\n>> it in 3 places is not too bad as each place hints at their specific\n>> circumstance:\n>> git-submodule.txt explains the values to set itself.\n>> gitmodules.txt explains what the possible fields in that file are,\n>> and regarding this field it points out it is ignored in the init call.\n>> config.txt: actually describe the effects of the setting.\n>>\n>> I think we can keep it as-is for now.\n>\n> Sorry, I got lost. Which state is as-is?\n\nBy as-is I refer to origin/pu.\n\n> As a user, how do I find out what submodule.*.update is going to do\n> and which commands will respect it?\n\nThe user would discover it via 'man git-config' I would assume, which\ncovers any config variable? It also directs to git-submodule which is\nmore detailed, but the text there is suitable for the casual reader.\n(pu has origin/sb/doc-config-submodule-update)\n\n> Maybe we should work on first wordsmithing the doc and then figuring\n> out where it goes? The current state of the doc with (?) three\n> different texts,\n\nsuch that each different text highlights each locations purpose.\n\n> all wrong,\n\nCare to spell out this bold claim?\n\nThanks,\nStefan\n"},{"id":"328901","messageId":"20170925234428.GJ27425@aiede.mtv.corp.google.com","threadId":"46812","inReplyTo":"CAGZ79kY4tAfYERj1V2AL+piqWe6nw0qA+AHqm5w6ch9WiL86pw@mail.gmail.com","subject":"Re: [PATCH] Documentation: consolidate submodule..update","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-09-25T23:44:28Z","receivedAt":"2017-09-25T23:44:35Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Stefan Beller wrote:\n\n> By as-is I refer to origin/pu.\n\nAh, okay. I'm not in that habit because pu frequently loses topics\n--- it's mostly useful as a tool to (1) distribute topic branches and\n(2) check whether they are compatible with each other.\n\n[...]\n> On Mon, Sep 25, 2017 at 3:22 PM, Jonathan Nieder wrote:\n\n>> Maybe we should work on first wordsmithing the doc and then figuring\n>> out where it goes? The current state of the doc with (?) three\n>> different texts,\n>\n> such that each different text highlights each locations purpose.\n>\n>> all wrong,\n>\n> Care to spell out this bold claim?\n\nIn the state of \"master\", \"man git-config\" tells me that\n\n\t[submodule \"\"]\n\t\tupdate = ...\n\nsets the \"default update procedure for a submodule\". It suggests that\nI read about \"git submodule update\" in git-submodule(1) for more\ndetails. This is problematic because\n\n 1. It doesn't tell me when I should and should not set it.\n 2. I would expect \"git checkout --recurse-submodules\" to respect the\n default update procedure.\n 3. It doesn't tell me what commands like \"git fetch\n --recurse-submodules\" will do.\n 4. It doesn't point me to better alternatives, when this\n configuration doesn't fit my use case.\n\n\"man git-submodule\" doesn't have a section on submodule..update.\nIt has references scattered throughout the manpage. It only tells me\nhow the setting affects the \"git submodule update\" command and doesn't\naddress the problems (1)-(4).\n\n\"man gitmodules\" also refers to this setting as the \"default update\nprocedure for the named submodule\". It doesn't answer the questions\n(1)-(4) either.\n\nThanks and hope that helps,\nJonathan\n"},{"id":"328918","messageId":"xmqqy3p2ckks.fsf@gitster.mtv.corp.google.com","threadId":"46812","inReplyTo":"20170925191726.GE35385@google.com","subject":"Re: [PATCH] Documentation: consolidate submodule..update","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-09-26T01:30:59Z","receivedAt":"2017-09-26T01:31:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Brandon Williams writes:\n\n>> +\tThe method by which a submodule is updated by 'git submodule update',\n>> +\twhich is the only affected command, others such as\n>> +\t'git checkout --recurse-submodules' are unaffected. It exists for\n>> +\thistorical reasons, when 'git submodule' was the only command to\n>> +\tinteract with submodules; settings like `submodule.active`\n>> +\tand `pull.rebase` are more specific. It is copied to the config\n>> +\tby `git submodule init` from the .gitmodules file.\n>> +\tAllowed values here are 'checkout', 'rebase', 'merge' or 'none'.\n>> +\tSee description of 'update' command in linkgit:git-submodule[1]\n>> +\tfor their meaning. Note that the '!command' form is intentionally\n>> +\tignored here for security reasons.\n>\n> This probably needs to be tweaked a bit to say that the '!command' form\n> is ignored by submodule init, in that it isn't copied over from the\n> .gitmodules file, but if it is configured in your config it will be\n> respected by 'submodule update'.\n\nI do not think gitmodules.txt is the place to say anything more than\nwhat Stefan's patch says above. Perhaps config.txt should mention\nthat in addition to what the variable with the same in .gitmodules\ncan take, it is allowed to use the !command form.\n\nIOW, in config.txt\n\n\tsubmodule..update::\n\t\tSpecifies how 'git submodule update' should work on\n\t\tthe named submodule. In addition to the values that\n\t\tcan be specified in (and copied from) `.gitmodules`\n\t\t(see linkgit:gitmodules[5]), `!command` form can\n\t\talso be used.\n\nor something, perhaps?\n"}]}