{"thread":{"id":"37868","subject":"[PATCH] submodule: Fix documentation of update subcommand","startedAt":"2014-11-03T10:09:51Z","lastAt":"2015-03-02T23:05:34Z","messageCount":25,"participants":["Michal Sojka","Junio C Hamano","Jens Lehmann"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"251297","messageId":"1415009391-14979-1-git-send-email-sojkam1@fel.cvut.cz","threadId":"37868","inReplyTo":null,"subject":"[PATCH] submodule: Fix documentation of update subcommand","fromName":"Michal Sojka","fromEmail":"sojkam1@fel.cvut.cz","sentAt":"2014-11-03T10:09:51Z","receivedAt":"2014-11-03T10:09:51Z","isPatch":true,"sender":{"key":"sojkam1@fel.cvut.cz","avatar":"https://avatars.githubusercontent.com/u/140542?v=4"},"body":"The documentation says that submodule.$name.update can be overridden by\n--checkout only if its value is `none`. This is not true, because both\nimplementation and documentation of --checkout specifies that the\noverride applies to all possible values.\n\nSigned-off-by: Michal Sojka \n---\n Documentation/git-submodule.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 8e6af65..84ab577 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -158,7 +158,7 @@ update::\n \tcheckout the commit specified in the index of the containing repository.\n \tThis will make the submodules HEAD be detached unless `--rebase` or\n \t`--merge` is specified or the key `submodule.$name.update` is set to\n-\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n+\t`rebase`, `merge` or `none`. This can be overridden by specifying\n \t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n \twill cause `command` to be run. `command` can be any arbitrary shell\n \tcommand that takes a single argument, namely the sha1 to update to.\n-- \n2.1.1\n"},{"id":"251335","messageId":"xmqqegtkrtt9.fsf@gitster.dls.corp.google.com","threadId":"37868","inReplyTo":"1415009391-14979-1-git-send-email-sojkam1@fel.cvut.cz","subject":"Re: [PATCH] submodule: Fix documentation of update subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-11-03T19:02:42Z","receivedAt":"2014-11-03T19:02:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michal Sojka writes:\n\n> The documentation says that submodule.$name.update can be overridden by\n> --checkout only if its value is `none`. This is not true, because both\n> implementation and documentation of --checkout specifies that the\n> override applies to all possible values.\n>\n> Signed-off-by: Michal Sojka \n> ---\n> Documentation/git-submodule.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 8e6af65..84ab577 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -158,7 +158,7 @@ update::\n> \tcheckout the commit specified in the index of the containing repository.\n> \tThis will make the submodules HEAD be detached unless `--rebase` or\n> \t`--merge` is specified or the key `submodule.$name.update` is set to\n> -\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n> +\t`rebase`, `merge` or `none`. This can be overridden by specifying\n> \t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n> \twill cause `command` to be run. `command` can be any arbitrary shell\n> \tcommand that takes a single argument, namely the sha1 to update to.\n\nThanks. This looks sensible, judging only from the text (iow I\ndidn't check if there were legitimate reason why rebase/merge\nsettings should not be overriden from the command line).\n\nJens?\n"},{"id":"251356","messageId":"5457E7DF.5070500@web.de","threadId":"37868","inReplyTo":"xmqqegtkrtt9.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] submodule: Fix documentation of update subcommand","fromName":"Jens Lehmann","fromEmail":"jens.lehmann@web.de","sentAt":"2014-11-03T20:38:55Z","receivedAt":"2014-11-03T20:38:55Z","isPatch":true,"sender":{"key":"jens.lehmann@web.de","avatar":"https://avatars.githubusercontent.com/u/135220?v=4"},"body":"Am 03.11.2014 um 20:02 schrieb Junio C Hamano:\n> Michal Sojka writes:\n>\n>> The documentation says that submodule.$name.update can be overridden by\n>> --checkout only if its value is `none`. This is not true, because both\n>> implementation and documentation of --checkout specifies that the\n>> override applies to all possible values.\n>>\n>> Signed-off-by: Michal Sojka \n>> ---\n>> Documentation/git-submodule.txt | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n>> index 8e6af65..84ab577 100644\n>> --- a/Documentation/git-submodule.txt\n>> +++ b/Documentation/git-submodule.txt\n>> @@ -158,7 +158,7 @@ update::\n>> \tcheckout the commit specified in the index of the containing repository.\n>> \tThis will make the submodules HEAD be detached unless `--rebase` or\n>> \t`--merge` is specified or the key `submodule.$name.update` is set to\n>> -\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n>> +\t`rebase`, `merge` or `none`. This can be overridden by specifying\n>> \t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n>> \twill cause `command` to be run. `command` can be any arbitrary shell\n>> \tcommand that takes a single argument, namely the sha1 to update to.\n>\n> Thanks. This looks sensible, judging only from the text (iow I\n> didn't check if there were legitimate reason why rebase/merge\n> settings should not be overriden from the command line).\n\nThis was introduced in e6a1c43aaf (document submdule.$name.update=none\noption for gitmodules), and I agree with Michal that we should fix it.\nBut I think we should rather say \"This can be overridden by specifying\n'--merge', '--rebase' or `--checkout`.\" here, as the other two options\nalso override the update setting. So I think we should queue this:\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 8e6af65..84ab577 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -158,7 +158,7 @@ update::\n \tcheckout the commit specified in the index of the containing repository.\n \tThis will make the submodules HEAD be detached unless `--rebase` or\n \t`--merge` is specified or the key `submodule.$name.update` is set to\n-\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n+\t`rebase`, `merge` or `none`. This can be overridden by using '--merge',\n+\t'--rebase' or\n \t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n \twill cause `command` to be run. `command` can be any arbitrary shell\n \tcommand that takes a single argument, namely the sha1 to update to.\n\nApart from that I'm all for it.\n"},{"id":"251357","messageId":"xmqqsii0qa4l.fsf@gitster.dls.corp.google.com","threadId":"37868","inReplyTo":"xmqqegtkrtt9.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] submodule: Fix documentation of update subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-11-03T20:53:14Z","receivedAt":"2014-11-03T20:53:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"I did a bit more digging of the history, and came up with this,\nwhich would be with a clearer and fairer description. Also to\nclarify, I spelled what Michal's \"This\" meant to refer to.\n\n-- >8 --\nFrom: Michal Sojka \nDate: Mon, 3 Nov 2014 11:09:51 +0100\nSubject: [PATCH] submodule: clarify documentation for update subcommand\n\ne6a1c43a (document submdule.$name.update=none option for gitmodules,\n2012-05-10) meant to say \"Unlike the case where your .update\nconfiguration is set to either 'rebase' or 'merge', when it is set\nto 'none', the tip of the submodule would never move. You can use\nthe --checkout option if you want the contents of the submodule to\nbe updated to some other commit.\"\n\nBut the resulting text made it sound as if using \"--checkout\" would\nhave no effect when .update configuration is set to 'rebase' or\n'merge', which was misleading. In fact, with the \"--checkout\"\noption, the tip of the submodule moves to the exact commit that is\nrecorded in the superproject tree, regardless of .update\nconfiguration.\n\nSigned-off-by: Michal Sojka \nSigned-off-by: Junio C Hamano \n---\n Documentation/git-submodule.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 8e6af65..648323f 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -158,7 +158,7 @@ update::\n \tcheckout the commit specified in the index of the containing repository.\n \tThis will make the submodules HEAD be detached unless `--rebase` or\n \t`--merge` is specified or the key `submodule.$name.update` is set to\n-\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n+\t`rebase`, `merge` or `none`. The configuration can be overridden by specifying\n \t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n \twill cause `command` to be run. `command` can be any arbitrary shell\n \tcommand that takes a single argument, namely the sha1 to update to.\n-- \n2.2.0-rc0-43-g5b91d12\n"},{"id":"251360","messageId":"5457EC81.2060504@web.de","threadId":"37868","inReplyTo":"xmqqsii0qa4l.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] submodule: Fix documentation of update subcommand","fromName":"Jens Lehmann","fromEmail":"jens.lehmann@web.de","sentAt":"2014-11-03T20:58:41Z","receivedAt":"2014-11-03T20:58:41Z","isPatch":true,"sender":{"key":"jens.lehmann@web.de","avatar":"https://avatars.githubusercontent.com/u/135220?v=4"},"body":"Am 03.11.2014 um 21:53 schrieb Junio C Hamano:\n> I did a bit more digging of the history, and came up with this,\n> which would be with a clearer and fairer description. Also to\n> clarify, I spelled what Michal's \"This\" meant to refer to.\n>\n> -- >8 --\n> From: Michal Sojka \n> Date: Mon, 3 Nov 2014 11:09:51 +0100\n> Subject: [PATCH] submodule: clarify documentation for update subcommand\n>\n> e6a1c43a (document submdule.$name.update=none option for gitmodules,\n> 2012-05-10) meant to say \"Unlike the case where your .update\n> configuration is set to either 'rebase' or 'merge', when it is set\n> to 'none', the tip of the submodule would never move. You can use\n> the --checkout option if you want the contents of the submodule to\n> be updated to some other commit.\"\n>\n> But the resulting text made it sound as if using \"--checkout\" would\n> have no effect when .update configuration is set to 'rebase' or\n> 'merge', which was misleading. In fact, with the \"--checkout\"\n> option, the tip of the submodule moves to the exact commit that is\n> recorded in the superproject tree, regardless of .update\n> configuration.\n>\n> Signed-off-by: Michal Sojka \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git-submodule.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 8e6af65..648323f 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -158,7 +158,7 @@ update::\n> \tcheckout the commit specified in the index of the containing repository.\n> \tThis will make the submodules HEAD be detached unless `--rebase` or\n> \t`--merge` is specified or the key `submodule.$name.update` is set to\n> -\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n> +\t`rebase`, `merge` or `none`. The configuration can be overridden by specifying\n> \t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n> \twill cause `command` to be run. `command` can be any arbitrary shell\n> \tcommand that takes a single argument, namely the sha1 to update to.\n\nYup, but we should also mention '--merge' and '--rebase' here.\n"},{"id":"251362","messageId":"87wq7c9ea9.fsf@steelpick.2x.cz","threadId":"37868","inReplyTo":"xmqqsii0qa4l.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] submodule: Fix documentation of update subcommand","fromName":"Michal Sojka","fromEmail":"sojkam1@fel.cvut.cz","sentAt":"2014-11-03T21:15:26Z","receivedAt":"2014-11-03T21:15:26Z","isPatch":true,"sender":{"key":"sojkam1@fel.cvut.cz","avatar":"https://avatars.githubusercontent.com/u/140542?v=4"},"body":"On Mon, Nov 03 2014, Junio C Hamano wrote:\n> I did a bit more digging of the history, and came up with this,\n> which would be with a clearer and fairer description. Also to\n> clarify, I spelled what Michal's \"This\" meant to refer to.\n>\n> -- >8 --\n> From: Michal Sojka \n> Date: Mon, 3 Nov 2014 11:09:51 +0100\n> Subject: [PATCH] submodule: clarify documentation for update subcommand\n>\n> e6a1c43a (document submdule.$name.update=none option for gitmodules,\n> 2012-05-10) meant to say \"Unlike the case where your .update\n> configuration is set to either 'rebase' or 'merge', when it is set\n> to 'none', the tip of the submodule would never move. You can use\n> the --checkout option if you want the contents of the submodule to\n> be updated to some other commit.\"\n>\n> But the resulting text made it sound as if using \"--checkout\" would\n> have no effect when .update configuration is set to 'rebase' or\n> 'merge', which was misleading. In fact, with the \"--checkout\"\n> option, the tip of the submodule moves to the exact commit that is\n> recorded in the superproject tree, regardless of .update\n> configuration.\n\nThis is much better description than I was able to put together. Thanks.\nI also agree with Jens that mentioning --merge and --rebase is\nworthwhile.\n\n-Michal\n"},{"id":"251363","messageId":"xmqqbnooq863.fsf@gitster.dls.corp.google.com","threadId":"37868","inReplyTo":"5457E7DF.5070500@web.de","subject":"Re: [PATCH] submodule: Fix documentation of update subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-11-03T21:35:32Z","receivedAt":"2014-11-03T21:35:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jens Lehmann writes:\n\n> This was introduced in e6a1c43aaf (document submdule.$name.update=none\n> option for gitmodules), and I agree with Michal that we should fix it.\n> But I think we should rather say \"This can be overridden by specifying\n> '--merge', '--rebase' or `--checkout`.\" here, as the other two options\n> also override the update setting. So I think we should queue this:\n>\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 8e6af65..84ab577 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -158,7 +158,7 @@ update::\n> \tcheckout the commit specified in the index of the containing repository.\n> \tThis will make the submodules HEAD be detached unless `--rebase` or\n> \t`--merge` is specified or the key `submodule.$name.update` is set to\n> -\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n> +\t`rebase`, `merge` or `none`. This can be overridden by using '--merge',\n> +\t'--rebase' or\n> \t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n> \twill cause `command` to be run. `command` can be any arbitrary shell\n> \tcommand that takes a single argument, namely the sha1 to update to.\n>\n> Apart from that I'm all for it.\n\nBut read the whole thing again. Isn't that a bit roundabout and\ntortuous?\n\nThe paragraph is about the \"update\" subcommand, and then mentions\nhow the subcommand is affected by options and configuration. And\n\"OVERRIDING\" the topic of this thread is only about configuration.\n\nDisecting what each sentence in the existing paragraph says:\n\n - This is about updating the submodule working tree to match\n what the superproject expects.\n\n - There can be three ways how it is \"updated\" (and one way to\n leave it not updated), by setting submodule.$name.update\n and/or giving --rebase, --merge or --checkout option, and one\n way to leave it not \"updated\" by setting .update=none.\n\n - The .update=none can be defeated with --checkout\n\nwhich I think is a mess.\n\nIt is a fairly common and uniform pattern that command line options\noverride configured defaults, so I think it could be argued that\n\"you can override .update=none or .update=anything with command line\noption\" is not even worth saying. Definitely not by piling yet\nanother \"oh by the way, if you have this, things behave differently\nagain\" on top of existing description.\n\n\tUpdate the registered submodules to match what the superproject\n\texpects by cloning missing submodules and updating the\n\tworking tree of the submodules. The \"updating\" can take\n\tvarious forms:\n\n\t(1) By default, or by explicitly giving `--checkout` option,\n the HEAD of the submodules are detached to the exact\n commit recorded by the superproject.\n\n\t(2) By giving `--rebase` or `--merge` option, the commit\n that happens to be checked out in the submodule's\n working tree is integrated with the commit recorded by\n the superproject by rebasing or merging, respectively.\n\n\tSetting submodule.$name.update configuration to `rebase` or\n `merge` will make `git submodule update` without these\n command line options to default to `--rebase` or `--merge`,\n respectively.\n\n\tAlso, setting submodule.$name.update configuration to `none`\n marks the named submodule not updated by \"submodule update\"\n by default (you can still use `--checkout`, `--merge`, or\n `--rebase`).\n\nOr something perhaps? Or the detailed description of\nsubmodule.$name.update should be dropped from here and refer the\nreader to config.txt instead?\n"},{"id":"251367","messageId":"87k33bao7w.fsf@steelpick.2x.cz","threadId":"37868","inReplyTo":"xmqqbnooq863.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] submodule: Fix documentation of update subcommand","fromName":"Michal Sojka","fromEmail":"sojkam1@fel.cvut.cz","sentAt":"2014-11-03T22:55:31Z","receivedAt":"2014-11-03T22:55:31Z","isPatch":true,"sender":{"key":"sojkam1@fel.cvut.cz","avatar":"https://avatars.githubusercontent.com/u/140542?v=4"},"body":"On Mon, Nov 03 2014, Junio C Hamano wrote:\n> Jens Lehmann writes:\n>\n>> This was introduced in e6a1c43aaf (document submdule.$name.update=none\n>> option for gitmodules), and I agree with Michal that we should fix it.\n>> But I think we should rather say \"This can be overridden by specifying\n>> '--merge', '--rebase' or `--checkout`.\" here, as the other two options\n>> also override the update setting. So I think we should queue this:\n>>\n>> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n>> index 8e6af65..84ab577 100644\n>> --- a/Documentation/git-submodule.txt\n>> +++ b/Documentation/git-submodule.txt\n>> @@ -158,7 +158,7 @@ update::\n>> \tcheckout the commit specified in the index of the containing repository.\n>> \tThis will make the submodules HEAD be detached unless `--rebase` or\n>> \t`--merge` is specified or the key `submodule.$name.update` is set to\n>> -\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n>> +\t`rebase`, `merge` or `none`. This can be overridden by using '--merge',\n>> +\t'--rebase' or\n>> \t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n>> \twill cause `command` to be run. `command` can be any arbitrary shell\n>> \tcommand that takes a single argument, namely the sha1 to update to.\n>>\n>> Apart from that I'm all for it.\n>\n> But read the whole thing again. Isn't that a bit roundabout and\n> tortuous?\n>\n> The paragraph is about the \"update\" subcommand, and then mentions\n> how the subcommand is affected by options and configuration. And\n> \"OVERRIDING\" the topic of this thread is only about configuration.\n>\n> Disecting what each sentence in the existing paragraph says:\n>\n> - This is about updating the submodule working tree to match\n> what the superproject expects.\n>\n> - There can be three ways how it is \"updated\" (and one way to\n> leave it not updated), by setting submodule.$name.update\n> and/or giving --rebase, --merge or --checkout option, and one\n> way to leave it not \"updated\" by setting .update=none.\n>\n> - The .update=none can be defeated with --checkout\n>\n> which I think is a mess.\n>\n> It is a fairly common and uniform pattern that command line options\n> override configured defaults, so I think it could be argued that\n> \"you can override .update=none or .update=anything with command line\n> option\" is not even worth saying. Definitely not by piling yet\n> another \"oh by the way, if you have this, things behave differently\n> again\" on top of existing description.\n>\n> \tUpdate the registered submodules to match what the superproject\n> \texpects by cloning missing submodules and updating the\n> \tworking tree of the submodules. The \"updating\" can take\n> \tvarious forms:\n>\n> \t(1) By default, or by explicitly giving `--checkout` option,\n> the HEAD of the submodules are detached to the exact\n> commit recorded by the superproject.\n>\n> \t(2) By giving `--rebase` or `--merge` option, the commit\n> that happens to be checked out in the submodule's\n> working tree is integrated with the commit recorded by\n> the superproject by rebasing or merging, respectively.\n>\n> \tSetting submodule.$name.update configuration to `rebase` or\n> `merge` will make `git submodule update` without these\n> command line options to default to `--rebase` or `--merge`,\n> respectively.\n>\n> \tAlso, setting submodule.$name.update configuration to `none`\n> marks the named submodule not updated by \"submodule update\"\n> by default (you can still use `--checkout`, `--merge`, or\n> `--rebase`).\n\nThis sounds good, but it doesn't mention the `!command` value of\n.update. I'd call this form (3). But then different update forms would\nmix config settings and command line options.\n\n> Or something perhaps? Or the detailed description of\n> submodule.$name.update should be dropped from here and refer the\n> reader to config.txt instead?\n\nI guess you mean gitmodules.txt.\n\nThe `!command` form is not documented in gitmodules.txt. Maybe it would\nbe best to fully document .update in gitmodules.txt and just refer to\nthere. Having documentation at two places seems to be confusing not only\nfor users, but also for those who send patches :)\n\nI'm no longer able to formulate my proposal properly as a patch tonight,\nbut if needed I'll try it later.\n\n-Michal\n"},{"id":"251368","messageId":"xmqq7fzbriew.fsf@gitster.dls.corp.google.com","threadId":"37868","inReplyTo":"87k33bao7w.fsf@steelpick.2x.cz","subject":"Re: [PATCH] submodule: Fix documentation of update subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-11-03T23:08:55Z","receivedAt":"2014-11-03T23:08:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michal Sojka writes:\n\n> This sounds good, but it doesn't mention the `!command` value of\n> .update.\n\nThat part is unchanged by what I did. My rewrite was up to\n\n\t... by specifying `--checkout`.\n\nof the existing text.\n\n>> Or something perhaps? Or the detailed description of\n>> submodule.$name.update should be dropped from here and refer the\n>> reader to config.txt instead?\n>\n> I guess you mean gitmodules.txt.\n\nActually, I do mean the configuration. .gitmodules is just a\ntemplate to help the user populate .git/config, and the latter of\nwhich should be the sole source of truth. This is an important\nprinciple, and it becomes even more important once we start talking\nabout security sensitive possiblity like allowing !command as the\nvalue.\n\n> The `!command` form is not documented in gitmodules.txt. Maybe it would\n> be best to fully document .update in gitmodules.txt and just refer to\n> there. Having documentation at two places seems to be confusing not only\n> for users, but also for those who send patches :)\n>\n> I'm no longer able to formulate my proposal properly as a patch tonight,\n> but if needed I'll try it later.\n\nThat is fine. People have lived with the current text for more than\ntwo years without problems, so we are obviously not in a hurry.\n"},{"id":"251382","messageId":"54593572.3080805@web.de","threadId":"37868","inReplyTo":"xmqq7fzbriew.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] submodule: Fix documentation of update subcommand","fromName":"Jens Lehmann","fromEmail":"jens.lehmann@web.de","sentAt":"2014-11-04T20:22:10Z","receivedAt":"2014-11-04T20:22:10Z","isPatch":true,"sender":{"key":"jens.lehmann@web.de","avatar":"https://avatars.githubusercontent.com/u/135220?v=4"},"body":"Am 04.11.2014 um 00:08 schrieb Junio C Hamano:\n> Michal Sojka writes:\n>>> Or something perhaps? Or the detailed description of\n>>> submodule.$name.update should be dropped from here and refer the\n>>> reader to config.txt instead?\n>>\n>> I guess you mean gitmodules.txt.\n>\n> Actually, I do mean the configuration. .gitmodules is just a\n> template to help the user populate .git/config, and the latter of\n> which should be the sole source of truth. This is an important\n> principle, and it becomes even more important once we start talking\n> about security sensitive possiblity like allowing !command as the\n> value.\n\nNot quite. You're definitely right about the !command value for\nthe 'update' setting; this should never be taken from .gitmodules\nbut only from .git/config. But apart from that following this\nprinciple would hurt submodule users a lot. The only thing that\nshould be set in stone in .git/config is the 'url' setting,\nbecause an older url might not even exist anmore. But e.g. the\n'branch' setting must be taken from .gitmodules. Otherwise we\ncould not change it on a per-superproject-branch basis. And if\nthe 'path' setting would only be taken from .git/config instead\nof .gitmodules, we wouldn't even be able to rename submodules\n(which is exactly what this setting was added for in the first\nplace). The same applies to 'ignore' and 'fetch'.\n\nSo I believe that gitmodules.txt should describe all ćonfig\noptions that can be provided by upstream (and e.g. mention that\nthe 'url' and 'update' values are copied into .git/config on\ninit), while all settings that can be overridden locally should\nbe documented in config.txt (which will be a subset of those\ndocumented in gitmodules.txt).\n\n>> The `!command` form is not documented in gitmodules.txt. Maybe it would\n>> be best to fully document .update in gitmodules.txt and just refer to\n>> there. Having documentation at two places seems to be confusing not only\n>> for users, but also for those who send patches :)\n>>\n>> I'm no longer able to formulate my proposal properly as a patch tonight,\n>> but if needed I'll try it later.\n>\n> That is fine. People have lived with the current text for more than\n> two years without problems, so we are obviously not in a hurry.\n\nYup.\n"},{"id":"251385","messageId":"xmqqk33aptw3.fsf@gitster.dls.corp.google.com","threadId":"37868","inReplyTo":"54593572.3080805@web.de","subject":"Re: [PATCH] submodule: Fix documentation of update subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-11-04T20:56:12Z","receivedAt":"2014-11-04T20:56:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jens Lehmann writes:\n\n> So I believe that gitmodules.txt should describe all ćonfig\n> options that can be provided by upstream (and e.g. mention that\n> the 'url' and 'update' values are copied into .git/config on\n> init), while all settings that can be overridden locally should\n> be documented in config.txt (which will be a subset of those\n> documented in gitmodules.txt).\n\nRight; thanks.\n"},{"id":"256244","messageId":"xmqqvbj0yx6c.fsf@gitster.dls.corp.google.com","threadId":"37868","inReplyTo":"5457EC81.2060504@web.de","subject":"Re: [PATCH] submodule: Fix documentation of update subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-02-17T22:45:31Z","receivedAt":"2015-02-17T22:45:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jens Lehmann writes:\n\n> Yup, but we should also mention '--merge' and '--rebase' here.\n\nThis has been sitting in the Stalled pile for quite a while and I am\ngetting tired of waiting. How does this look?\n\n-- >8 --\nFrom: Michal Sojka \nDate: Mon, 3 Nov 2014 11:09:51 +0100\nSubject: [PATCH] submodule: clarify documentation for update subcommand\n\ne6a1c43a (document submdule.$name.update=none option for gitmodules,\n2012-05-10) meant to say \"Unlike the case where your .update\nconfiguration is set to either 'rebase' or 'merge', when it is set\nto 'none', the tip of the submodule would never move. You can use\nthe --checkout option if you want the contents of the submodule to\nbe updated to some other commit.\"\n\nBut the resulting text made it sound as if using \"--checkout\" would\nhave no effect when .update configuration is set to 'rebase' or\n'merge', which was misleading. In fact, with the \"--checkout\"\noption, the tip of the submodule moves to the exact commit that is\nrecorded in the superproject tree, regardless of .update\nconfiguration.\n\nSigned-off-by: Michal Sojka \nSigned-off-by: Junio C Hamano \n---\n Documentation/git-submodule.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 8e6af65..9bfcdf5 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -158,7 +158,8 @@ update::\n \tcheckout the commit specified in the index of the containing repository.\n \tThis will make the submodules HEAD be detached unless `--rebase` or\n \t`--merge` is specified or the key `submodule.$name.update` is set to\n-\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n+\t`rebase`, `merge` or `none`. The configuration can be overridden by\n+\tspecifying `--rebase`, `--merge`, or\n \t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n \twill cause `command` to be run. `command` can be any arbitrary shell\n \tcommand that takes a single argument, namely the sha1 to update to.\n-- \n2.3.0-301-g71e72fe\n"},{"id":"256320","messageId":"1424299716-21138-1-git-send-email-sojkam1@fel.cvut.cz","threadId":"37868","inReplyTo":"xmqqvbj0yx6c.fsf@gitster.dls.corp.google.com","subject":"[PATCH v2] submodule: Fix documentation of update subcommand","fromName":"Michal Sojka","fromEmail":"sojkam1@fel.cvut.cz","sentAt":"2015-02-18T22:48:36Z","receivedAt":"2015-02-18T22:48:36Z","isPatch":true,"sender":{"key":"sojkam1@fel.cvut.cz","avatar":"https://avatars.githubusercontent.com/u/140542?v=4"},"body":"The documentation of 'git submodule update' has several problems:\n\n1) It says that submodule.$name.update can be overridden by --checkout\n only if its value is `none`. This is not true, because both\n implementation and documentation of --checkout specifies that the\n override applies to all possible values.\n\n2) The documentation of submodule.$name.update key is scattered across\n three places, which is confusing.\n\n3) The documentation of submodule.$name.update in gitmodules.txt is\n incorrect, because the code always uses the value from .git/config\n and never from .gitmodules.\n\nThis patch fixes all three problems. Now, submodule.$name.update is\nfully documented in config.txt and the other files just refer to it.\nThis is based on discussion between myself, Junio C Hamano and Jens\nLehmann.\n\nSigned-off-by: Michal Sojka \n---\n Documentation/config.txt | 27 ++++++++++++++++++++++-----\n Documentation/git-submodule.txt | 17 ++++++++---------\n Documentation/gitmodules.txt | 18 ++++++------------\n 3 files changed, 36 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex ae6791d..f30cbbc 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -2411,12 +2411,29 @@ status.submodulesummary::\n \n submodule..path::\n submodule..url::\n+\tThe path within this project and URL for a submodule. These\n+\tvariables are initially populated by 'git submodule init';\n+\tedit them to override the URL and other values found in the\n+\t`.gitmodules` file. See linkgit:git-submodule[1] and\n+\tlinkgit:gitmodules[5] for details.\n+\n submodule..update::\n-\tThe path within this project, URL, and the updating strategy\n-\tfor a submodule. These variables are initially populated\n-\tby 'git submodule init'; edit them to override the\n-\tURL and other values found in the `.gitmodules` file. See\n-\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n+\tThe default updating strategy for a submodule, used by `git\n+\tsubmodule update`. This variable is populated by `git\n+\tsubmodule init` from linkgit:gitmodules[5].\n+\n+\tIf the value is 'checkout' (the default), the new commit\n+\tspecified in the superproject will be checked out in the\n+\tsubmodule on a detached HEAD.\n+\tIf 'rebase', the current branch of the submodule will be\n+\trebased onto the commit specified in the superproject.\n+\tIf 'merge', the commit specified in the superproject will be\n+\tmerged into the current branch in the submodule. If 'none',\n+\tthe submodule with name `$name` will not be updated by\n+\tdefault.\n+\tIf the value is of form '!command', it will cause `command` to\n+\tbe run. `command` can be any arbitrary shell command that\n+\ttakes a single argument, namely the sha1 to update to.\n \n submodule..branch::\n \tThe remote branch name for a submodule, used by `git submodule\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 8e6af65..c92908e 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -154,14 +154,13 @@ If `--force` is specified, the submodule's work tree will be removed even if\n it contains local modifications.\n \n update::\n-\tUpdate the registered submodules, i.e. clone missing submodules and\n-\tcheckout the commit specified in the index of the containing repository.\n-\tThis will make the submodules HEAD be detached unless `--rebase` or\n-\t`--merge` is specified or the key `submodule.$name.update` is set to\n-\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n-\t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n-\twill cause `command` to be run. `command` can be any arbitrary shell\n-\tcommand that takes a single argument, namely the sha1 to update to.\n+\tUpdate the registered submodules to match what the superproject\n+\texpects by cloning missing submodules and updating the working\n+\ttree of the submodules. The \"updating\" can take various forms\n+\tand can be configured in .git/config by the\n+\t`submodule.$name.update` key or by explicitely giving one of\n+\t'--checkout' (the default), '--merge' or '--rebase' options. See\n+\tlinkgit:git-config[1] for details.\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@@ -302,7 +301,7 @@ the submodule itself.\n \tCheckout the commit recorded in the superproject on a detached HEAD\n \tin the submodule. This is the default behavior, the main use of\n \tthis option is to override `submodule.$name.update` when set to\n-\t`merge`, `rebase` or `none`.\n+\tother value than `checkout`.\n \tIf the key `submodule.$name.update` is either not explicitly set or\n \tset to `checkout`, this option is implicit.\n \ndiff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt\nindex f6c0dfd..59efbfe 100644\n--- a/Documentation/gitmodules.txt\n+++ b/Documentation/gitmodules.txt\n@@ -38,18 +38,12 @@ submodule..url::\n In addition, there are a number of optional keys:\n \n submodule..update::\n-\tDefines what to do when the submodule is updated by the superproject.\n-\tIf 'checkout' (the default), the new commit specified in the\n-\tsuperproject will be checked out in the submodule on a detached HEAD.\n-\tIf 'rebase', the current branch of the submodule will be rebased onto\n-\tthe commit specified in the superproject. If 'merge', the commit\n-\tspecified in the superproject will be merged into the current branch\n-\tin the submodule.\n-\tIf 'none', the submodule with name `$name` will not be updated\n-\tby default.\n-\n-\tThis config option is overridden if 'git submodule update' is given\n-\tthe '--merge', '--rebase' or '--checkout' options.\n+\tDefines what to do when the submodule is updated by the\n+\tsuperproject. This is only used by `git submodule init` to\n+\tinitialize the variable of the same name in .git/config.\n+\tAllowed values here are 'checkout', 'rebase', 'merge' or\n+\t'none'. See linkgit:git-config[1] for their meaning and other\n+\tvalues that can be configured manually by users.\n \n submodule..branch::\n \tA remote branch name for tracking updates in the upstream submodule.\n-- \n2.1.4\n"},{"id":"256324","messageId":"xmqqbnkq23a0.fsf@gitster.dls.corp.google.com","threadId":"37868","inReplyTo":"1424299716-21138-1-git-send-email-sojkam1@fel.cvut.cz","subject":"Re: [PATCH v2] submodule: Fix documentation of update subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-02-18T23:44:39Z","receivedAt":"2015-02-18T23:44:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michal Sojka writes:\n\n> The documentation of 'git submodule update' has several problems:\n>\n> 1) It says that submodule.$name.update can be overridden by --checkout\n> only if its value is `none`.\n\nHmm, I do not read the existing sentence that way, though. The\n\"only if\" above is only in your head and not in the documentation,\nno? The way I understand it is that the explanation does not even\nbother to say that it is overridable when update is set to something\nthat clearly corresponds to --option (e.g. 'update=rebase' is for\npeople too lazy to type --rebase from the command line), but because\nit is unclear when it is set to 'update=none', it specifically\nsingles out that case.\n\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index ae6791d..f30cbbc 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -2411,12 +2411,29 @@ status.submodulesummary::\n> \n> submodule..path::\n> submodule..url::\n> +\tThe path within this project and URL for a submodule. These\n> +\tvariables are initially populated by 'git submodule init';\n> +\tedit them to override the URL and other values found in the\n> +\t`.gitmodules` file. See linkgit:git-submodule[1] and\n> +\tlinkgit:gitmodules[5] for details.\n> +\n\nOK.\n\n> submodule..update::\n> -\tThe path within this project, URL, and the updating strategy\n> -\tfor a submodule. These variables are initially populated\n> -\tby 'git submodule init'; edit them to override the\n> -\tURL and other values found in the `.gitmodules` file. See\n> -\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n> +\tThe default updating strategy for a submodule, used by `git\n> +\tsubmodule update`. This variable is populated by `git\n> +\tsubmodule init` from linkgit:gitmodules[5].\n> +\n> +\tIf the value is 'checkout' (the default), the new commit\n> +\tspecified in the superproject will be checked out in the\n\nHave you formatted this? I _think_ this change would break the\ntypesetting by having an empty line there.\n\n> +\tsubmodule on a detached HEAD.\n> +\tIf 'rebase', the current branch of the submodule will be\n> +\trebased onto the commit specified in the superproject.\n> +\tIf 'merge', the commit specified in the superproject will be\n> +\tmerged into the current branch in the submodule. If 'none',\n> +\tthe submodule with name `$name` will not be updated by\n> +\tdefault.\n> +\tIf the value is of form '!command', it will cause `command` to\n> +\tbe run. `command` can be any arbitrary shell command that\n> +\ttakes a single argument, namely the sha1 to update to.\n\nI have a feeling that it is better to leave the explanations of\nthese values in git-submodule.txt (i.e. where you took the above\ntext from) and say \"see description of 'update' command in\nlinkgit:git-submodule[1]\" here to avoid duplication.\n\n> submodule..branch::\n> \tThe remote branch name for a submodule, used by `git submodule\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 8e6af65..c92908e 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -154,14 +154,13 @@ If `--force` is specified, the submodule's work tree will be removed even if\n> it contains local modifications.\n> \n> update::\n> -\tUpdate the registered submodules, i.e. clone missing submodules and\n> -\tcheckout the commit specified in the index of the containing repository.\n> -\tThis will make the submodules HEAD be detached unless `--rebase` or\n> -\t`--merge` is specified or the key `submodule.$name.update` is set to\n> -\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n> -\t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n> -\twill cause `command` to be run. `command` can be any arbitrary shell\n> -\tcommand that takes a single argument, namely the sha1 to update to.\n> +\tUpdate the registered submodules to match what the superproject\n> +\texpects by cloning missing submodules and updating the working\n> +\ttree of the submodules....\n\nThis part is better than the original.\n\n> The \"updating\" can take various forms\n> +\tand can be configured in .git/config by the\n> +\t`submodule.$name.update` key or by explicitely giving one of\n> +\t'--checkout' (the default), '--merge' or '--rebase' options. See\n> +\tlinkgit:git-config[1] for details.\n\nBecause submodule..update is interesting only to those who run\n\"git submodule update\", and also the command line options that\ninteract with the setting are only described here not in config.txt,\nI think it is better to have the description of various modes here.\n\nAnd the description, if it is done here, can clarify the precedence\n(i.e. command line trumps configuration) and semantics\n(i.e. configuration 'update=checkout' and option --checkout are both\nto trigger the same behaviour), perhaps like this:\n\n\tThe updating can be done in one of three ways:\n\n checkout;; detaches the HEAD in the submodule at the commit\n that is recorded by the superproject. This is done when\n --checkout option is given, or no option is given, and\n submodule..update is unset, or if it is set to\n 'checkout'.\n rebase;; EXPLAIN IN A SIMILAR WAY, talk about --rebase,\n 'rebase', etc.\n merge;; EXPLAIN IN A SIMILAR WAY, talk about --merge,\n 'merge', etc.\n\n When no option is given and submodule..update is set\n to 'none', the submodule is not updated.\n\nIt would be awkward to talk about --option in any of the other pages\nlike config.txt and gitmodules.txt, but the relationship between the\noptions and configurations must be explained somewhere, so....\n"},{"id":"256356","messageId":"87d255zt0j.fsf@steelpick.2x.cz","threadId":"37868","inReplyTo":"xmqqbnkq23a0.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2] submodule: Fix documentation of update subcommand","fromName":"Michal Sojka","fromEmail":"sojkam1@fel.cvut.cz","sentAt":"2015-02-19T17:54:36Z","receivedAt":"2015-02-19T17:54:36Z","isPatch":true,"sender":{"key":"sojkam1@fel.cvut.cz","avatar":"https://avatars.githubusercontent.com/u/140542?v=4"},"body":"On Thu, Feb 19 2015, Junio C Hamano wrote:\n> Michal Sojka writes:\n>\n>> The documentation of 'git submodule update' has several problems:\n>>\n>> 1) It says that submodule.$name.update can be overridden by --checkout\n>> only if its value is `none`.\n>\n> Hmm, I do not read the existing sentence that way, though. The\n> \"only if\" above is only in your head and not in the documentation,\n> no?\n\nYes, you're right.\n\n> The way I understand it is that the explanation does not even bother\n> to say that it is overridable when update is set to something that\n> clearly corresponds to --option (e.g. 'update=rebase' is for people\n> too lazy to type --rebase from the command line), but because it is\n> unclear when it is set to 'update=none', it specifically singles out\n> that case.\n\nI updated the commit message a bit.\n\n>> diff --git a/Documentation/config.txt b/Documentation/config.txt\n>> index ae6791d..f30cbbc 100644\n>> --- a/Documentation/config.txt\n>> +++ b/Documentation/config.txt\n>> @@ -2411,12 +2411,29 @@ status.submodulesummary::\n>>\n>> submodule..path::\n>> submodule..url::\n>> +\tThe path within this project and URL for a submodule. These\n>> +\tvariables are initially populated by 'git submodule init';\n>> +\tedit them to override the URL and other values found in the\n>> +\t`.gitmodules` file. See linkgit:git-submodule[1] and\n>> +\tlinkgit:gitmodules[5] for details.\n>> +\n>\n> OK.\n>\n>> submodule..update::\n>> -\tThe path within this project, URL, and the updating strategy\n>> -\tfor a submodule. These variables are initially populated\n>> -\tby 'git submodule init'; edit them to override the\n>> -\tURL and other values found in the `.gitmodules` file. See\n>> -\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n>> +\tThe default updating strategy for a submodule, used by `git\n>> +\tsubmodule update`. This variable is populated by `git\n>> +\tsubmodule init` from linkgit:gitmodules[5].\n>> +\n>> +\tIf the value is 'checkout' (the default), the new commit\n>> +\tspecified in the superproject will be checked out in the\n>\n> Have you formatted this? I _think_ this change would break the\n> typesetting by having an empty line there.\n\nRight. I need to add a '+' and deindent.\n\n>> +\tsubmodule on a detached HEAD.\n>> +\tIf 'rebase', the current branch of the submodule will be\n>> +\trebased onto the commit specified in the superproject.\n>> +\tIf 'merge', the commit specified in the superproject will be\n>> +\tmerged into the current branch in the submodule. If 'none',\n>> +\tthe submodule with name `$name` will not be updated by\n>> +\tdefault.\n>> +\tIf the value is of form '!command', it will cause `command` to\n>> +\tbe run. `command` can be any arbitrary shell command that\n>> +\ttakes a single argument, namely the sha1 to update to.\n>\n> I have a feeling that it is better to leave the explanations of\n> these values in git-submodule.txt (i.e. where you took the above\n> text from) and say \"see description of 'update' command in\n> linkgit:git-submodule[1]\" here to avoid duplication.\n\nOK\n\n>> submodule..branch::\n>> \tThe remote branch name for a submodule, used by `git submodule\n>> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n>> index 8e6af65..c92908e 100644\n>> --- a/Documentation/git-submodule.txt\n>> +++ b/Documentation/git-submodule.txt\n>> @@ -154,14 +154,13 @@ If `--force` is specified, the submodule's work tree will be removed even if\n>> it contains local modifications.\n>>\n>> update::\n>> -\tUpdate the registered submodules, i.e. clone missing submodules and\n>> -\tcheckout the commit specified in the index of the containing repository.\n>> -\tThis will make the submodules HEAD be detached unless `--rebase` or\n>> -\t`--merge` is specified or the key `submodule.$name.update` is set to\n>> -\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n>> -\t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n>> -\twill cause `command` to be run. `command` can be any arbitrary shell\n>> -\tcommand that takes a single argument, namely the sha1 to update to.\n>> +\tUpdate the registered submodules to match what the superproject\n>> +\texpects by cloning missing submodules and updating the working\n>> +\ttree of the submodules....\n>\n> This part is better than the original.\n\nIndeed. You wrote this in a previous email :)\n\n>> The \"updating\" can take various forms\n>> +\tand can be configured in .git/config by the\n>> +\t`submodule.$name.update` key or by explicitely giving one of\n>> +\t'--checkout' (the default), '--merge' or '--rebase' options. See\n>> +\tlinkgit:git-config[1] for details.\n>\n> Because submodule..update is interesting only to those who run\n> \"git submodule update\", and also the command line options that\n> interact with the setting are only described here not in config.txt,\n> I think it is better to have the description of various modes here.\n>\n> And the description, if it is done here, can clarify the precedence\n> (i.e. command line trumps configuration) and semantics\n> (i.e. configuration 'update=checkout' and option --checkout are both\n> to trigger the same behaviour), perhaps like this:\n>\n> \tThe updating can be done in one of three ways:\n>\n> checkout;; detaches the HEAD in the submodule at the commit\n> that is recorded by the superproject. This is done when\n> --checkout option is given, or no option is given, and\n> submodule..update is unset, or if it is set to\n> 'checkout'.\n> rebase;; EXPLAIN IN A SIMILAR WAY, talk about --rebase,\n> 'rebase', etc.\n> merge;; EXPLAIN IN A SIMILAR WAY, talk about --merge,\n> 'merge', etc.\n>\n> When no option is given and submodule..update is set\n> to 'none', the submodule is not updated.\n>\n> It would be awkward to talk about --option in any of the other pages\n> like config.txt and gitmodules.txt, but the relationship between the\n> options and configurations must be explained somewhere, so....\n\nAgreed expect that there is a fourth way: !command. But this could be\neasily added here as well.\n\nI'll send an updated patch in a while.\n\nThanks.\n-Michal\n"},{"id":"256360","messageId":"1424371972-13393-1-git-send-email-sojkam1@fel.cvut.cz","threadId":"37868","inReplyTo":"87d255zt0j.fsf@steelpick.2x.cz","subject":"[PATCH v3] submodule: Improve documentation of update subcommand","fromName":"Michal Sojka","fromEmail":"sojkam1@fel.cvut.cz","sentAt":"2015-02-19T18:52:52Z","receivedAt":"2015-02-19T18:52:52Z","isPatch":true,"sender":{"key":"sojkam1@fel.cvut.cz","avatar":"https://avatars.githubusercontent.com/u/140542?v=4"},"body":"The documentation of 'git submodule update' has several problems:\n\n1) It mentions that value 'none' of submodule.$name.update can be\n overridden by --checkout, but other combinations of configuration\n values and command line options are not mentioned.\n\n2) The documentation of submodule.$name.update is scattered across three\n places, which is confusing.\n\n3) The documentation of submodule.$name.update in gitmodules.txt is\n incorrect, because the code always uses the value from .git/config\n and never from .gitmodules.\n\n4) Documentation of --force was incomplete, because it is only effective\n in case of checkout method of update.\n\nThis patch fixes all these problems. Now, submodule.$name.update is\nfully documented in git-submodule.txt and the other files just refer to\nit. This is based on discussion between Junio C Hamano, Jens Lehmann and\nmyself.\n\nSigned-off-by: Michal Sojka \n---\n Documentation/config.txt | 15 +++++++----\n Documentation/git-submodule.txt | 58 +++++++++++++++++++++++++++++------------\n Documentation/gitmodules.txt | 18 +++++--------\n 3 files changed, 57 insertions(+), 34 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex ae6791d..fb2ae37 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -2411,12 +2411,17 @@ status.submodulesummary::\n \n submodule..path::\n submodule..url::\n+\tThe path within this project and URL for a submodule. These\n+\tvariables are initially populated by 'git submodule init';\n+\tedit them to override the URL and other values found in the\n+\t`.gitmodules` file. See linkgit:git-submodule[1] and\n+\tlinkgit:gitmodules[5] for details.\n+\n submodule..update::\n-\tThe path within this project, URL, and the updating strategy\n-\tfor a submodule. These variables are initially populated\n-\tby 'git submodule init'; edit them to override the\n-\tURL and other values found in the `.gitmodules` file. See\n-\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n+\tThe default updating strategy 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 \n submodule..branch::\n \tThe remote branch name for a submodule, used by `git submodule\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 8e6af65..72c6fb2 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -154,14 +154,36 @@ If `--force` is specified, the submodule's work tree will be removed even if\n it contains local modifications.\n \n update::\n-\tUpdate the registered submodules, i.e. clone missing submodules and\n-\tcheckout the commit specified in the index of the containing repository.\n-\tThis will make the submodules HEAD be detached unless `--rebase` or\n-\t`--merge` is specified or the key `submodule.$name.update` is set to\n-\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n-\t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n-\twill cause `command` to be run. `command` can be any arbitrary shell\n-\tcommand that takes a single argument, namely the sha1 to update to.\n+\tUpdate the registered submodules to match what the superproject\n+\texpects by cloning missing submodules and updating the working\n+\ttree of the submodules. The \"updating\" can be done in several\n+\tways depending on command line options and the value of\n+\t`submodule..update` in .git/config:\n+\n+\tcheckout;; the new commit recorded in the superproject will be\n+\t checked out in the submodule on a detached HEAD. This is\n+\t done when `--checkout` option is given, or no option is\n+\t given, and `submodule..update` is unset, or if it is set\n+\t to 'checkout'.\n+\n+\trebase;; the current branch of the submodule will be rebased\n+\t onto the commit recoded in the superproject. This is done\n+\t when `--rebase` option is given, or no option is given, and\n+\t `submodule..update` is set to 'rebase'.\n+\n+\tmerge;; the commit recorded in the superproject will be merged\n+\t into the current branch in the submodule. This is done\n+\t when `--merge` option is given, or no option is given, and\n+\t `submodule..update` is set to 'merge'.\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. This is done when no option is\n+\t given, and `submodule..update` has the form of\n+\t '!command'.\n++\n+When no option is given and `submodule..update` is set to 'none',\n+the submodule is not updated.\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@@ -170,10 +192,11 @@ submodule with the `--init` option.\n If `--recursive` is specified, this command will recurse into the\n registered submodules, and update any nested submodules within.\n +\n-If `--force` is specified, the submodule will be checked out (using\n-`git checkout --force` if appropriate), even if the commit specified in the\n-index of the containing repository already matches the commit checked out in\n-the submodule.\n+If `--force` is specified and the checkout method of update is used, the\n+submodule will be checked out (using `git checkout --force` if\n+appropriate), even if the commit specified in the index of the\n+containing repository already matches the commit checked out in the\n+submodule.\n \n summary::\n \tShow commit summary between the given commit (defaults to HEAD) and\n@@ -238,10 +261,11 @@ OPTIONS\n \tWhen running add, allow adding an otherwise ignored submodule path.\n \tWhen running deinit the submodule work trees will be removed even if\n \tthey contain local changes.\n-\tWhen running update, throw away local changes in submodules when\n-\tswitching to a different commit; and always run a checkout operation\n-\tin the submodule, even if the commit listed in the index of the\n-\tcontaining repository matches the commit checked out in the submodule.\n+\tWhen running update and the checkout method is used, throw away\n+\tlocal changes in submodules when switching to a different\n+\tcommit; and always run a checkout operation in the submodule,\n+\teven if the commit listed in the index of the containing\n+\trepository matches the commit checked out in the submodule.\n \n --cached::\n \tThis option is only valid for status and summary commands. These\n@@ -302,7 +326,7 @@ the submodule itself.\n \tCheckout the commit recorded in the superproject on a detached HEAD\n \tin the submodule. This is the default behavior, the main use of\n \tthis option is to override `submodule.$name.update` when set to\n-\t`merge`, `rebase` or `none`.\n+\tother value than `checkout`.\n \tIf the key `submodule.$name.update` is either not explicitly set or\n \tset to `checkout`, this option is implicit.\n \ndiff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt\nindex f6c0dfd..a51183c 100644\n--- a/Documentation/gitmodules.txt\n+++ b/Documentation/gitmodules.txt\n@@ -38,18 +38,12 @@ submodule..url::\n In addition, there are a number of optional keys:\n \n submodule..update::\n-\tDefines what to do when the submodule is updated by the superproject.\n-\tIf 'checkout' (the default), the new commit specified in the\n-\tsuperproject will be checked out in the submodule on a detached HEAD.\n-\tIf 'rebase', the current branch of the submodule will be rebased onto\n-\tthe commit specified in the superproject. If 'merge', the commit\n-\tspecified in the superproject will be merged into the current branch\n-\tin the submodule.\n-\tIf 'none', the submodule with name `$name` will not be updated\n-\tby default.\n-\n-\tThis config option is overridden if 'git submodule update' is given\n-\tthe '--merge', '--rebase' or '--checkout' options.\n+\tDefines what to do when the submodule is updated by the\n+\tsuperproject. This is only used by `git submodule init` to\n+\tinitialize the variable of the same name in .git/config.\n+\tAllowed values here are 'checkout', 'rebase', 'merge' or\n+\t'none'. See description of 'update' command in\n+\tlinkgit:git-submodule[1] for their meaning.\n \n submodule..branch::\n \tA remote branch name for tracking updates in the upstream submodule.\n-- \n2.1.4\n"},{"id":"256447","messageId":"xmqqlhjsxira.fsf@gitster.dls.corp.google.com","threadId":"37868","inReplyTo":"1424371972-13393-1-git-send-email-sojkam1@fel.cvut.cz","subject":"Re: [PATCH v3] submodule: Improve documentation of update subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-02-20T23:31:21Z","receivedAt":"2015-02-20T23:31:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michal Sojka writes:\n\n> This patch fixes all these problems. Now, submodule.$name.update is\n> fully documented in git-submodule.txt and the other files just refer to\n\n\"Fix all these problems by documenting submodule.*.update in\ngit-submodule.txt and make everybody else refer to it\" in imperative\nmood, as if you are giving an order to the source to \"be this way\".\nIt would be sweeter and shorter that way.\n\n> it. This is based on discussion between Junio C Hamano, Jens Lehmann and\n> myself.\n\nIt's customary to just mention them on Helped-by: around here, I\nthink.\n\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 8e6af65..72c6fb2 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -154,14 +154,36 @@ If `--force` is specified, the submodule's work tree will be removed even if\n> it contains local modifications.\n> \n> update::\n> +\tUpdate the registered submodules to match what the superproject\n> +\texpects by cloning missing submodules and updating the working\n> +\ttree of the submodules. The \"updating\" can be done in several\n> +\tways depending on command line options and the value of\n> +\t`submodule..update` in .git/config:\n\nNo quoting around .git/config? Actually, it is probably better not\nto spell out that path. \"... and the value of the `...`\nconfiguration variable\" would be better.\n\n> +\tcheckout;; the new commit recorded in the superproject will be\n> +\t checked out in the submodule on a detached HEAD. This is\n\nDrop \"new\". It does not add anything to the description, and you\nmay even be checking out an old commit in the superproject.\n\n> @@ -238,10 +261,11 @@ OPTIONS\n\nTotally offtopic, but we may want a custom xfuncname for our AsciiDoc\ndocumentation; we would want to see \"--force::\" not \"OPTIONS\" on the\nabove line, I would think.\n\n> \tWhen running add, allow adding an otherwise ignored submodule path.\n> \tWhen running deinit the submodule work trees will be removed even if\n> \tthey contain local changes.\n> -\tWhen running update, throw away local changes in submodules when\n> -\tswitching to a different commit; and always run a checkout operation\n> -\tin the submodule, even if the commit listed in the index of the\n> -\tcontaining repository matches the commit checked out in the submodule.\n> +\tWhen running update and the checkout method is used, throw away\n> +\tlocal changes in submodules when switching to a different\n> +\tcommit; and always run a checkout operation in the submodule,\n> +\teven if the commit listed in the index of the containing\n> +\trepository matches the commit checked out in the submodule.\n\nThis makes a reader wonder what --force would do when --merge or\n--rebase is given from the command line (or specifiedy in the\nconfiguration). The original (unfortunately) did not have that\nproblem because it did not single out the --checkout mode.\n\nThe use of the phrase \"the checkout method\" is iffy, as nobody\ndefines what it is (I just said \"--checkout mode\" to mean the same\nthing, but I do not think anybody defines it). See below.\n\n\n> @@ -302,7 +326,7 @@ the submodule itself.\n> \tCheckout the commit recorded in the superproject on a detached HEAD\n> \tin the submodule. This is the default behavior, the main use of\n> \tthis option is to override `submodule.$name.update` when set to\n> -\t`merge`, `rebase` or `none`.\n> +\tother value than `checkout`.\n\n\"... when set to a value other than `checkout`\", would read better,\nI would think.\n\n> diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt\n> index f6c0dfd..a51183c 100644\n> --- a/Documentation/gitmodules.txt\n> +++ b/Documentation/gitmodules.txt\n> @@ -38,18 +38,12 @@ submodule..url::\n> In addition, there are a number of optional keys:\n> \n> submodule..update::\n> +\tDefines what to do when the submodule is updated by the\n> +\tsuperproject. This is only used by `git submodule init` to\n> +\tinitialize the variable of the same name in .git/config.\n> +\tAllowed values here are 'checkout', 'rebase', 'merge' or\n> +\t'none'. See description of 'update' command in\n> +\tlinkgit:git-submodule[1] for their meaning.\n\nWhatever word we decide to use, this may be a good place to\nintroduce it, perhaps like this (if we were to go with 'update\nmethod'):\n\n submodule..update::\n\n\tDefine the default update method for the named submodule,\n\thow the submodule is updated by \"git submodule update\"\n\tcommand in the superproject.\n\nThe enumeration of the allowed values is correct, I think, but we\nmight want to be very clear that we do not copy the !command form\nand that is on purpose.\n"},{"id":"256504","messageId":"87egpgdaac.fsf@steelpick.2x.cz","threadId":"37868","inReplyTo":"xmqqlhjsxira.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v3] submodule: Improve documentation of update subcommand","fromName":"Michal Sojka","fromEmail":"sojkam1@fel.cvut.cz","sentAt":"2015-02-23T13:31:23Z","receivedAt":"2015-02-23T13:31:23Z","isPatch":true,"sender":{"key":"sojkam1@fel.cvut.cz","avatar":"https://avatars.githubusercontent.com/u/140542?v=4"},"body":"On Sat, Feb 21 2015, Junio C Hamano wrote:\n> Michal Sojka writes:\n>> update::\n>> +\tUpdate the registered submodules to match what the superproject\n>> +\texpects by cloning missing submodules and updating the working\n>> +\ttree of the submodules. The \"updating\" can be done in several\n>> +\tways depending on command line options and the value of\n>> +\t`submodule..update` in .git/config:\n>\n> No quoting around .git/config?\n\nThere is not quoting in the rest of the file as well.\n\n> Actually, it is probably better not to spell out that path. \"... and\n> the value of the `...` configuration variable\" would be better.\n\nYes, I changed it to this. See the followup mail.\n\n>> \tWhen running add, allow adding an otherwise ignored submodule path.\n>> \tWhen running deinit the submodule work trees will be removed even if\n>> \tthey contain local changes.\n>> -\tWhen running update, throw away local changes in submodules when\n>> -\tswitching to a different commit; and always run a checkout operation\n>> -\tin the submodule, even if the commit listed in the index of the\n>> -\tcontaining repository matches the commit checked out in the submodule.\n>> +\tWhen running update and the checkout method is used, throw away\n>> +\tlocal changes in submodules when switching to a different\n>> +\tcommit; and always run a checkout operation in the submodule,\n>> +\teven if the commit listed in the index of the containing\n>> +\trepository matches the commit checked out in the submodule.\n>\n> This makes a reader wonder what --force would do when --merge or\n> --rebase is given from the command line (or specifiedy in the\n> configuration). The original (unfortunately) did not have that\n> problem because it did not single out the --checkout mode.\n\nI changed that to \"(only effective with the checkout method)\".\n\n> The use of the phrase \"the checkout method\" is iffy, as nobody\n> defines what it is (I just said \"--checkout mode\" to mean the same\n> thing, but I do not think anybody defines it). See below.\n\nI defined it in gitmodules.txt as you suggest as well as in the\ndescription of update command in git-submodule.txt.\n\nThanks.\n-Michal\n"},{"id":"256505","messageId":"1424698360-10952-1-git-send-email-sojkam1@fel.cvut.cz","threadId":"37868","inReplyTo":"87egpgdaac.fsf@steelpick.2x.cz","subject":"[PATCH] submodule: Improve documentation of update subcommand","fromName":"Michal Sojka","fromEmail":"sojkam1@fel.cvut.cz","sentAt":"2015-02-23T13:32:40Z","receivedAt":"2015-02-23T13:32:40Z","isPatch":true,"sender":{"key":"sojkam1@fel.cvut.cz","avatar":"https://avatars.githubusercontent.com/u/140542?v=4"},"body":"The documentation of 'git submodule update' has several problems:\n\n1) It mentions that value 'none' of submodule.$name.update can be\n overridden by --checkout, but other combinations of configuration\n values and command line options are not mentioned.\n\n2) The documentation of submodule.$name.update is scattered across three\n places, which is confusing.\n\n3) The documentation of submodule.$name.update in gitmodules.txt is\n incorrect, because the code always uses the value from .git/config\n and never from .gitmodules.\n\n4) Documentation of --force was incomplete, because it is only effective\n in case of checkout method of update.\n\nFix all these problems by documenting submodule.*.update in\ngit-submodule.txt and make everybody else refer to it.\n\nHelped-by: Junio C Hamano \nHelped-by: Jens Lehmann \nSigned-off-by: Michal Sojka \n---\n Documentation/config.txt | 15 ++++++----\n Documentation/git-submodule.txt | 66 ++++++++++++++++++++++++++++-------------\n Documentation/gitmodules.txt | 21 ++++++-------\n 3 files changed, 65 insertions(+), 37 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex ae6791d..fb2ae37 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -2411,12 +2411,17 @@ status.submodulesummary::\n \n submodule..path::\n submodule..url::\n+\tThe path within this project and URL for a submodule. These\n+\tvariables are initially populated by 'git submodule init';\n+\tedit them to override the URL and other values found in the\n+\t`.gitmodules` file. See linkgit:git-submodule[1] and\n+\tlinkgit:gitmodules[5] for details.\n+\n submodule..update::\n-\tThe path within this project, URL, and the updating strategy\n-\tfor a submodule. These variables are initially populated\n-\tby 'git submodule init'; edit them to override the\n-\tURL and other values found in the `.gitmodules` file. See\n-\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n+\tThe default updating strategy 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 \n submodule..branch::\n \tThe remote branch name for a submodule, used by `git submodule\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 8e6af65..067d616 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -154,27 +154,51 @@ If `--force` is specified, the submodule's work tree will be removed even if\n it contains local modifications.\n \n update::\n-\tUpdate the registered submodules, i.e. clone missing submodules and\n-\tcheckout the commit specified in the index of the containing repository.\n-\tThis will make the submodules HEAD be detached unless `--rebase` or\n-\t`--merge` is specified or the key `submodule.$name.update` is set to\n-\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n-\t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n-\twill cause `command` to be run. `command` can be any arbitrary shell\n-\tcommand that takes a single argument, namely the sha1 to update to.\n +\n+--\n+Update the registered submodules to match what the superproject\n+expects by cloning missing 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. Supported update methods are:\n+\n+\tcheckout;; the commit recorded in the superproject will be\n+\t checked out in the submodule on a detached HEAD. This is\n+\t done when `--checkout` option is given, or no option is\n+\t given, and `submodule..update` is unset, or if it is\n+\t set to 'checkout'.\n++\n+If `--force` is specified, the submodule will be checked out (using\n+`git checkout --force` if appropriate), even if the commit specified\n+in the index of the containing repository already matches the commit\n+checked out in the submodule.\n+\n+\trebase;; the current branch of the submodule will be rebased\n+\t onto the commit recoded in the superproject. This is done\n+\t when `--rebase` option is given, or no option is given, and\n+\t `submodule..update` is set to 'rebase'.\n+\n+\tmerge;; the commit recorded in the superproject will be merged\n+\t into the current branch in the submodule. This is done\n+\t when `--merge` option is given, or no option is given, and\n+\t `submodule..update` is set to 'merge'.\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. This is done when no option is\n+\t given, and `submodule..update` has the form of\n+\t '!command'.\n+\n+When no option is given and `submodule..update` is set to 'none',\n+the submodule is not updated.\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-+\n+\n If `--recursive` is specified, this command will recurse into the\n registered submodules, and update any nested submodules within.\n-+\n-If `--force` is specified, the submodule will be checked out (using\n-`git checkout --force` if appropriate), even if the commit specified in the\n-index of the containing repository already matches the commit checked out in\n-the submodule.\n-\n+--\n summary::\n \tShow commit summary between the given commit (defaults to HEAD) and\n \tworking tree/index. For a submodule in question, a series of commits\n@@ -238,10 +262,12 @@ OPTIONS\n \tWhen running add, allow adding an otherwise ignored submodule path.\n \tWhen running deinit the submodule work trees will be removed even if\n \tthey contain local changes.\n-\tWhen running update, throw away local changes in submodules when\n-\tswitching to a different commit; and always run a checkout operation\n-\tin the submodule, even if the commit listed in the index of the\n-\tcontaining repository matches the commit checked out in the submodule.\n+\tWhen running update (only effective with the checkout method),\n+\tthrow away local changes in submodules when switching to a\n+\tdifferent commit; and always run a checkout operation in the\n+\tsubmodule, even if the commit listed in the index of the\n+\tcontaining repository matches the commit checked out in the\n+\tsubmodule.\n \n --cached::\n \tThis option is only valid for status and summary commands. These\n@@ -302,7 +328,7 @@ the submodule itself.\n \tCheckout the commit recorded in the superproject on a detached HEAD\n \tin the submodule. This is the default behavior, the main use of\n \tthis option is to override `submodule.$name.update` when set to\n-\t`merge`, `rebase` or `none`.\n+\ta value other than `checkout`.\n \tIf the key `submodule.$name.update` is either not explicitly set or\n \tset to `checkout`, this option is implicit.\n \ndiff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt\nindex f6c0dfd..7e8fb87 100644\n--- a/Documentation/gitmodules.txt\n+++ b/Documentation/gitmodules.txt\n@@ -38,18 +38,15 @@ submodule..url::\n In addition, there are a number of optional keys:\n \n submodule..update::\n-\tDefines what to do when the submodule is updated by the superproject.\n-\tIf 'checkout' (the default), the new commit specified in the\n-\tsuperproject will be checked out in the submodule on a detached HEAD.\n-\tIf 'rebase', the current branch of the submodule will be rebased onto\n-\tthe commit specified in the superproject. If 'merge', the commit\n-\tspecified in the superproject will be merged into the current branch\n-\tin the submodule.\n-\tIf 'none', the submodule with name `$name` will not be updated\n-\tby default.\n-\n-\tThis config option is overridden if 'git submodule update' is given\n-\tthe '--merge', '--rebase' or '--checkout' options.\n+\tDefines the default update method 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 submodule..branch::\n \tA remote branch name for tracking updates in the upstream submodule.\n-- \n2.1.4\n"},{"id":"256541","messageId":"xmqqvbiss7xb.fsf@gitster.dls.corp.google.com","threadId":"37868","inReplyTo":"1424698360-10952-1-git-send-email-sojkam1@fel.cvut.cz","subject":"Re: [PATCH] submodule: Improve documentation of update subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-02-23T20:13:20Z","receivedAt":"2015-02-23T20:13:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michal Sojka writes:\n\n> The documentation of 'git submodule update' has several problems:\n\nThanks, this round looks much better.\n\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index ae6791d..fb2ae37 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -2411,12 +2411,17 @@ status.submodulesummary::\n> \n> submodule..path::\n> submodule..url::\n> +\tThe path within this project and URL for a submodule. These\n> +\tvariables are initially populated by 'git submodule init';\n> +\tedit them to override the URL and other values found in the\n> +\t`.gitmodules` file. See linkgit:git-submodule[1] and\n> +\tlinkgit:gitmodules[5] for details.\n> +\n\nThe sentence \"edit them to override\" talks about \"other values\",\nwhich in the original wanted to cover not just \"path\" but \"update\"\nas well. By splitting 'update' into its own entry, \"edit them to\noverride\" is lost from 'update'.\n\nBut stepping back a bit, \"edit them to override\" applies to all\nconfiguration variables. The user edits the configuration file to\ncustomize things. I wonder if we even need to say this for .path\nand url in the first place?\n\n Note: not a request to remove it because I hinted so, but a\n request for comments and discussion, as I do not have a firm\n opinion.\n\n> submodule..update::\n> -\tThe path within this project, URL, and the updating strategy\n> -\tfor a submodule. These variables are initially populated\n> -\tby 'git submodule init'; edit them to override the\n> -\tURL and other values found in the `.gitmodules` file. See\n> -\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n> +\tThe default updating strategy 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\n\n\n\n> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n> index 8e6af65..067d616 100644\n> --- a/Documentation/git-submodule.txt\n> +++ b/Documentation/git-submodule.txt\n> @@ -154,27 +154,51 @@ If `--force` is specified, the submodule's work tree will be removed even if\n> it contains local modifications.\n> \n> update::\n> -\tUpdate the registered submodules, i.e. clone missing submodules and\n> -\tcheckout the commit specified in the index of the containing repository.\n> -\tThis will make the submodules HEAD be detached unless `--rebase` or\n> -\t`--merge` is specified or the key `submodule.$name.update` is set to\n> -\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n> -\t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n> -\twill cause `command` to be run. `command` can be any arbitrary shell\n> -\tcommand that takes a single argument, namely the sha1 to update to.\n> +\n> +--\n> +Update the registered submodules to match what the superproject\n> +expects by cloning missing 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. Supported update methods are:\n\nIf you read the description of \"--remote\" (sorry, I didn't notice it\nuntil I formatted the result of this patch and tried to read the\nwhole thing), we already use \"update procedure\" to mean these modes\nof updates collectively. Either use \"update procedures\" here (and\neverywhere else in this patch where it is called \"update method\"),\nor adjust the existing \"update procedure\" to \"update method\".\nEither way is fine, but because \"update procedure\" is not wrong\nper-se, I think it would be better to use that phrasing that may\nalready be familiar with the \"git submodule\" users.\n"},{"id":"256543","messageId":"xmqqr3tgs7cf.fsf@gitster.dls.corp.google.com","threadId":"37868","inReplyTo":"xmqqvbiss7xb.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] submodule: Improve documentation of update subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-02-23T20:25:52Z","receivedAt":"2015-02-23T20:25:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n>> +Update the registered submodules to match what the superproject\n>> +expects by cloning missing 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. Supported update methods are:\n>\n> If you read the description of \"--remote\" (sorry, I didn't notice it\n> until I formatted the result of this patch and tried to read the\n> whole thing), we already use \"update procedure\" to mean these modes\n> of updates collectively. Either use \"update procedures\" here (and\n> everywhere else in this patch where it is called \"update method\"),\n> or adjust the existing \"update procedure\" to \"update method\".\n> Either way is fine, but because \"update procedure\" is not wrong\n> per-se, I think it would be better to use that phrasing that may\n> already be familiar with the \"git submodule\" users.\n\nAddendum. Your update to config.txt calls it \"updating strategy\".\nThat also needs to be unified to clarify that we are talking about\nthe same thing in these places to the readers.\n\nThanks.\n"},{"id":"256872","messageId":"87k2yzrpm8.fsf@steelpick.2x.cz","threadId":"37868","inReplyTo":"xmqqvbiss7xb.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] submodule: Improve documentation of update subcommand","fromName":"Michal Sojka","fromEmail":"sojkam1@fel.cvut.cz","sentAt":"2015-03-02T22:39:11Z","receivedAt":"2015-03-02T22:39:11Z","isPatch":true,"sender":{"key":"sojkam1@fel.cvut.cz","avatar":"https://avatars.githubusercontent.com/u/140542?v=4"},"body":"On Mon, Feb 23 2015, Junio C Hamano wrote:\n> Michal Sojka writes:\n>\n>> The documentation of 'git submodule update' has several problems:\n>\n> Thanks, this round looks much better.\n>\n>> diff --git a/Documentation/config.txt b/Documentation/config.txt\n>> index ae6791d..fb2ae37 100644\n>> --- a/Documentation/config.txt\n>> +++ b/Documentation/config.txt\n>> @@ -2411,12 +2411,17 @@ status.submodulesummary::\n>> \n>> submodule..path::\n>> submodule..url::\n>> +\tThe path within this project and URL for a submodule. These\n>> +\tvariables are initially populated by 'git submodule init';\n>> +\tedit them to override the URL and other values found in the\n>> +\t`.gitmodules` file. See linkgit:git-submodule[1] and\n>> +\tlinkgit:gitmodules[5] for details.\n>> +\n>\n> The sentence \"edit them to override\" talks about \"other values\",\n> which in the original wanted to cover not just \"path\" but \"update\"\n> as well. By splitting 'update' into its own entry, \"edit them to\n> override\" is lost from 'update'.\n>\n> But stepping back a bit, \"edit them to override\" applies to all\n> configuration variables. The user edits the configuration file to\n> customize things. I wonder if we even need to say this for .path\n> and url in the first place?\n>\n> Note: not a request to remove it because I hinted so, but a\n> request for comments and discussion, as I do not have a firm\n> opinion.\n\nI also thing that \"edit them to override\" is kind of useless here so I\nremoved it.\n\n>\n>> submodule..update::\n>> -\tThe path within this project, URL, and the updating strategy\n>> -\tfor a submodule. These variables are initially populated\n>> -\tby 'git submodule init'; edit them to override the\n>> -\tURL and other values found in the `.gitmodules` file. See\n>> -\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n>> +\tThe default updating strategy 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>\n>\n>\n>\n>> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\n>> index 8e6af65..067d616 100644\n>> --- a/Documentation/git-submodule.txt\n>> +++ b/Documentation/git-submodule.txt\n>> @@ -154,27 +154,51 @@ If `--force` is specified, the submodule's work tree will be removed even if\n>> it contains local modifications.\n>> \n>> update::\n>> -\tUpdate the registered submodules, i.e. clone missing submodules and\n>> -\tcheckout the commit specified in the index of the containing repository.\n>> -\tThis will make the submodules HEAD be detached unless `--rebase` or\n>> -\t`--merge` is specified or the key `submodule.$name.update` is set to\n>> -\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n>> -\t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n>> -\twill cause `command` to be run. `command` can be any arbitrary shell\n>> -\tcommand that takes a single argument, namely the sha1 to update to.\n>> +\n>> +--\n>> +Update the registered submodules to match what the superproject\n>> +expects by cloning missing 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. Supported update methods are:\n>\n> If you read the description of \"--remote\" (sorry, I didn't notice it\n> until I formatted the result of this patch and tried to read the\n> whole thing), we already use \"update procedure\" to mean these modes\n> of updates collectively. Either use \"update procedures\" here (and\n> everywhere else in this patch where it is called \"update method\"),\n> or adjust the existing \"update procedure\" to \"update method\".\n> Either way is fine, but because \"update procedure\" is not wrong\n> per-se, I think it would be better to use that phrasing that may\n> already be familiar with the \"git submodule\" users.\n\nOK, I replaced the method (and strategy in config.txt) with procedure.\n\nIn the previous version was also a typo, which is fixed now. v5 will\nfollow shortly.\n\nThanks.\n-Michal\n"},{"id":"256873","messageId":"1425336139-22566-1-git-send-email-sojkam1@fel.cvut.cz","threadId":"37868","inReplyTo":"87k2yzrpm8.fsf@steelpick.2x.cz","subject":"[PATCH v5] submodule: Improve documentation of update subcommand","fromName":"Michal Sojka","fromEmail":"sojkam1@fel.cvut.cz","sentAt":"2015-03-02T22:42:19Z","receivedAt":"2015-03-02T22:42:19Z","isPatch":true,"sender":{"key":"sojkam1@fel.cvut.cz","avatar":"https://avatars.githubusercontent.com/u/140542?v=4"},"body":"The documentation of 'git submodule update' has several problems:\n\n1) It mentions that value 'none' of submodule.$name.update can be\n overridden by --checkout, but other combinations of configuration\n values and command line options are not mentioned.\n\n2) The documentation of submodule.$name.update is scattered across three\n places, which is confusing.\n\n3) The documentation of submodule.$name.update in gitmodules.txt is\n incorrect, because the code always uses the value from .git/config\n and never from .gitmodules.\n\n4) Documentation of --force was incomplete, because it is only effective\n in case of checkout method of update.\n\nFix all these problems by documenting submodule.*.update in\ngit-submodule.txt and make everybody else refer to it.\n\nHelped-by: Junio C Hamano \nHelped-by: Jens Lehmann \nSigned-off-by: Michal Sojka \n---\n Documentation/config.txt | 15 ++++++----\n Documentation/git-submodule.txt | 66 ++++++++++++++++++++++++++++-------------\n Documentation/gitmodules.txt | 21 ++++++-------\n 3 files changed, 65 insertions(+), 37 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex ae6791d..fb2ae37 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -2411,12 +2411,17 @@ status.submodulesummary::\n \n submodule..path::\n submodule..url::\n+\tThe path within this project and URL for a submodule. These\n+\tvariables are initially populated by 'git submodule init';\n+\tedit them to override the URL and other values found in the\n+\t`.gitmodules` file. See linkgit:git-submodule[1] and\n+\tlinkgit:gitmodules[5] for details.\n+\n submodule..update::\n-\tThe path within this project, URL, and the updating strategy\n-\tfor a submodule. These variables are initially populated\n-\tby 'git submodule init'; edit them to override the\n-\tURL and other values found in the `.gitmodules` file. See\n-\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\n+\tThe default updating strategy 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 \n submodule..branch::\n \tThe remote branch name for a submodule, used by `git submodule\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 8e6af65..067d616 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -154,27 +154,51 @@ If `--force` is specified, the submodule's work tree will be removed even if\n it contains local modifications.\n \n update::\n-\tUpdate the registered submodules, i.e. clone missing submodules and\n-\tcheckout the commit specified in the index of the containing repository.\n-\tThis will make the submodules HEAD be detached unless `--rebase` or\n-\t`--merge` is specified or the key `submodule.$name.update` is set to\n-\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n-\t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n-\twill cause `command` to be run. `command` can be any arbitrary shell\n-\tcommand that takes a single argument, namely the sha1 to update to.\n +\n+--\n+Update the registered submodules to match what the superproject\n+expects by cloning missing 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. Supported update methods are:\n+\n+\tcheckout;; the commit recorded in the superproject will be\n+\t checked out in the submodule on a detached HEAD. This is\n+\t done when `--checkout` option is given, or no option is\n+\t given, and `submodule..update` is unset, or if it is\n+\t set to 'checkout'.\n++\n+If `--force` is specified, the submodule will be checked out (using\n+`git checkout --force` if appropriate), even if the commit specified\n+in the index of the containing repository already matches the commit\n+checked out in the submodule.\n+\n+\trebase;; the current branch of the submodule will be rebased\n+\t onto the commit recoded in the superproject. This is done\n+\t when `--rebase` option is given, or no option is given, and\n+\t `submodule..update` is set to 'rebase'.\n+\n+\tmerge;; the commit recorded in the superproject will be merged\n+\t into the current branch in the submodule. This is done\n+\t when `--merge` option is given, or no option is given, and\n+\t `submodule..update` is set to 'merge'.\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. This is done when no option is\n+\t given, and `submodule..update` has the form of\n+\t '!command'.\n+\n+When no option is given and `submodule..update` is set to 'none',\n+the submodule is not updated.\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-+\n+\n If `--recursive` is specified, this command will recurse into the\n registered submodules, and update any nested submodules within.\n-+\n-If `--force` is specified, the submodule will be checked out (using\n-`git checkout --force` if appropriate), even if the commit specified in the\n-index of the containing repository already matches the commit checked out in\n-the submodule.\n-\n+--\n summary::\n \tShow commit summary between the given commit (defaults to HEAD) and\n \tworking tree/index. For a submodule in question, a series of commits\n@@ -238,10 +262,12 @@ OPTIONS\n \tWhen running add, allow adding an otherwise ignored submodule path.\n \tWhen running deinit the submodule work trees will be removed even if\n \tthey contain local changes.\n-\tWhen running update, throw away local changes in submodules when\n-\tswitching to a different commit; and always run a checkout operation\n-\tin the submodule, even if the commit listed in the index of the\n-\tcontaining repository matches the commit checked out in the submodule.\n+\tWhen running update (only effective with the checkout method),\n+\tthrow away local changes in submodules when switching to a\n+\tdifferent commit; and always run a checkout operation in the\n+\tsubmodule, even if the commit listed in the index of the\n+\tcontaining repository matches the commit checked out in the\n+\tsubmodule.\n \n --cached::\n \tThis option is only valid for status and summary commands. These\n@@ -302,7 +328,7 @@ the submodule itself.\n \tCheckout the commit recorded in the superproject on a detached HEAD\n \tin the submodule. This is the default behavior, the main use of\n \tthis option is to override `submodule.$name.update` when set to\n-\t`merge`, `rebase` or `none`.\n+\ta value other than `checkout`.\n \tIf the key `submodule.$name.update` is either not explicitly set or\n \tset to `checkout`, this option is implicit.\n \ndiff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt\nindex f6c0dfd..7e8fb87 100644\n--- a/Documentation/gitmodules.txt\n+++ b/Documentation/gitmodules.txt\n@@ -38,18 +38,15 @@ submodule..url::\n In addition, there are a number of optional keys:\n \n submodule..update::\n-\tDefines what to do when the submodule is updated by the superproject.\n-\tIf 'checkout' (the default), the new commit specified in the\n-\tsuperproject will be checked out in the submodule on a detached HEAD.\n-\tIf 'rebase', the current branch of the submodule will be rebased onto\n-\tthe commit specified in the superproject. If 'merge', the commit\n-\tspecified in the superproject will be merged into the current branch\n-\tin the submodule.\n-\tIf 'none', the submodule with name `$name` will not be updated\n-\tby default.\n-\n-\tThis config option is overridden if 'git submodule update' is given\n-\tthe '--merge', '--rebase' or '--checkout' options.\n+\tDefines the default update method 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 submodule..branch::\n \tA remote branch name for tracking updates in the upstream submodule.\n-- \n2.1.4\n"},{"id":"256874","messageId":"1425337078-24154-1-git-send-email-sojkam1@fel.cvut.cz","threadId":"37868","inReplyTo":"87k2yzrpm8.fsf@steelpick.2x.cz","subject":"[PATCH v6] submodule: Improve documentation of update subcommand","fromName":"Michal Sojka","fromEmail":"sojkam1@fel.cvut.cz","sentAt":"2015-03-02T22:57:58Z","receivedAt":"2015-03-02T22:57:58Z","isPatch":true,"sender":{"key":"sojkam1@fel.cvut.cz","avatar":"https://avatars.githubusercontent.com/u/140542?v=4"},"body":"The documentation of 'git submodule update' has several problems:\n\n1) It mentions that value 'none' of submodule.$name.update can be\n overridden by --checkout, but other combinations of configuration\n values and command line options are not mentioned.\n\n2) The documentation of submodule.$name.update is scattered across three\n places, which is confusing.\n\n3) The documentation of submodule.$name.update in gitmodules.txt is\n incorrect, because the code always uses the value from .git/config\n and never from .gitmodules.\n\n4) Documentation of --force was incomplete, because it is only effective\n in case of checkout method of update.\n\nFix all these problems by documenting submodule.*.update in\ngit-submodule.txt and make everybody else refer to it.\n\nHelped-by: Junio C Hamano \nHelped-by: Jens Lehmann \nSigned-off-by: Michal Sojka \n---\n Documentation/config.txt | 14 +++++----\n Documentation/git-submodule.txt | 66 ++++++++++++++++++++++++++++-------------\n Documentation/gitmodules.txt | 21 ++++++-------\n 3 files changed, 64 insertions(+), 37 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex ae6791d..0a6852d 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -2411,12 +2411,16 @@ status.submodulesummary::\n \n submodule..path::\n submodule..url::\n+\tThe path within this project and URL for a submodule. These\n+\tvariables are initially populated by 'git submodule init'. See\n+\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for\n+\tdetails.\n+\n submodule..update::\n-\tThe path within this project, URL, and the updating strategy\n-\tfor a submodule. These variables are initially populated\n-\tby 'git submodule init'; edit them to override the\n-\tURL and other values found in the `.gitmodules` file. See\n-\tlinkgit:git-submodule[1] and linkgit:gitmodules[5] for details.\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 \n submodule..branch::\n \tThe remote branch name for a submodule, used by `git submodule\ndiff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt\nindex 8e6af65..2c25916 100644\n--- a/Documentation/git-submodule.txt\n+++ b/Documentation/git-submodule.txt\n@@ -154,27 +154,51 @@ If `--force` is specified, the submodule's work tree will be removed even if\n it contains local modifications.\n \n update::\n-\tUpdate the registered submodules, i.e. clone missing submodules and\n-\tcheckout the commit specified in the index of the containing repository.\n-\tThis will make the submodules HEAD be detached unless `--rebase` or\n-\t`--merge` is specified or the key `submodule.$name.update` is set to\n-\t`rebase`, `merge` or `none`. `none` can be overridden by specifying\n-\t`--checkout`. Setting the key `submodule.$name.update` to `!command`\n-\twill cause `command` to be run. `command` can be any arbitrary shell\n-\tcommand that takes a single argument, namely the sha1 to update to.\n +\n+--\n+Update the registered submodules to match what the superproject\n+expects by cloning missing 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. Supported update procedures are:\n+\n+\tcheckout;; the commit recorded in the superproject will be\n+\t checked out in the submodule on a detached HEAD. This is\n+\t done when `--checkout` option is given, or no option is\n+\t given, and `submodule..update` is unset, or if it is\n+\t set to 'checkout'.\n++\n+If `--force` is specified, the submodule will be checked out (using\n+`git checkout --force` if appropriate), even if the commit specified\n+in the index of the containing repository already matches the commit\n+checked out in the submodule.\n+\n+\trebase;; the current branch of the submodule will be rebased\n+\t onto the commit recorded in the superproject. This is done\n+\t when `--rebase` option is given, or no option is given, and\n+\t `submodule..update` is set to 'rebase'.\n+\n+\tmerge;; the commit recorded in the superproject will be merged\n+\t into the current branch in the submodule. This is done\n+\t when `--merge` option is given, or no option is given, and\n+\t `submodule..update` is set to 'merge'.\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. This is done when no option is\n+\t given, and `submodule..update` has the form of\n+\t '!command'.\n+\n+When no option is given and `submodule..update` is set to 'none',\n+the submodule is not updated.\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-+\n+\n If `--recursive` is specified, this command will recurse into the\n registered submodules, and update any nested submodules within.\n-+\n-If `--force` is specified, the submodule will be checked out (using\n-`git checkout --force` if appropriate), even if the commit specified in the\n-index of the containing repository already matches the commit checked out in\n-the submodule.\n-\n+--\n summary::\n \tShow commit summary between the given commit (defaults to HEAD) and\n \tworking tree/index. For a submodule in question, a series of commits\n@@ -238,10 +262,12 @@ OPTIONS\n \tWhen running add, allow adding an otherwise ignored submodule path.\n \tWhen running deinit the submodule work trees will be removed even if\n \tthey contain local changes.\n-\tWhen running update, throw away local changes in submodules when\n-\tswitching to a different commit; and always run a checkout operation\n-\tin the submodule, even if the commit listed in the index of the\n-\tcontaining repository matches the commit checked out in the submodule.\n+\tWhen running update (only effective with the checkout procedure),\n+\tthrow away local changes in submodules when switching to a\n+\tdifferent commit; and always run a checkout operation in the\n+\tsubmodule, even if the commit listed in the index of the\n+\tcontaining repository matches the commit checked out in the\n+\tsubmodule.\n \n --cached::\n \tThis option is only valid for status and summary commands. These\n@@ -302,7 +328,7 @@ the submodule itself.\n \tCheckout the commit recorded in the superproject on a detached HEAD\n \tin the submodule. This is the default behavior, the main use of\n \tthis option is to override `submodule.$name.update` when set to\n-\t`merge`, `rebase` or `none`.\n+\ta value other than `checkout`.\n \tIf the key `submodule.$name.update` is either not explicitly set or\n \tset to `checkout`, this option is implicit.\n \ndiff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt\nindex f6c0dfd..ac70eca 100644\n--- a/Documentation/gitmodules.txt\n+++ b/Documentation/gitmodules.txt\n@@ -38,18 +38,15 @@ submodule..url::\n In addition, there are a number of optional keys:\n \n submodule..update::\n-\tDefines what to do when the submodule is updated by the superproject.\n-\tIf 'checkout' (the default), the new commit specified in the\n-\tsuperproject will be checked out in the submodule on a detached HEAD.\n-\tIf 'rebase', the current branch of the submodule will be rebased onto\n-\tthe commit specified in the superproject. If 'merge', the commit\n-\tspecified in the superproject will be merged into the current branch\n-\tin the submodule.\n-\tIf 'none', the submodule with name `$name` will not be updated\n-\tby default.\n-\n-\tThis config option is overridden if 'git submodule update' is given\n-\tthe '--merge', '--rebase' or '--checkout' options.\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 submodule..branch::\n \tA remote branch name for tracking updates in the upstream submodule.\n-- \n2.1.4\n"},{"id":"256875","messageId":"xmqq385n9f0h.fsf@gitster.dls.corp.google.com","threadId":"37868","inReplyTo":"1425337078-24154-1-git-send-email-sojkam1@fel.cvut.cz","subject":"Re: [PATCH v6] submodule: Improve documentation of update subcommand","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-03-02T23:05:34Z","receivedAt":"2015-03-02T23:05:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thanks, will queue. I think this round should be ready for 'next'.\n"}]}