{"thread":{"id":"52903","subject":"[PATCH 0/4] doc: --recurse-submodules","startedAt":"2020-02-28T10:37:23Z","lastAt":"2020-04-06T18:42:33Z","messageCount":62,"participants":["Damien Robert","Philippe Blain","Junio C Hamano","Robert P. J. Day"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"392654","messageId":"20200228103558.1684937-1-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":null,"subject":"[PATCH 0/4] doc: --recurse-submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-02-28T10:35:54Z","receivedAt":"2020-02-28T10:37:23Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"This series add some extra documentation on --recurse-submodules.\n\nDamien Robert (4):\n doc: list all commands affected by recurse.submodule\n doc: document --recurse-submodules for reset and restore\n doc: explain how to deactivate recurse.submodule completely\n doc: be more precise on (fetch|pull).recurseSubmodules\n\n Documentation/config/fetch.txt | 6 ++++--\n Documentation/config/push.txt | 3 +++\n Documentation/config/submodule.txt | 11 +++++++++--\n Documentation/git-reset.txt | 6 ++++++\n Documentation/git-restore.txt | 9 +++++++++\n 5 files changed, 31 insertions(+), 4 deletions(-)\n\n-- \nPatched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n\n"},{"id":"392655","messageId":"20200228103558.1684937-2-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200228103558.1684937-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH 1/4] doc: list all commands affected by recurse.submodule","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-02-28T10:35:55Z","receivedAt":"2020-02-28T10:37:24Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Note that `ls-files` is not affected, even though it has a\n`--recurse-submodules` option, so list it as an exception too.\n\nSigned-off-by: Damien Robert \n---\n Documentation/config/submodule.txt | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\nindex b33177151c..5962f41ead 100644\n--- a/Documentation/config/submodule.txt\n+++ b/Documentation/config/submodule.txt\n@@ -59,8 +59,9 @@ submodule.active::\n \n submodule.recurse::\n \tSpecifies if commands recurse into submodules by default. This\n-\tapplies to all commands that have a `--recurse-submodules` option,\n-\texcept `clone`.\n+\tapplies to all commands that have a `--recurse-submodules` option\n+\t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n+\t`restore` and `switch`) except `clone` and `ls-files`.\n \tDefaults to false.\n \n submodule.fetchJobs::\n-- \nPatched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n\n"},{"id":"392656","messageId":"20200228103558.1684937-3-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200228103558.1684937-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH 2/4] doc: document --recurse-submodules for reset and restore","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-02-28T10:35:56Z","receivedAt":"2020-02-28T10:37:25Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Signed-off-by: Damien Robert \n---\n Documentation/git-reset.txt | 6 ++++++\n Documentation/git-restore.txt | 9 +++++++++\n 2 files changed, 15 insertions(+)\n\ndiff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\nindex 932080c55d..838c0f1101 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -87,6 +87,12 @@ but carries forward unmerged index entries.\n \tdifferent between `` and `HEAD`.\n \tIf a file that is different between `` and `HEAD` has local\n \tchanges, reset is aborted.\n+\n+--[no-]recurse-submodules::\n+\tWhen the working tree is updated, using --recurse-submodules will\n+\talso recursively reset the content of all active submodules\n+\taccording to the commit recorded in the superproject, also setting\n+\tthe submodules HEAD to be detached at that commit.\n --\n \n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\ndiff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt\nindex 5bf60d4943..b94b2559c7 100644\n--- a/Documentation/git-restore.txt\n+++ b/Documentation/git-restore.txt\n@@ -107,6 +107,15 @@ in linkgit:git-checkout[1] for details.\n \tpatterns and unconditionally restores any files in\n \t``.\n \n+--recurse-submodules::\n+--no-recurse-submodules::\n+\tUsing `--recurse-submodules` will update the content of all\n+\trestored submodules according to the commit recorded in the\n+\tsuperproject. Local modifications in a restored submodule are\n+\toverwritten. If nothing (or `--no-recurse-submodules`) is used, the\n+\twork trees of submodules will not be updated. Just like\n+\tlinkgit:git-submodule[1], this will detach `HEAD` of the submodule.\n+\n --overlay::\n --no-overlay::\n \tIn overlay mode, the command never removes files when\n-- \nPatched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n\n"},{"id":"392657","messageId":"20200228103558.1684937-4-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200228103558.1684937-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH 3/4] doc: explain how to deactivate recurse.submodule completely","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-02-28T10:35:57Z","receivedAt":"2020-02-28T10:37:25Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Signed-off-by: Damien Robert \n---\n Documentation/config/submodule.txt | 6 ++++++\n 1 file changed, 6 insertions(+)\n\ndiff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\nindex 5962f41ead..f4edc6cad0 100644\n--- a/Documentation/config/submodule.txt\n+++ b/Documentation/config/submodule.txt\n@@ -62,6 +62,12 @@ submodule.recurse::\n \tapplies to all commands that have a `--recurse-submodules` option\n \t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n \t`restore` and `switch`) except `clone` and `ls-files`.\n+\tWhen set to true, it can be deactivated by calling\n+\t`--no-recurse-submodules`. But note that since `submodule.recurse`\n+\talso applies to internal calls to git commands (issued by other git\n+\tcommands), adding `--no-recurse-submodules` might not be enough to\n+\tcompletely turn off the effect of that config. A solution is to use\n+\t`git -c submodule.recurse=0` instead.\n \tDefaults to false.\n \n submodule.fetchJobs::\n-- \nPatched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n\n"},{"id":"392658","messageId":"20200228103558.1684937-5-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200228103558.1684937-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH 4/4] doc: be more precise on (fetch|pull).recurseSubmodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-02-28T10:35:58Z","receivedAt":"2020-02-28T10:37:29Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"The default value also depends on the value of submodule.recurse\n\nSigned-off-by: Damien Robert \n---\n Documentation/config/fetch.txt | 6 ++++--\n Documentation/config/push.txt | 3 +++\n 2 files changed, 7 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt\nindex f11940280f..8f716809f9 100644\n--- a/Documentation/config/fetch.txt\n+++ b/Documentation/config/fetch.txt\n@@ -2,10 +2,12 @@ fetch.recurseSubmodules::\n \tThis option can be either set to a boolean value or to 'on-demand'.\n \tSetting it to a boolean changes the behavior of fetch and pull to\n \tunconditionally recurse into submodules when set to true or to not\n-\trecurse at all when set to false. When set to 'on-demand' (the default\n-\tvalue), fetch and pull will only recurse into a populated submodule\n+\trecurse at all when set to false. When set to 'on-demand', \n+\tfetch and pull will only recurse into a populated submodule\n \twhen its superproject retrieves a commit that updates the submodule's\n \treference.\n+\tIf not set, it fallbacks to the value of `submodule.recurse`, and\n+\tif both are not set the default value is 'on-demand'.\n \n fetch.fsckObjects::\n \tIf it is set to true, git-fetch-pack will check all fetched\ndiff --git a/Documentation/config/push.txt b/Documentation/config/push.txt\nindex 54871f8213..2a5250cf5c 100644\n--- a/Documentation/config/push.txt\n+++ b/Documentation/config/push.txt\n@@ -112,3 +112,6 @@ push.recurseSubmodules::\n \tis 'no' then default behavior of ignoring submodules when pushing\n \tis retained. You may override this configuration at time of push by\n \tspecifying '--recurse-submodules=check|on-demand|no'.\n+\tIf not set, it fallbacks to the value of `submodule.recurse` (where\n+\ta 'true' value means 'on-demand'), and if both are not set the\n+\tdefault value is 'no'.\n-- \nPatched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n\n"},{"id":"392659","messageId":"20200228104449.o42twhy34fynalk4@feanor","threadId":"52903","inReplyTo":"20200228103558.1684937-1-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH 0/4] doc: --recurse-submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-02-28T10:44:49Z","receivedAt":"2020-02-28T10:44:54Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Note that git-switch.txt states that\n\tUsing `--recurse-submodules` will update the content of all\n\tinitialized submodules according to the commit recorded in the\n\tsuperproject.\nbut actually only 'active' submodules will be updated.\n\nShould I also update the doc? It is already stated in `gitsubmodules(7)`\nthat only 'active' submodules are considered for recursion.\n\n-- \nDamien Robert\nhttp://www.normalesup.org/~robert/pro\n"},{"id":"392733","messageId":"6C13DF7D-2999-4C91-882F-B899CEBD7C29@gmail.com","threadId":"52903","inReplyTo":"20200228103558.1684937-2-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH 1/4] doc: list all commands affected by recurse.submodule","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-02T04:43:35Z","receivedAt":"2020-03-02T04:43:45Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"HI Damien,\n\nThe commit title has the option name reversed: it’s submodule.recurse and not recurse.submodule\n\n> Le 28 févr. 2020 à 05:35, Damien Robert a écrit :\n> \n> Note that `ls-files` is not affected, even though it has a\n> `--recurse-submodules` option, so list it as an exception too.\n\nGood find.\n\n> \n> Signed-off-by: Damien Robert \n> ---\n> Documentation/config/submodule.txt | 5 +++--\n> 1 file changed, 3 insertions(+), 2 deletions(-)\n\nI’d also add the same list to the \"Implementation details\" section of the gitsubmodules guide [1], which just mentions `checkout`\nat the moment.\n\n[1] https://git-scm.com/docs/gitsubmodules#_implementation_details\n\n> \n> diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\n> index b33177151c..5962f41ead 100644\n> --- a/Documentation/config/submodule.txt\n> +++ b/Documentation/config/submodule.txt\n> @@ -59,8 +59,9 @@ submodule.active::\n> \n> submodule.recurse::\n> \tSpecifies if commands recurse into submodules by default. This\n> -\tapplies to all commands that have a `--recurse-submodules` option,\n> -\texcept `clone`.\n> +\tapplies to all commands that have a `--recurse-submodules` option\n> +\t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n> +\t`restore` and `switch`) except `clone` and `ls-files`.\n> \tDefaults to false.\n> \n> submodule.fetchJobs::\n> -- \n> Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n> \n\n"},{"id":"392734","messageId":"9831AAEE-8FBF-4CBD-B589-3F045720D6DC@gmail.com","threadId":"52903","inReplyTo":"20200228103558.1684937-3-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH 2/4] doc: document --recurse-submodules for reset and restore","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-02T04:45:02Z","receivedAt":"2020-03-02T04:45:07Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 28 févr. 2020 à 05:35, Damien Robert a écrit :\n> \n> Signed-off-by: Damien Robert \n> ---\n> Documentation/git-reset.txt | 6 ++++++\n> Documentation/git-restore.txt | 9 +++++++++\n> 2 files changed, 15 insertions(+)\n> \n> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\n> index 932080c55d..838c0f1101 100644\n> --- a/Documentation/git-reset.txt\n> +++ b/Documentation/git-reset.txt\n> @@ -87,6 +87,12 @@ but carries forward unmerged index entries.\n> \tdifferent between `` and `HEAD`.\n> \tIf a file that is different between `` and `HEAD` has local\n> \tchanges, reset is aborted.\n> +\n> +--[no-]recurse-submodules::\n> +\tWhen the working tree is updated, using --recurse-submodules will\n> +\talso recursively reset the content of all active submodules\n> +\taccording to the commit recorded in the superproject, also setting\n> +\tthe submodules HEAD to be detached at that commit.\n> —\n\nFrom previous testing I had done, when the submodule is modified (either modified content, \nnew commits or new commits, staged) and `git reset` is invoked (and so `git reset HEAD` is assumed),\nthe submodule is only touched if `--hard` or `--merge` is given, \ni.e. not when `--soft`, `--mixed` (the default action) or `--keep` are given.\nSo this is in line with this option just coming into play \"When the working tree is updated\", as you wrote.\nHowever I just noticed that according to the doc `--merge` should abort in that case (I think?), but it does not if \n`--recurse-submodules` is given. I don’t know if it’s a doc oversight or a real bug though...\n\n> \n> See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n> diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt\n> index 5bf60d4943..b94b2559c7 100644\n> --- a/Documentation/git-restore.txt\n> +++ b/Documentation/git-restore.txt\n> @@ -107,6 +107,15 @@ in linkgit:git-checkout[1] for details.\n> \tpatterns and unconditionally restores any files in\n> \t``.\n> \n> +--recurse-submodules::\n> +--no-recurse-submodules::\n> +\tUsing `--recurse-submodules` will update the content of all\n> +\trestored submodules according to the commit recorded in the\n> +\tsuperproject.\n\nI’d phrase it more like so :\nIf `` names a submodule and the restore location includes the working tree, \nthe submodule will only be updated if this option is given, \nin which case it’s working tree will be restored to the commit recorded in the superproject \nat the tree-ish given as the restore source.\n\nThis makes it clearer that `git restore -- submodule` does nothing, and one has to say\n`git restore --recurse-submodules -- submodule` for the submodule working tree to be updated.\n\n> Local modifications in a restored submodule are\n> +\toverwritten. If nothing (or `--no-recurse-submodules`) is used, the\n> +\twork trees of submodules will not be updated. Just like\n> +\tlinkgit:git-submodule[1], this will detach `HEAD` of the submodule.\n> +\n\nIn fact `git submodule` does not unconditionally detach the submodules HEAD \n(if `git submodule update` is invoked and a branch is checked out in the submodule that points\nto the same commit as the one recorded in the superproject, the HEAD is not detached and the branch\nstays checked out unless `--force` is given.) So I would instead link to `checkout`, \nwhich does unconditionally detach the submodules HEAD.\n\n> --overlay::\n> --no-overlay::\n> \tIn overlay mode, the command never removes files when\n> -- \n> Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n> \n\n"},{"id":"392735","messageId":"2442144D-A86E-4DD0-BA0B-ED02956820D0@gmail.com","threadId":"52903","inReplyTo":"20200228103558.1684937-4-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH 3/4] doc: explain how to deactivate recurse.submodule completely","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-02T04:45:45Z","receivedAt":"2020-03-02T04:45:48Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Again, the commit title has the option name backwards :\ns/recurse.submodule/submodule.recurse/\n\n> Le 28 févr. 2020 à 05:35, Damien Robert a écrit :\n> \n> Signed-off-by: Damien Robert \n\nI think the commit message for this one could be more detailed \n(even if it would say something very similar to the text added to the doc).\nI think it could be made clearer, for example, that the `-c submodule.recurse=0` is\nespecially useful to deactivate the config when calling commands that do *not* have a `--recurse-submodules` flag,\nbut that internally call other commands that do support that flag.\n\n> ---\n> Documentation/config/submodule.txt | 6 ++++++\n> 1 file changed, 6 insertions(+)\n> \n> diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\n> index 5962f41ead..f4edc6cad0 100644\n> --- a/Documentation/config/submodule.txt\n> +++ b/Documentation/config/submodule.txt\n> @@ -62,6 +62,12 @@ submodule.recurse::\n> \tapplies to all commands that have a `--recurse-submodules` option\n> \t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n> \t`restore` and `switch`) except `clone` and `ls-files`.\n> +\tWhen set to true, it can be deactivated by calling\n> +\t`--no-recurse-submodules`.\n\nI’d say \"can be deactivated for a specific call by adding --no-recurse-submodules.\"\n\n> But note that since `submodule.recurse`\n> +\talso applies to internal calls to git commands (issued by other git\n> +\tcommands),\n\nWe tend to capitalize \"Git\" when talking about the system as a whole.\n\n> adding `--no-recurse-submodules` might not be enough to\n> +\tcompletely turn off the effect of that config. A solution is to use\n> +\t`git -c submodule.recurse=0` instead.\n> \tDefaults to false.\n\nPersonally I’d let \"Defaults to false\" just after the list of affected commands.\n\n> \n> submodule.fetchJobs::\n> -- \n> Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n> \n\n"},{"id":"392736","messageId":"695F48BB-F9EE-43A4-8B12-CF331E5A941A@gmail.com","threadId":"52903","inReplyTo":"20200228103558.1684937-5-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH 4/4] doc: be more precise on (fetch|pull).recurseSubmodules","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-02T04:46:11Z","receivedAt":"2020-03-02T04:46:16Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"The commit message title mentions fetch and pull but the patch also talks about push, maybe add that to the title ?\n\n> Le 28 févr. 2020 à 05:35, Damien Robert a écrit :\n> \n> The default value also depends on the value of submodule.recurse\n> \n> Signed-off-by: Damien Robert \n> ---\n> Documentation/config/fetch.txt | 6 ++++--\n> Documentation/config/push.txt | 3 +++\n> 2 files changed, 7 insertions(+), 2 deletions(-)\n> \n> diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt\n> index f11940280f..8f716809f9 100644\n> --- a/Documentation/config/fetch.txt\n> +++ b/Documentation/config/fetch.txt\n> @@ -2,10 +2,12 @@ fetch.recurseSubmodules::\n> \tThis option can be either set to a boolean value or to 'on-demand'.\n> \tSetting it to a boolean changes the behavior of fetch and pull to\n> \tunconditionally recurse into submodules when set to true or to not\n> -\trecurse at all when set to false. When set to 'on-demand' (the default\n> -\tvalue), fetch and pull will only recurse into a populated submodule\n> +\trecurse at all when set to false. When set to 'on-demand', \n> +\tfetch and pull will only recurse into a populated submodule\n> \twhen its superproject retrieves a commit that updates the submodule's\n> \treference.\n> +\tIf not set, it fallbacks to the value of `submodule.recurse`, and\n> +\tif both are not set the default value is 'on-demand’.\n\nFor such a change to the doc, I’d expect the commit message to point \nto the relevant part of the code that supports the behaviour that is being described, \nor to the specific test that enforces this behaviour (I briefly looked at t5526 but couldn’t spot one).\nIf such a test is missing it would be good to add it.\n\n> \n> fetch.fsckObjects::\n> \tIf it is set to true, git-fetch-pack will check all fetched\n> diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt\n> index 54871f8213..2a5250cf5c 100644\n> --- a/Documentation/config/push.txt\n> +++ b/Documentation/config/push.txt\n> @@ -112,3 +112,6 @@ push.recurseSubmodules::\n> \tis 'no' then default behavior of ignoring submodules when pushing\n> \tis retained. You may override this configuration at time of push by\n> \tspecifying '--recurse-submodules=check|on-demand|no'.\n> +\tIf not set, it fallbacks to the value of `submodule.recurse` (where\n> +\ta 'true' value means 'on-demand'), and if both are not set the\n> +\tdefault value is 'no’.\n\nSame thing here. Also, I do not think it’s good UI that setting ‘submodule,recurse’ to true will make ‘push' default to ‘on-demand’ \nbut will make ‘fetch’ unconditionally fetch, but I guess that would be for another series...\n\n> -- \n> Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n> \n\n"},{"id":"392737","messageId":"1ECBCF2C-256F-453B-9503-7818D82F4C61@gmail.com","threadId":"52903","inReplyTo":"20200228103558.1684937-1-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH 0/4] doc: --recurse-submodules","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-02T04:47:03Z","receivedAt":"2020-03-02T04:47:06Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Damien,\n> Le 28 févr. 2020 à 05:35, Damien Robert a écrit :\n> \n> This series add some extra documentation on --recurse-submodules.\n> \n> Damien Robert (4):\n> doc: list all commands affected by recurse.submodule\n> doc: document --recurse-submodules for reset and restore\n> doc: explain how to deactivate recurse.submodule completely\n> doc: be more precise on (fetch|pull).recurseSubmodules\n> \n> Documentation/config/fetch.txt | 6 ++++--\n> Documentation/config/push.txt | 3 +++\n> Documentation/config/submodule.txt | 11 +++++++++--\n> Documentation/git-reset.txt | 6 ++++++\n> Documentation/git-restore.txt | 9 +++++++++\n> 5 files changed, 31 insertions(+), 4 deletions(-)\n\nThanks a lot for working on that!\n\nCheers,\nPhilippe.\n\n> \n> -- \n> Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n> \n\n"},{"id":"392772","messageId":"FF79EA85-4A15-4B4B-B59E-657E0488D4C6@gmail.com","threadId":"52903","inReplyTo":"20200228104449.o42twhy34fynalk4@feanor","subject":"Re: [PATCH 0/4] doc: --recurse-submodules","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-03T05:18:57Z","receivedAt":"2020-03-03T05:19:05Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 28 févr. 2020 à 05:44, Damien Robert a écrit :\n> \n> Note that git-switch.txt states that\n> \tUsing `--recurse-submodules` will update the content of all\n> \tinitialized submodules according to the commit recorded in the\n> \tsuperproject.\n> but actually only 'active' submodules will be updated.\n\nTechnically that’s true, but I’d say that in a \"simple\" workflow (you clone a superproject then do\n`git submodule update --init`, then maybe set `submodule.recurse` to true), then being active and \nbeing initialized are equivalent. So I don’t think it’s that big of an issue. \n\nIn any case, if such a change is made, the doc for\nall commands that have the flag should be revised, as both \"initialized\" (grep, checkout, switch, read-tree)\nand \"populated\" (fetch, pull) seems to be used currently.\n\n> \n> Should I also update the doc? It is already stated in `gitsubmodules(7)`\n> that only 'active' submodules are considered for recursion.\n> \n> -- \n> Damien Robert\n> http://www.normalesup.org/~robert/pro\n\n"},{"id":"392794","messageId":"20200303170740.1879432-2-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200303170740.1879432-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v2 1/5] doc: list all commands affected by submodule.recurse","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-03T17:07:36Z","receivedAt":"2020-03-03T17:08:29Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Note that `ls-files` is not affected, even though it has a\n`--recurse-submodules` option, so list it as an exception too.\n\nSigned-off-by: Damien Robert \n---\n Documentation/config/submodule.txt | 5 +++--\n Documentation/gitsubmodules.txt | 3 ++-\n 2 files changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\nindex b33177151c..5962f41ead 100644\n--- a/Documentation/config/submodule.txt\n+++ b/Documentation/config/submodule.txt\n@@ -59,8 +59,9 @@ submodule.active::\n \n submodule.recurse::\n \tSpecifies if commands recurse into submodules by default. This\n-\tapplies to all commands that have a `--recurse-submodules` option,\n-\texcept `clone`.\n+\tapplies to all commands that have a `--recurse-submodules` option\n+\t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n+\t`restore` and `switch`) except `clone` and `ls-files`.\n \tDefaults to false.\n \n submodule.fetchJobs::\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex c476f891b5..f9f4e65c9e 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse\n into submodules. The 'init' and 'update' subcommands of 'git submodule'\n will maintain submodules checked out and at an appropriate revision in\n your working tree. Alternatively you can set 'submodule.recurse' to have\n-'checkout' recursing into submodules.\n+'checkout' recursing into submodules (note that 'submodule.recurse' also\n+affects other git commands, see linkgit:git-config[1] for a complete list).\n \n \n SEE ALSO\n-- \nPatched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n\n"},{"id":"392795","messageId":"20200303170740.1879432-3-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200303170740.1879432-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v2 2/5] doc: document --recurse-submodules for reset and restore","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-03T17:07:37Z","receivedAt":"2020-03-03T17:08:29Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Signed-off-by: Damien Robert \n---\n Documentation/git-reset.txt | 6 ++++++\n Documentation/git-restore.txt | 10 ++++++++++\n 2 files changed, 16 insertions(+)\n\ndiff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\nindex 932080c55d..838c0f1101 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -87,6 +87,12 @@ but carries forward unmerged index entries.\n \tdifferent between `` and `HEAD`.\n \tIf a file that is different between `` and `HEAD` has local\n \tchanges, reset is aborted.\n+\n+--[no-]recurse-submodules::\n+\tWhen the working tree is updated, using --recurse-submodules will\n+\talso recursively reset the content of all active submodules\n+\taccording to the commit recorded in the superproject, also setting\n+\tthe submodules HEAD to be detached at that commit.\n --\n \n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\ndiff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt\nindex 5bf60d4943..5036f91132 100644\n--- a/Documentation/git-restore.txt\n+++ b/Documentation/git-restore.txt\n@@ -107,6 +107,16 @@ in linkgit:git-checkout[1] for details.\n \tpatterns and unconditionally restores any files in\n \t``.\n \n+--recurse-submodules::\n+--no-recurse-submodules::\n+\tIf `` names a submodule and the restore location includes\n+\tthe working tree, the submodule will only be updated if this option\n+\tis given, in which case it's working tree will be restored to the\n+\tcommit recorded in the superproject, and it's local modifications\n+\toverwritten. If nothing (or `--no-recurse-submodules`) is used,\n+\tthe work trees of submodules will not be updated. Just like\n+\tlinkgit:git-checkout[1], this will detach `HEAD` of the submodule.\n+\n --overlay::\n --no-overlay::\n \tIn overlay mode, the command never removes files when\n-- \nPatched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n\n"},{"id":"392796","messageId":"20200303170740.1879432-1-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200228103558.1684937-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v2 0/5] doc: --recurse-submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-03T17:07:35Z","receivedAt":"2020-03-03T17:08:30Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Incorporated the comments of Philippe Blain.\n\nOther changes since v1:\n- Patch 4: also updated a little the man page of git fetch and git pull.\n- Added a new patch to refer to 'active' submodules.\n\nDamien Robert (5):\n doc: list all commands affected by submodule.recurse\n doc: document --recurse-submodules for reset and restore\n doc: explain how to deactivate recurse.submodule completely\n doc: be more precise on (fetch|push).recurseSubmodules\n doc: --recurse-submodules only apply to active submodules\n\n Documentation/config/fetch.txt | 6 ++++--\n Documentation/config/push.txt | 3 +++\n Documentation/config/submodule.txt | 12 ++++++++++--\n Documentation/fetch-options.txt | 9 +++++----\n Documentation/git-checkout.txt | 2 +-\n Documentation/git-grep.txt | 2 +-\n Documentation/git-pull.txt | 5 ++---\n Documentation/git-read-tree.txt | 2 +-\n Documentation/git-reset.txt | 6 ++++++\n Documentation/git-restore.txt | 10 ++++++++++\n Documentation/git-switch.txt | 2 +-\n Documentation/gitsubmodules.txt | 3 ++-\n 12 files changed, 46 insertions(+), 16 deletions(-)\n\n-- \nPatched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n\n"},{"id":"392797","messageId":"20200303170740.1879432-4-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200303170740.1879432-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-03T17:07:38Z","receivedAt":"2020-03-03T17:08:30Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Signed-off-by: Damien Robert \n---\n Documentation/config/submodule.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\nindex 5962f41ead..74e691a487 100644\n--- a/Documentation/config/submodule.txt\n+++ b/Documentation/config/submodule.txt\n@@ -63,6 +63,13 @@ submodule.recurse::\n \t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n \t`restore` and `switch`) except `clone` and `ls-files`.\n \tDefaults to false.\n+\tWhen set to true, it can be deactivated by calling\n+\t`--no-recurse-submodules`. Note that some Git commands without this\n+\toption may call some of the above commands affected by\n+\t`submodule.recurse`; for instance `git remote update` will call\n+\t`git fetch` but does not have a `--no-recurse-submodules` option.\n+\tsince `submodule.recurse`. In this case a solution is to temporary\n+\tchange the configuration value by using `git -c submodule.recurse=0`.\n \n submodule.fetchJobs::\n \tSpecifies how many submodules are fetched/cloned at the same time.\n-- \nPatched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n\n"},{"id":"392798","messageId":"20200303170740.1879432-5-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200303170740.1879432-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-03T17:07:39Z","receivedAt":"2020-03-03T17:08:32Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"The default value also depends on the value of submodule.recurse.\n\nAlso mention `fetch.recurseSubmodules` in fetch-options.txt. In\ngit-push.txt, `push.recurseSubmodules` is implicitly mentioned (by\nexplaining how to disable it), so no need to add it there.\n\nLastly add a link to `git-fetch` in `git-pull.txt` to explain the\nmeaning of `--recurse-submodules` there.\n\nSigned-off-by: Damien Robert \n---\n Documentation/config/fetch.txt | 6 ++++--\n Documentation/config/push.txt | 3 +++\n Documentation/fetch-options.txt | 3 ++-\n Documentation/git-pull.txt | 3 +--\n 4 files changed, 10 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt\nindex f11940280f..8f716809f9 100644\n--- a/Documentation/config/fetch.txt\n+++ b/Documentation/config/fetch.txt\n@@ -2,10 +2,12 @@ fetch.recurseSubmodules::\n \tThis option can be either set to a boolean value or to 'on-demand'.\n \tSetting it to a boolean changes the behavior of fetch and pull to\n \tunconditionally recurse into submodules when set to true or to not\n-\trecurse at all when set to false. When set to 'on-demand' (the default\n-\tvalue), fetch and pull will only recurse into a populated submodule\n+\trecurse at all when set to false. When set to 'on-demand', \n+\tfetch and pull will only recurse into a populated submodule\n \twhen its superproject retrieves a commit that updates the submodule's\n \treference.\n+\tIf not set, it fallbacks to the value of `submodule.recurse`, and\n+\tif both are not set the default value is 'on-demand'.\n \n fetch.fsckObjects::\n \tIf it is set to true, git-fetch-pack will check all fetched\ndiff --git a/Documentation/config/push.txt b/Documentation/config/push.txt\nindex 54871f8213..2a5250cf5c 100644\n--- a/Documentation/config/push.txt\n+++ b/Documentation/config/push.txt\n@@ -112,3 +112,6 @@ push.recurseSubmodules::\n \tis 'no' then default behavior of ignoring submodules when pushing\n \tis retained. You may override this configuration at time of push by\n \tspecifying '--recurse-submodules=check|on-demand|no'.\n+\tIf not set, it fallbacks to the value of `submodule.recurse` (where\n+\ta 'true' value means 'on-demand'), and if both are not set the\n+\tdefault value is 'no'.\ndiff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt\nindex a115a1ae0e..58972b1a05 100644\n--- a/Documentation/fetch-options.txt\n+++ b/Documentation/fetch-options.txt\n@@ -163,7 +163,8 @@ ifndef::git-pull[]\n \tvalue. Use 'on-demand' to only recurse into a populated submodule\n \twhen the superproject retrieves a commit that updates the submodule's\n \treference to a commit that isn't already in the local submodule\n-\tclone.\n+\tclone. By default this uses the fetch.recurseSubmodules value (see\n+\tlinkgit:git-config), and the default value is 'on-demand'.\n \n -j::\n --jobs=::\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex dfb901f8b8..47bc4a7061 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -86,8 +86,7 @@ OPTIONS\n \n --[no-]recurse-submodules[=yes|on-demand|no]::\n \tThis option controls if new commits of all populated submodules should\n-\tbe fetched and updated, too (see linkgit:git-config[1] and\n-\tlinkgit:gitmodules[5]).\n+\tbe fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).\n +\n If the checkout is done via rebase, local submodule commits are rebased as well.\n +\n-- \nPatched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n\n"},{"id":"392799","messageId":"20200303170740.1879432-6-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200303170740.1879432-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-03T17:07:40Z","receivedAt":"2020-03-03T17:08:34Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"The documentation refers to \"initialized\" or \"populated\" submodules,\nto explain which submodules are affected by '--recurse-submodules', but\nthe real terminology here is 'active' submodules. Update the\ndocumentation accordingly.\n\nSigned-off-by: Damien Robert \n---\n Documentation/fetch-options.txt | 6 +++---\n Documentation/git-checkout.txt | 2 +-\n Documentation/git-grep.txt | 2 +-\n Documentation/git-pull.txt | 2 +-\n Documentation/git-read-tree.txt | 2 +-\n Documentation/git-switch.txt | 2 +-\n 6 files changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt\nindex 58972b1a05..ba33009253 100644\n--- a/Documentation/fetch-options.txt\n+++ b/Documentation/fetch-options.txt\n@@ -156,11 +156,11 @@ ifndef::git-pull[]\n \n --recurse-submodules[=yes|on-demand|no]::\n \tThis option controls if and under what conditions new commits of\n-\tpopulated submodules should be fetched too. It can be used as a\n+\tactive submodules should be fetched too. It can be used as a\n \tboolean option to completely disable recursion when set to 'no' or to\n-\tunconditionally recurse into all populated submodules when set to\n+\tunconditionally recurse into all active submodules when set to\n \t'yes', which is the default when this option is used without any\n-\tvalue. Use 'on-demand' to only recurse into a populated submodule\n+\tvalue. Use 'on-demand' to only recurse into a active submodule\n \twhen the superproject retrieves a commit that updates the submodule's\n \treference to a commit that isn't already in the local submodule\n \tclone. By default this uses the fetch.recurseSubmodules value (see\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex c8fb995fa7..3be0a28284 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also\n \n --recurse-submodules::\n --no-recurse-submodules::\n-\tUsing `--recurse-submodules` will update the content of all initialized\n+\tUsing `--recurse-submodules` will update the content of all active\n \tsubmodules according to the commit recorded in the superproject. If\n \tlocal modifications in a submodule would be overwritten the checkout\n \twill fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex ddb6acc025..cdf8e26b47 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -93,7 +93,7 @@ OPTIONS\n \twith `--no-index`.\n \n --recurse-submodules::\n-\tRecursively search in each submodule that has been initialized and\n+\tRecursively search in each submodule that is active and\n \tchecked out in the repository. When used in combination with the\n \t option the prefix of all submodule output will be the name of\n \tthe parent project's object. This option has no effect\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex 47bc4a7061..2285f3729d 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -85,7 +85,7 @@ OPTIONS\n \tPass --verbose to git-fetch and git-merge.\n \n --[no-]recurse-submodules[=yes|on-demand|no]::\n-\tThis option controls if new commits of all populated submodules should\n+\tThis option controls if new commits of all active submodules should\n \tbe fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).\n +\n If the checkout is done via rebase, local submodule commits are rebased as well.\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex da33f84f33..aab6856341 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -116,7 +116,7 @@ OPTIONS\n \tlocated in.\n \n --[no-]recurse-submodules::\n-\tUsing --recurse-submodules will update the content of all initialized\n+\tUsing --recurse-submodules will update the content of all active\n \tsubmodules according to the commit recorded in the superproject by\n \tcalling read-tree recursively, also setting the submodules HEAD to be\n \tdetached at that commit.\ndiff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\nindex 197900363b..337852d86b 100644\n--- a/Documentation/git-switch.txt\n+++ b/Documentation/git-switch.txt\n@@ -181,7 +181,7 @@ name, the guessing is aborted. You can explicitly give a name with\n --recurse-submodules::\n --no-recurse-submodules::\n \tUsing `--recurse-submodules` will update the content of all\n-\tinitialized submodules according to the commit recorded in the\n+\tactive submodules according to the commit recorded in the\n \tsuperproject. If nothing (or `--no-recurse-submodules`) is\n \tused, the work trees of submodules will not be updated. Just\n \tlike linkgit:git-submodule[1], this will detach `HEAD` of the\n-- \nPatched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)\n\n"},{"id":"392800","messageId":"20200303170905.hnsf4o37mmlcf3hz@feanor","threadId":"52903","inReplyTo":"6C13DF7D-2999-4C91-882F-B899CEBD7C29@gmail.com","subject":"Re: [PATCH 1/4] doc: list all commands affected by recurse.submodule","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-03T17:09:05Z","receivedAt":"2020-03-03T17:09:11Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"From Philippe Blain, Sun 01 Mar 2020 at 23:43:35 (-0500) :\n> I’d also add the same list to the \"Implementation details\" section of the gitsubmodules guide [1], which just mentions `checkout`\n> at the moment.\n\nThe implementation details section really is about the behaviour of\ncloning and checkout. So I just added a link to git-config.\n"},{"id":"392801","messageId":"20200303172613.vmd47i5bcwg56vyt@feanor","threadId":"52903","inReplyTo":"9831AAEE-8FBF-4CBD-B589-3F045720D6DC@gmail.com","subject":"Re: [PATCH 2/4] doc: document --recurse-submodules for reset and restore","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-03T17:26:13Z","receivedAt":"2020-03-03T17:26:18Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"From Philippe Blain, Sun 01 Mar 2020 at 23:45:02 (-0500) :\n> \n\n> From previous testing I had done, when the submodule is modified (either modified content, \n> new commits or new commits, staged) and `git reset` is invoked (and so `git reset HEAD` is assumed),\n> the submodule is only touched if `--hard` or `--merge` is given, \n> i.e. not when `--soft`, `--mixed` (the default action) or `--keep` are given.\n> So this is in line with this option just coming into play \"When the working tree is updated\", as you wrote.\n\nYes essentially reset.c only update the value of submodule.recurse\naccording to --recurse-submodules. Then it is 'unpack-trees.c' that handle\nrecursive submodules.\n\n> However I just noticed that according to the doc `--merge` should abort in that case (I think?), but it does not if \n> `--recurse-submodules` is given. I don’t know if it’s a doc oversight or a real bug though...\n\nGood question...\n\n> > +\twork trees of submodules will not be updated. Just like\n> > +\tlinkgit:git-submodule[1], this will detach `HEAD` of the submodule.\n\n> In fact `git submodule` does not unconditionally detach the submodules HEAD \n> (if `git submodule update` is invoked and a branch is checked out in the submodule that points\n> to the same commit as the one recorded in the superproject, the HEAD is not detached and the branch\n> stays checked out unless `--force` is given.) So I would instead link to `checkout`, \n> which does unconditionally detach the submodules HEAD.\n\nOk. I copied the above line from git-switch[1]. Should I also update it?\ngit-checkout[1] also says that git-submodule will detach HEAD by the way.\n"},{"id":"392817","messageId":"xmqqwo816r4z.fsf@gitster-ct.c.googlers.com","threadId":"52903","inReplyTo":"20200303170740.1879432-3-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-03-03T21:54:36Z","receivedAt":"2020-03-03T21:54:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Damien Robert writes:\n\n> +\n> +--[no-]recurse-submodules::\n> +\tWhen the working tree is updated, using --recurse-submodules will\n> +...\n> \n> +--recurse-submodules::\n> +--no-recurse-submodules::\n> +\tIf `` names a submodule and the restore location includes\n> +...\n\nHmph, this inconsistency across files is a bit unfortunate. \n\nI think (please somebody correct me from sideways) we have been\nmoving towards using the \"--[no-]option-name\", so we would want to\nclean up the latter (together with the \"--[no-]overlay\" entry in the\nsame file, with which the above tries to be consistent) sometime\nlater when the dust settles, iow, not as a part of this series.\n\n> +\tis given, in which case it's working tree will be restored to the\n> +\tcommit recorded in the superproject, and it's local modifications\n> +\toverwritten. If nothing (or `--no-recurse-submodules`) is used,\n> +\tthe work trees of submodules will not be updated. Just like\n> +\tlinkgit:git-checkout[1], this will detach `HEAD` of the submodule.\n> +\n> --overlay::\n> --no-overlay::\n> \tIn overlay mode, the command never removes files when\n\n"},{"id":"392819","messageId":"xmqqsgip6r0d.fsf@gitster-ct.c.googlers.com","threadId":"52903","inReplyTo":"20200303170740.1879432-4-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-03-03T21:57:22Z","receivedAt":"2020-03-03T21:57:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Damien Robert writes:\n\n> Signed-off-by: Damien Robert \n> ---\n> Documentation/config/submodule.txt | 7 +++++++\n> 1 file changed, 7 insertions(+)\n>\n> diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\n> index 5962f41ead..74e691a487 100644\n> --- a/Documentation/config/submodule.txt\n> +++ b/Documentation/config/submodule.txt\n> @@ -63,6 +63,13 @@ submodule.recurse::\n> \t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n> \t`restore` and `switch`) except `clone` and `ls-files`.\n> \tDefaults to false.\n> +\tWhen set to true, it can be deactivated by calling\n> +\t`--no-recurse-submodules`. Note that some Git commands without this\n\nYou do not \"call\" an option [*1*]. Perhaps \"... can be overriden by\npassing the `--no-recurse-submodules` option from the command line.\"\n\n> +\toption may call some of the above commands affected by\n> +\t`submodule.recurse`; for instance `git remote update` will call\n> +\t`git fetch` but does not have a `--no-recurse-submodules` option.\n> +\tsince `submodule.recurse`. In this case a solution is to temporary\n> +\tchange the configuration value by using `git -c submodule.recurse=0`.\n\nA good piece of advice.\n\n\n\n[Footnote]\n\n*1* ... unless you are in a different business, that is ;-).\n"},{"id":"392820","messageId":"20200303220409.xebesh3ygbuwgwgo@doriath","threadId":"52903","inReplyTo":"20200303170740.1879432-4-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-03T22:04:09Z","receivedAt":"2020-03-03T22:04:15Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"From Damien Robert, Tue 03 Mar 2020 at 18:07:38 (+0100) :\n> +\tWhen set to true, it can be deactivated by calling\n> +\t`--no-recurse-submodules`. Note that some Git commands without this\n> +\toption may call some of the above commands affected by\n> +\t`submodule.recurse`; for instance `git remote update` will call\n> +\t`git fetch` but does not have a `--no-recurse-submodules` option.\n> +\tsince `submodule.recurse`. In this case a solution is to temporary\n ^^^^^^^^^^^^^^^^^^^^^^^^^^\nSorry this is a leftover from a previous formulation, I'll clean that up.\n\n> +\tchange the configuration value by using `git -c submodule.recurse=0`.\n"},{"id":"392821","messageId":"xmqqo8td6qmm.fsf@gitster-ct.c.googlers.com","threadId":"52903","inReplyTo":"20200303170740.1879432-5-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-03-03T22:05:37Z","receivedAt":"2020-03-03T22:05:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Damien Robert writes:\n\n> diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt\n> index f11940280f..8f716809f9 100644\n> --- a/Documentation/config/fetch.txt\n> +++ b/Documentation/config/fetch.txt\n> @@ -2,10 +2,12 @@ fetch.recurseSubmodules::\n> \tThis option can be either set to a boolean value or to 'on-demand'.\n> \tSetting it to a boolean changes the behavior of fetch and pull to\n> \tunconditionally recurse into submodules when set to true or to not\n> -\trecurse at all when set to false. When set to 'on-demand' (the default\n> -\tvalue), fetch and pull will only recurse into a populated submodule\n> +\trecurse at all when set to false. When set to 'on-demand', \n> +\tfetch and pull will only recurse into a populated submodule\n> \twhen its superproject retrieves a commit that updates the submodule's\n> \treference.\n> +\tIf not set, it fallbacks to the value of `submodule.recurse`, and\n> +\tif both are not set the default value is 'on-demand'.\n\nI do not think \"fallback\" is a single-word verb. If you must use\nthe phrase, \"it falls back to the value of ...\", but I personally\nprefer to give the simplest case first and then its variants second\n(i.e. if you do not do anything, this is what you get, and then if\nyou do this thing, this other thing happens).\n\nIn other words:\n\n\tIf not set, 'on-demand' is used by default, unless\n\t'submodule.recurse' is set, in which case it is used.\n\nBut in this case it is so obvious that it would not be necessary to\nadd \", in which case it is used\" at the end.\n\n> diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt\n> index 54871f8213..2a5250cf5c 100644\n> --- a/Documentation/config/push.txt\n> +++ b/Documentation/config/push.txt\n> @@ -112,3 +112,6 @@ push.recurseSubmodules::\n> \tis 'no' then default behavior of ignoring submodules when pushing\n> \tis retained. You may override this configuration at time of push by\n> \tspecifying '--recurse-submodules=check|on-demand|no'.\n> +\tIf not set, it fallbacks to the value of `submodule.recurse` (where\n> +\ta 'true' value means 'on-demand'), and if both are not set the\n> +\tdefault value is 'no'.\n\nLikewise.\n\n> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt\n> index a115a1ae0e..58972b1a05 100644\n> --- a/Documentation/fetch-options.txt\n> +++ b/Documentation/fetch-options.txt\n> @@ -163,7 +163,8 @@ ifndef::git-pull[]\n> \tvalue. Use 'on-demand' to only recurse into a populated submodule\n> \twhen the superproject retrieves a commit that updates the submodule's\n> \treference to a commit that isn't already in the local submodule\n> -\tclone.\n> +\tclone. By default this uses the fetch.recurseSubmodules value (see\n> +\tlinkgit:git-config), and the default value is 'on-demand'.\n\n\tBy default, 'on-demand' is used, unless\n\t`fetch.recurseSubmodules` is set (see linkgit:git-config[1]).\n"},{"id":"392822","messageId":"alpine.LFD.2.21.2003031709070.10776@localhost.localdomain","threadId":"52903","inReplyTo":"xmqqo8td6qmm.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2020-03-03T22:12:29Z","receivedAt":"2020-03-03T22:12:35Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Tue, 3 Mar 2020, Junio C Hamano wrote:\n\n> Damien Robert writes:\n>\n> > diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt\n> > index f11940280f..8f716809f9 100644\n> > --- a/Documentation/config/fetch.txt\n> > +++ b/Documentation/config/fetch.txt\n> > @@ -2,10 +2,12 @@ fetch.recurseSubmodules::\n> > \tThis option can be either set to a boolean value or to 'on-demand'.\n> > \tSetting it to a boolean changes the behavior of fetch and pull to\n> > \tunconditionally recurse into submodules when set to true or to not\n> > -\trecurse at all when set to false. When set to 'on-demand' (the default\n> > -\tvalue), fetch and pull will only recurse into a populated submodule\n> > +\trecurse at all when set to false. When set to 'on-demand',\n> > +\tfetch and pull will only recurse into a populated submodule\n> > \twhen its superproject retrieves a commit that updates the submodule's\n> > \treference.\n> > +\tIf not set, it fallbacks to the value of `submodule.recurse`, and\n> > +\tif both are not set the default value is 'on-demand'.\n\n missed earlier post ... \"either set\" should be \"set either.\" also,\nadverbs technically *follow* what they qualify, so \"unconditionally\nrecusrse\" should be \"recurse unconditionally\" and so on.\n\n it has always been thus.\n\nrday\n\np.s. avoid use of the word \"it\" if it's potentially unclear what it\nrefers to. in the above, one reads, \"If not set, it falls back ...\"\n\n*what* falls back?\n"},{"id":"392830","messageId":"alpine.LFD.2.21.2003031703030.10381@localhost.localdomain","threadId":"52903","inReplyTo":"xmqqsgip6r0d.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2020-03-03T22:05:10Z","receivedAt":"2020-03-03T22:56:55Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Tue, 3 Mar 2020, Junio C Hamano wrote:\n\n> Damien Robert writes:\n>\n> > Signed-off-by: Damien Robert \n> > ---\n> > Documentation/config/submodule.txt | 7 +++++++\n> > 1 file changed, 7 insertions(+)\n> >\n> > diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\n> > index 5962f41ead..74e691a487 100644\n> > --- a/Documentation/config/submodule.txt\n> > +++ b/Documentation/config/submodule.txt\n> > @@ -63,6 +63,13 @@ submodule.recurse::\n> > \t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n> > \t`restore` and `switch`) except `clone` and `ls-files`.\n> > \tDefaults to false.\n> > +\tWhen set to true, it can be deactivated by calling\n> > +\t`--no-recurse-submodules`. Note that some Git commands without this\n>\n> You do not \"call\" an option [*1*]. Perhaps \"... can be overriden by\n> passing the `--no-recurse-submodules` option from the command line.\"\n\n nooooooo ... my biggest gripe with documentation is the unnecessary\nuse of superfluous words. :-)\n\n simply, \"can be deactivated via the '--no-recurse-submodules'\noption.\" no one here's getting paid by the word.\n\nrday\n"},{"id":"392892","messageId":"DEF5103D-C687-4EAB-BFF9-58267093B456@gmail.com","threadId":"52903","inReplyTo":"20200303172613.vmd47i5bcwg56vyt@feanor","subject":"Re: [PATCH 2/4] doc: document --recurse-submodules for reset and restore","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-06T04:16:36Z","receivedAt":"2020-03-06T04:16:43Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 3 mars 2020 à 12:26, Damien Robert a écrit :\n> \n>>> +\twork trees of submodules will not be updated. Just like\n>>> +\tlinkgit:git-submodule[1], this will detach `HEAD` of the submodule.\n> \n>> In fact `git submodule` does not unconditionally detach the submodules HEAD \n>> (if `git submodule update` is invoked and a branch is checked out in the submodule that points\n>> to the same commit as the one recorded in the superproject, the HEAD is not detached and the branch\n>> stays checked out unless `--force` is given.) So I would instead link to `checkout`, \n>> which does unconditionally detach the submodules HEAD.\n> \n> Ok. I copied the above line from git-switch[1]. Should I also update it?\n> git-checkout[1] also says that git-submodule will detach HEAD by the way.\n\nI would say yes: git-switch(1) should be updated to refer to git-checkout(1) instead of git-submodule(1),\nand git-checkout(1) should drop the reference to git-submodule(1) \nand just say that it will detach the submodule HEAD. \nMaybe in a separate patch before this one ?"},{"id":"392893","messageId":"7CED2197-7BFF-45DC-94D2-5CFDA7A70EFF@gmail.com","threadId":"52903","inReplyTo":"20200303170740.1879432-3-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-06T04:16:45Z","receivedAt":"2020-03-06T04:16:49Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 3 mars 2020 à 12:07, Damien Robert a écrit :\n> \n> Signed-off-by: Damien Robert \n> ---\n> Documentation/git-reset.txt | 6 ++++++\n> Documentation/git-restore.txt | 10 ++++++++++\n> 2 files changed, 16 insertions(+)\n> \n> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\n> index 932080c55d..838c0f1101 100644\n> --- a/Documentation/git-reset.txt\n> +++ b/Documentation/git-reset.txt\n> @@ -87,6 +87,12 @@ but carries forward unmerged index entries.\n> \tdifferent between `` and `HEAD`.\n> \tIf a file that is different between `` and `HEAD` has local\n> \tchanges, reset is aborted.\n> +\n> +--[no-]recurse-submodules::\n> +\tWhen the working tree is updated, using --recurse-submodules will\n> +\talso recursively reset the content of all active submodules\n> +\taccording to the commit recorded in the superproject, also setting\n> +\tthe submodules HEAD to be detached at that commit.\n> —\n\nMaybe \"working tree\" instead of \"content\" ?\n\n> \n> See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n> diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt\n> index 5bf60d4943..5036f91132 100644\n> --- a/Documentation/git-restore.txt\n> +++ b/Documentation/git-restore.txt\n> @@ -107,6 +107,16 @@ in linkgit:git-checkout[1] for details.\n> \tpatterns and unconditionally restores any files in\n> \t``.\n> \n> +--recurse-submodules::\n> +--no-recurse-submodules::\n> +\tIf `` names a submodule and the restore location includes\n> +\tthe working tree, the submodule will only be updated if this option\n> +\tis given, in which case it's working tree will be restored to the\n> +\tcommit recorded in the superproject, and it's local modifications\n> +\toverwritten. If nothing (or `--no-recurse-submodules`) is used,\n> +\tthe work trees of submodules will not be updated. Just like\n> +\tlinkgit:git-checkout[1], this will detach `HEAD` of the submodule.\n> +\n\nboth \"it's\" should be \"its\". In fact I'd personally prefer \"any local modifications\" instead of \"its local modifications\""},{"id":"392894","messageId":"26A32704-BA98-4EBE-A982-F38830EEB8B5@gmail.com","threadId":"52903","inReplyTo":"20200303220409.xebesh3ygbuwgwgo@doriath","subject":"Re: [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-06T04:16:53Z","receivedAt":"2020-03-06T04:16:57Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 3 mars 2020 à 17:04, Damien Robert a écrit :\n> \n>> +\tsince `submodule.recurse`. In this case a solution is to temporary\n> ^^^^^^^^^^^^^^^^^^^^^^^^^^\n> Sorry this is a leftover from a previous formulation, I'll clean that up.\n\nAlso, the commit title still has the option name reversed:\ns/recurse.submodule/submodule.recurse/\n\n"},{"id":"392895","messageId":"EA460350-CF54-4B91-B1F0-6C4692A14B88@gmail.com","threadId":"52903","inReplyTo":"20200303170740.1879432-6-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-06T04:17:54Z","receivedAt":"2020-03-06T04:17:58Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"In the commit title: s/apply/applies\n\n> Le 3 mars 2020 à 12:07, Damien Robert a écrit :\n> \n> The documentation refers to \"initialized\" or \"populated\" submodules,\n> to explain which submodules are affected by '--recurse-submodules', but\n> the real terminology here is 'active' submodules. Update the\n> documentation accordingly.\n\nInitialized, active and populated, as far as I understand, are three different concepts.\n- Active is defined in gitsubmodules(7), it only involves the configuration variables 'submodule.active', \n'submodule..active' and 'submodule..url'. The function \nsubmodule.c::is_submodule_active checks that a submodule is active.\n- My understanding is that \"populated\" means that the submodule's working tree is \npresent (and the gitfile correctly points to the submodule repository), \ni.e. either the superproject was cloned with ` --recurse-submodules`, or\nthe user ran `git submodule update --init`, or `git submodule init []` and `git submodule update [ \n> Signed-off-by: Damien Robert \n> ---\n> Documentation/fetch-options.txt | 6 +++---\n> Documentation/git-checkout.txt | 2 +-\n> Documentation/git-grep.txt | 2 +-\n> Documentation/git-pull.txt | 2 +-\n> Documentation/git-read-tree.txt | 2 +-\n> Documentation/git-switch.txt | 2 +-\n> 6 files changed, 8 insertions(+), 8 deletions(-)\n\nWhat about ls-files ? builtin/ls-files.c:231 indicates that it does call\nsubmodule.c::is_submodule_active, so its doc should also be updated.\n\n> \n> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt\n> index 58972b1a05..ba33009253 100644\n> --- a/Documentation/fetch-options.txt\n> +++ b/Documentation/fetch-options.txt\n> @@ -156,11 +156,11 @@ ifndef::git-pull[]\n\nFrom what I understand of the code, git-fetch really recurses into *populated* submodules,\nand does not consult the submodule.active or submodule..active config settings.\nIf you look at builtin/fetch.c::cmd_fetch, and the functions it calls, but is_submodule_active is not in the call chain.\nI tested that setting submodule..active to false and calling \n\n git fetch --recurse-submodules=yes\n\nstill fetches in the submodule(s). So this should stay as \"populated\".\n\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index c8fb995fa7..3be0a28284 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also\n> \n> --recurse-submodules::\n> --no-recurse-submodules::\n> -\tUsing `--recurse-submodules` will update the content of all initialized\n> +\tUsing `--recurse-submodules` will update the content of all active\n> \tsubmodules according to the commit recorded in the superproject. If\n> \tlocal modifications in a submodule would be overwritten the checkout\n> \twill fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)\n\nThat's correct as checkout uses the unpack-trees machinery,\nwhich calls submodule_move_head, and submodule_move_head calls \nis_submodule_active (submodule.c:1894).\n\n> diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\n> index ddb6acc025..cdf8e26b47 100644\n> --- a/Documentation/git-grep.txt\n> +++ b/Documentation/git-grep.txt\n> @@ -93,7 +93,7 @@ OPTIONS\n> \twith `--no-index`.\n> \n> --recurse-submodules::\n> -\tRecursively search in each submodule that has been initialized and\n> +\tRecursively search in each submodule that is active and\n> \tchecked out in the repository. When used in combination with the\n> \t option the prefix of all submodule output will be the name of\n> \tthe parent project's object. This option has no effect\n\nThat's correct (builtin/grep.c:423).\n\n> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\n> index 47bc4a7061..2285f3729d 100644\n> --- a/Documentation/git-pull.txt\n> +++ b/Documentation/git-pull.txt\n> @@ -85,7 +85,7 @@ OPTIONS\n> \tPass --verbose to git-fetch and git-merge.\n> \n> --[no-]recurse-submodules[=yes|on-demand|no]::\n> -\tThis option controls if new commits of all populated submodules should\n> +\tThis option controls if new commits of all active submodules should\n> \tbe fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).\n> +\n> If the checkout is done via rebase, local submodule commits are rebased as well.\n\nThat's only partly correct: I tested setting submodule..active to false and doing\n\n git pull --recurse-submodules\n\nThis does fetches the submodule but does not update its working tree, due to the call to \nis_submodule_active in prepare_to_clone_next_submodule in builtin/submodule--helper.c\n\n> diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\n> index da33f84f33..aab6856341 100644\n> --- a/Documentation/git-read-tree.txt\n> +++ b/Documentation/git-read-tree.txt\n> @@ -116,7 +116,7 @@ OPTIONS\n> \tlocated in.\n> \n> --[no-]recurse-submodules::\n> -\tUsing --recurse-submodules will update the content of all initialized\n> +\tUsing --recurse-submodules will update the content of all active\n> \tsubmodules according to the commit recorded in the superproject by\n> \tcalling read-tree recursively, also setting the submodules HEAD to be\n> \tdetached at that commit.\n\n`read-tree` is also in the unpack-trees machinery, so that's correct.\n\n> diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\n> index 197900363b..337852d86b 100644\n> --- a/Documentation/git-switch.txt\n> +++ b/Documentation/git-switch.txt\n> @@ -181,7 +181,7 @@ name, the guessing is aborted. You can explicitly give a name with\n> --recurse-submodules::\n> --no-recurse-submodules::\n> \tUsing `--recurse-submodules` will update the content of all\n> -\tinitialized submodules according to the commit recorded in the\n> +\tactive submodules according to the commit recorded in the\n> \tsuperproject. If nothing (or `--no-recurse-submodules`) is\n> \tused, the work trees of submodules will not be updated. Just\n> \tlike linkgit:git-submodule[1], this will detach `HEAD` of the\n\n`switch` is `checkout ` under the hood, so that's also correct.\n\nIn light of these facts, I think the commit title should be :\ndoc: --recurse-submodules mostly applies to active submodules"},{"id":"393551","messageId":"20200320213729.571924-1-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200228103558.1684937-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v3 0/5] doc: --recurse-submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-20T21:37:24Z","receivedAt":"2020-03-20T21:38:08Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"This is v3, incorporating all remarks received:\n- The typos mistakes mentioned by Robert and Junio.\n- The main change is patch 5/5 where I incorporated the nice explanations of\n Philippe Blain.\n\nDamien Robert (5):\n doc: list all commands affected by submodule.recurse\n doc: document --recurse-submodules for reset and restore\n doc: explain how to deactivate submodule.recurse completely\n doc: be more precise on (fetch|push).recurseSubmodules\n doc: --recurse-submodules mostly only apply to active submodules\n\n Documentation/config/fetch.txt | 10 ++++++----\n Documentation/config/push.txt | 2 ++\n Documentation/config/submodule.txt | 12 ++++++++++--\n Documentation/fetch-options.txt | 3 ++-\n Documentation/git-checkout.txt | 2 +-\n Documentation/git-grep.txt | 2 +-\n Documentation/git-ls-files.txt | 2 +-\n Documentation/git-pull.txt | 5 ++---\n Documentation/git-read-tree.txt | 2 +-\n Documentation/git-reset.txt | 6 ++++++\n Documentation/git-restore.txt | 10 ++++++++++\n Documentation/git-switch.txt | 2 +-\n Documentation/gitsubmodules.txt | 3 ++-\n 13 files changed, 45 insertions(+), 16 deletions(-)\n\n-- \nPatched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)\n\n"},{"id":"393552","messageId":"20200320213729.571924-3-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200320213729.571924-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v3 2/5] doc: document --recurse-submodules for reset and restore","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-20T21:37:26Z","receivedAt":"2020-03-20T21:38:29Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Signed-off-by: Damien Robert \n---\n Documentation/git-reset.txt | 6 ++++++\n Documentation/git-restore.txt | 10 ++++++++++\n 2 files changed, 16 insertions(+)\n\ndiff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\nindex 932080c55d..c8623cfc34 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -87,6 +87,12 @@ but carries forward unmerged index entries.\n \tdifferent between `` and `HEAD`.\n \tIf a file that is different between `` and `HEAD` has local\n \tchanges, reset is aborted.\n+\n+--[no-]recurse-submodules::\n+\tWhen the working tree is updated, using --recurse-submodules will\n+\talso recursively reset the working tree of all active submodules\n+\taccording to the commit recorded in the superproject, also setting\n+\tthe submodules HEAD to be detached at that commit.\n --\n \n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\ndiff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt\nindex 5bf60d4943..47f31d4a0f 100644\n--- a/Documentation/git-restore.txt\n+++ b/Documentation/git-restore.txt\n@@ -107,6 +107,16 @@ in linkgit:git-checkout[1] for details.\n \tpatterns and unconditionally restores any files in\n \t``.\n \n+--recurse-submodules::\n+--no-recurse-submodules::\n+\tIf `` names a submodule and the restore location includes\n+\tthe working tree, the submodule will only be updated if this option\n+\tis given, in which case its working tree will be restored to the\n+\tcommit recorded in the superproject, and any local modifications\n+\toverwritten. If nothing (or `--no-recurse-submodules`) is used,\n+\tthe work trees of submodules will not be updated. Just like\n+\tlinkgit:git-checkout[1], this will detach `HEAD` of the submodule.\n+\n --overlay::\n --no-overlay::\n \tIn overlay mode, the command never removes files when\n-- \nPatched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)\n\n"},{"id":"393553","messageId":"20200320213729.571924-4-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200320213729.571924-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v3 3/5] doc: explain how to deactivate submodule.recurse completely","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-20T21:37:27Z","receivedAt":"2020-03-20T21:38:30Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Signed-off-by: Damien Robert \n---\n Documentation/config/submodule.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\nindex 5962f41ead..900d374385 100644\n--- a/Documentation/config/submodule.txt\n+++ b/Documentation/config/submodule.txt\n@@ -63,6 +63,13 @@ submodule.recurse::\n \t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n \t`restore` and `switch`) except `clone` and `ls-files`.\n \tDefaults to false.\n+\tWhen set to true, it can be deactivated via the\n+\t`--no-recurse-submodules` option. Note that some Git commands\n+\twithout this option may call some of the above commands affected by\n+\t`submodule.recurse`; for instance `git remote update` will call\n+\t`git fetch` but does not have a `--no-recurse-submodules` option.\n+\tIn this case a solution is to temporary change the configuration\n+\tvalue by using `git -c submodule.recurse=0`.\n \n submodule.fetchJobs::\n \tSpecifies how many submodules are fetched/cloned at the same time.\n-- \nPatched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)\n\n"},{"id":"393554","messageId":"20200320213729.571924-5-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200320213729.571924-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-20T21:37:28Z","receivedAt":"2020-03-20T21:38:31Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"The default value also depends on the value of submodule.recurse.\nUse this opportunity to correct some grammar mistakes in\nDocumentation/config/fetch.txt signaled by Robert P. J. Day.\n\nAlso mention `fetch.recurseSubmodules` in fetch-options.txt. In\ngit-push.txt, `push.recurseSubmodules` is implicitly mentioned (by\nexplaining how to disable it), so no need to add it there.\n\nLastly add a link to `git-fetch` in `git-pull.txt` to explain the\nmeaning of `--recurse-submodules` there.\n\nSigned-off-by: Damien Robert \n---\n Documentation/config/fetch.txt | 10 ++++++----\n Documentation/config/push.txt | 2 ++\n Documentation/fetch-options.txt | 3 ++-\n Documentation/git-pull.txt | 3 +--\n 4 files changed, 11 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt\nindex f11940280f..8778a99fa6 100644\n--- a/Documentation/config/fetch.txt\n+++ b/Documentation/config/fetch.txt\n@@ -1,11 +1,13 @@\n fetch.recurseSubmodules::\n-\tThis option can be either set to a boolean value or to 'on-demand'.\n+\tThis option can be set either to a boolean value or to 'on-demand'.\n \tSetting it to a boolean changes the behavior of fetch and pull to\n-\tunconditionally recurse into submodules when set to true or to not\n-\trecurse at all when set to false. When set to 'on-demand' (the default\n-\tvalue), fetch and pull will only recurse into a populated submodule\n+\trecurse unconditionally into submodules when set to true or to not\n+\trecurse at all when set to false. When set to 'on-demand',\n+\tfetch and pull will only recurse into a populated submodule\n \twhen its superproject retrieves a commit that updates the submodule's\n \treference.\n+\tIf not set, 'on-demand' is used by default, unless\n+\t'submodule.recurse' is set.\n \n fetch.fsckObjects::\n \tIf it is set to true, git-fetch-pack will check all fetched\ndiff --git a/Documentation/config/push.txt b/Documentation/config/push.txt\nindex 0a7aa322a9..f5e5b38c68 100644\n--- a/Documentation/config/push.txt\n+++ b/Documentation/config/push.txt\n@@ -112,3 +112,5 @@ push.recurseSubmodules::\n \tis 'no' then default behavior of ignoring submodules when pushing\n \tis retained. You may override this configuration at time of push by\n \tspecifying '--recurse-submodules=check|on-demand|no'.\n+\tIf not set, 'no' is used by default, unless 'submodule.recurse' is\n+\tset (in which case a 'true' value means 'on-demand').\ndiff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt\nindex a115a1ae0e..b1058d63bc 100644\n--- a/Documentation/fetch-options.txt\n+++ b/Documentation/fetch-options.txt\n@@ -163,7 +163,8 @@ ifndef::git-pull[]\n \tvalue. Use 'on-demand' to only recurse into a populated submodule\n \twhen the superproject retrieves a commit that updates the submodule's\n \treference to a commit that isn't already in the local submodule\n-\tclone.\n+\tclone. By default, 'on-demand' is used, unless\n+\t`fetch.recurseSubmodules` is set (see linkgit:git-config[1]).\n \n -j::\n --jobs=::\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex dfb901f8b8..47bc4a7061 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -86,8 +86,7 @@ OPTIONS\n \n --[no-]recurse-submodules[=yes|on-demand|no]::\n \tThis option controls if new commits of all populated submodules should\n-\tbe fetched and updated, too (see linkgit:git-config[1] and\n-\tlinkgit:gitmodules[5]).\n+\tbe fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).\n +\n If the checkout is done via rebase, local submodule commits are rebased as well.\n +\n-- \nPatched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)\n\n"},{"id":"393555","messageId":"20200320213729.571924-6-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200320213729.571924-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-20T21:37:29Z","receivedAt":"2020-03-20T21:38:33Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"The documentation refers to \"initialized\" or \"populated\" submodules,\nto explain which submodules are affected by '--recurse-submodules', but\nthe real terminology here is 'active' submodules. Update the\ndocumentation accordingly.\n\nSome terminology:\n- Active is defined in gitsubmodules(7), it only involves the\n configuration variables 'submodule.active', 'submodule..active'\n and 'submodule..url'. The function\n submodule.c::is_submodule_active checks that a submodule is active.\n- Populated means that the submodule's working tree is present (and the\n gitfile correctly points to the submodule repository), i.e. either the\n superproject was cloned with ` --recurse-submodules`, or the user ran\n `git submodule update --init`, or `git submodule init []` and\n `git submodule update [\nHelped-by: Philippe Blain \n---\n Documentation/git-checkout.txt | 2 +-\n Documentation/git-grep.txt | 2 +-\n Documentation/git-ls-files.txt | 2 +-\n Documentation/git-pull.txt | 2 +-\n Documentation/git-read-tree.txt | 2 +-\n Documentation/git-switch.txt | 2 +-\n 6 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex c8fb995fa7..3be0a28284 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also\n \n --recurse-submodules::\n --no-recurse-submodules::\n-\tUsing `--recurse-submodules` will update the content of all initialized\n+\tUsing `--recurse-submodules` will update the content of all active\n \tsubmodules according to the commit recorded in the superproject. If\n \tlocal modifications in a submodule would be overwritten the checkout\n \twill fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex ddb6acc025..cdf8e26b47 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -93,7 +93,7 @@ OPTIONS\n \twith `--no-index`.\n \n --recurse-submodules::\n-\tRecursively search in each submodule that has been initialized and\n+\tRecursively search in each submodule that is active and\n \tchecked out in the repository. When used in combination with the\n \t option the prefix of all submodule output will be the name of\n \tthe parent project's object. This option has no effect\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 8461c0e83e..3cb2ebb438 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -148,7 +148,7 @@ a space) at the start of each line:\n \ttop directory.\n \n --recurse-submodules::\n-\tRecursively calls ls-files on each submodule in the repository.\n+\tRecursively calls ls-files on each active submodule in the repository.\n \tCurrently there is only support for the --cached mode.\n \n --abbrev[=]::\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex 47bc4a7061..2285f3729d 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -85,7 +85,7 @@ OPTIONS\n \tPass --verbose to git-fetch and git-merge.\n \n --[no-]recurse-submodules[=yes|on-demand|no]::\n-\tThis option controls if new commits of all populated submodules should\n+\tThis option controls if new commits of all active submodules should\n \tbe fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).\n +\n If the checkout is done via rebase, local submodule commits are rebased as well.\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex da33f84f33..aab6856341 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -116,7 +116,7 @@ OPTIONS\n \tlocated in.\n \n --[no-]recurse-submodules::\n-\tUsing --recurse-submodules will update the content of all initialized\n+\tUsing --recurse-submodules will update the content of all active\n \tsubmodules according to the commit recorded in the superproject by\n \tcalling read-tree recursively, also setting the submodules HEAD to be\n \tdetached at that commit.\ndiff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\nindex 197900363b..337852d86b 100644\n--- a/Documentation/git-switch.txt\n+++ b/Documentation/git-switch.txt\n@@ -181,7 +181,7 @@ name, the guessing is aborted. You can explicitly give a name with\n --recurse-submodules::\n --no-recurse-submodules::\n \tUsing `--recurse-submodules` will update the content of all\n-\tinitialized submodules according to the commit recorded in the\n+\tactive submodules according to the commit recorded in the\n \tsuperproject. If nothing (or `--no-recurse-submodules`) is\n \tused, the work trees of submodules will not be updated. Just\n \tlike linkgit:git-submodule[1], this will detach `HEAD` of the\n-- \nPatched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)\n\n"},{"id":"393556","messageId":"20200320213729.571924-2-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200320213729.571924-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v3 1/5] doc: list all commands affected by submodule.recurse","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-20T21:37:25Z","receivedAt":"2020-03-20T21:38:35Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Note that `ls-files` is not affected, even though it has a\n`--recurse-submodules` option, so list it as an exception too.\n\nSigned-off-by: Damien Robert \n---\n Documentation/config/submodule.txt | 5 +++--\n Documentation/gitsubmodules.txt | 3 ++-\n 2 files changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\nindex b33177151c..5962f41ead 100644\n--- a/Documentation/config/submodule.txt\n+++ b/Documentation/config/submodule.txt\n@@ -59,8 +59,9 @@ submodule.active::\n \n submodule.recurse::\n \tSpecifies if commands recurse into submodules by default. This\n-\tapplies to all commands that have a `--recurse-submodules` option,\n-\texcept `clone`.\n+\tapplies to all commands that have a `--recurse-submodules` option\n+\t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n+\t`restore` and `switch`) except `clone` and `ls-files`.\n \tDefaults to false.\n \n submodule.fetchJobs::\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex c476f891b5..f9f4e65c9e 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse\n into submodules. The 'init' and 'update' subcommands of 'git submodule'\n will maintain submodules checked out and at an appropriate revision in\n your working tree. Alternatively you can set 'submodule.recurse' to have\n-'checkout' recursing into submodules.\n+'checkout' recursing into submodules (note that 'submodule.recurse' also\n+affects other git commands, see linkgit:git-config[1] for a complete list).\n \n \n SEE ALSO\n-- \nPatched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)\n\n"},{"id":"393562","messageId":"20200320222328.lynvrgqc35pvxxnl@doriath","threadId":"52903","inReplyTo":"EA460350-CF54-4B91-B1F0-6C4692A14B88@gmail.com","subject":"Re: [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-20T22:23:28Z","receivedAt":"2020-03-20T22:23:37Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"From Philippe Blain, Thu 05 Mar 2020 at 23:17:54 (-0500) :\n> In the commit title: s/apply/applies\n\nOups, missed this one.\n\n> Initialized, active and populated, as far as I understand, are three different concepts.\n[...]\n\n> From what I understand of the code, git-fetch really recurses into *populated* submodules,\n> and does not consult the submodule.active or submodule..active config settings.\n> If you look at builtin/fetch.c::cmd_fetch, and the functions it calls, but is_submodule_active is not in the call chain.\n> I tested that setting submodule..active to false and calling \n> \n> git fetch --recurse-submodules=yes\n> \n> still fetches in the submodule(s). So this should stay as \"populated\".\n\nThanks for the thorough review! I had tested that `git-pull` was only\nupdating the worktree of active submodules, but missed that it was still\nfetching non active submodules.\n\nIn light of this I think this is even more important to mention which\ncommand affects which submodules in the doc.\n\n> That's only partly correct: I tested setting submodule..active to false and doing\n> \n> git pull --recurse-submodules\n> \n> This does fetches the submodule but does not update its working tree, due to the call to \n> is_submodule_active in prepare_to_clone_next_submodule in builtin/submodule--helper.c\n\nI still left 'active submodule' here in order to not render the formulation\ntoo heavy. Since it is implicit that `pull` goes through fetch, I hope it\nis clear that the fetching still involves all populated submodules.\n\n-- \nDamien Robert\nhttp://www.normalesup.org/~robert/pro\n"},{"id":"393742","messageId":"298AFA4F-3D0D-46C7-872A-9B0A0F38E770@gmail.com","threadId":"52903","inReplyTo":"20200320213729.571924-3-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-22T22:36:23Z","receivedAt":"2020-03-22T22:36:31Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 20 mars 2020 à 17:37, Damien Robert a écrit :\n> \n> Signed-off-by: Damien Robert \n> ---\n> Documentation/git-reset.txt | 6 ++++++\n> Documentation/git-restore.txt | 10 ++++++++++\n> 2 files changed, 16 insertions(+)\n> \n> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\n> index 932080c55d..c8623cfc34 100644\n> --- a/Documentation/git-reset.txt\n> +++ b/Documentation/git-reset.txt\n> @@ -87,6 +87,12 @@ but carries forward unmerged index entries.\n> \tdifferent between `` and `HEAD`.\n> \tIf a file that is different between `` and `HEAD` has local\n> \tchanges, reset is aborted.\n> +\n> +--[no-]recurse-submodules::\n> +\tWhen the working tree is updated, using --recurse-submodules will\n> +\talso recursively reset the working tree of all active submodules\n> +\taccording to the commit recorded in the superproject, also setting\n> +\tthe submodules HEAD to be detached at that commit.\n\nI *think* that should be \"the submodules' HEADs\" but I'd prefer that a native speaker confirm.\n\n> --\n> \n> See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n> diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt\n> index 5bf60d4943..47f31d4a0f 100644\n> --- a/Documentation/git-restore.txt\n> +++ b/Documentation/git-restore.txt\n> @@ -107,6 +107,16 @@ in linkgit:git-checkout[1] for details.\n> \tpatterns and unconditionally restores any files in\n> \t``.\n> \n> +--recurse-submodules::\n> +--no-recurse-submodules::\n> +\tIf `` names a submodule and the restore location includes\n\nTo be consistent with patch 5, I think that should be \"names an active submodule\".\n(restore is in the unpack-trees machinery so that would be correct; I checked this behaviour).\n\n> +\tthe working tree, the submodule will only be updated if this option\n> +\tis given, in which case its working tree will be restored to the\n> +\tcommit recorded in the superproject, and any local modifications\n> +\toverwritten. If nothing (or `--no-recurse-submodules`) is used,\n> +\tthe work trees of submodules will not be updated. Just like\n\nFor consistency I'd use \"working trees\" here also, as in the first sentence. \nIn fact I think it would read better as \"submodules working trees will not be updated\".\n"},{"id":"393743","messageId":"934EF1ED-E2A9-4561-8A3D-1B0F71129252@gmail.com","threadId":"52903","inReplyTo":"20200320213729.571924-4-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v3 3/5] doc: explain how to deactivate submodule.recurse completely","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-22T22:36:49Z","receivedAt":"2020-03-22T22:36:54Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 20 mars 2020 à 17:37, Damien Robert a écrit :\n> \n> +\tWhen set to true, it can be deactivated via the\n> +\t`--no-recurse-submodules` option. Note that some Git commands\n> +\twithout this option may call some of the above commands affected by\n\nFor clarity I'd write \"some Git commands lacking this option\" instead, as \"without this option\" \n*could* be interpreted as \"invoked without this option\".\n\n> +\t`submodule.recurse`; for instance `git remote update` will call\n> +\t`git fetch` but does not have a `--no-recurse-submodules` option.\n> +\tIn this case a solution\n\nI'm not sure \"solution\" is the best word here, maybe:\n\n\"For these commands a workaround is to temporarily change the configuration...\"\n\nNote: s/temporary/temporarily/\n\n> is to temporary change the configuration\n> +\tvalue by using `git -c submodule.recurse=0`.\n\n"},{"id":"393744","messageId":"260F83FF-484B-438A-B70A-8348A5267877@gmail.com","threadId":"52903","inReplyTo":"20200320213729.571924-5-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-22T22:37:37Z","receivedAt":"2020-03-22T22:37:42Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 20 mars 2020 à 17:37, Damien Robert a écrit :\n> \n> diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt\n> index f11940280f..8778a99fa6 100644\n> --- a/Documentation/config/fetch.txt\n> +++ b/Documentation/config/fetch.txt\n> @@ -1,11 +1,13 @@\n> fetch.recurseSubmodules::\n> -\tThis option can be either set to a boolean value or to 'on-demand'.\n> +\tThis option can be set either to a boolean value or to 'on-demand'.\n> \tSetting it to a boolean changes the behavior of fetch and pull to\n\nI think in the context of patch 5 maybe it would be good to be careful here, \nand state that this only affects the underlying \"fetch\" in \"pull\", and not the whole pull ?\n\n> -\tunconditionally recurse into submodules when set to true or to not\n> -\trecurse at all when set to false. When set to 'on-demand' (the default\n> -\tvalue), fetch and pull will only recurse into a populated submodule\n> +\trecurse unconditionally into submodules when set to true or to not\n> +\trecurse at all when set to false. When set to 'on-demand',\n> +\tfetch and pull will only recurse into a populated submodule\n> \twhen its superproject retrieves a commit that updates the submodule's\n> \treference.\n> +\tIf not set, 'on-demand' is used by default, unless\n> +\t'submodule.recurse' is set.\n\nI know Junio seems to think otherwise, but to me it would be clearer if this would be \nclearly spelled out: \n\nDefaults to 'on-demand', or to the value of 'submodule.recurse' if set."},{"id":"393745","messageId":"3689E44D-AB57-448E-99AA-C5317373E825@gmail.com","threadId":"52903","inReplyTo":"20200320213729.571924-6-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-22T22:38:47Z","receivedAt":"2020-03-22T22:38:52Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 20 mars 2020 à 17:37, Damien Robert a écrit\n\nin the title, I'd drop the \"only\"\n\"mostly only apply\" -> \"mostly applies\"\n\n> :\n> \n> The documentation refers to \"initialized\" or \"populated\" submodules,\n> to explain which submodules are affected by '--recurse-submodules', but\n> the real terminology here is 'active' submodules. Update the\n> documentation accordingly.\n> \n> Some terminology:\n> - Active is defined in gitsubmodules(7), it only involves the\n> configuration variables 'submodule.active', 'submodule..active'\n> and 'submodule..url'. The function\n> submodule.c::is_submodule_active checks that a submodule is active.\n> - Populated means that the submodule's working tree is present (and the\n> gitfile correctly points to the submodule repository), i.e. either the\n> superproject was cloned with ` --recurse-submodules`, or the user ran\n> `git submodule update --init`, or `git submodule init []` and\n> `git submodule update [' here (my mistake).\n\n> separately which populated the\n> submodule working tree. This does not involve the 3 configuration\n> variables above.\n> - Initialized (at least in the context of the man pages involved in this\n> patch) means both \"populated\" and \"active\" as defined above, i.e. what\n> `git submodule update --init` does.\n> \n> The --recurse-submodules option mostly affects submodules.\n\nI think you meant \"mostly affects active submodules\" here, right?\n\n> An exception\n> is `git fetch` where the option affects populated submodules.\n> As a consequence, in `git pull` the fetch affects populated submodules,\n> but the resulting working tree update only affects active submodules.\n> \n> In the documentation of `git-pull` we only refer to active submodules,\n> since it is implicit that the fetching behaviour is governed by the\n> fetch command.\n\nThis last paragraph is not a description of the current state of the code base, \nbut describes the changes introduced by this patch. As such, it's customary\nto write it in the imperative mode. A simple suggestion to fix that:\n\ns/we/let's/\n\n> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\n> index 47bc4a7061..2285f3729d 100644\n> --- a/Documentation/git-pull.txt\n> +++ b/Documentation/git-pull.txt\n> @@ -85,7 +85,7 @@ OPTIONS\n> \tPass --verbose to git-fetch and git-merge.\n> \n> --[no-]recurse-submodules[=yes|on-demand|no]::\n> -\tThis option controls if new commits of all populated submodules should\n> +\tThis option controls if new commits of all active submodules should\n> \tbe fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).\n\nI understand that the goal here is to make the formulation not too heavy, as you wrote in \nhttps://lore.kernel.org/git/20200320222328.lynvrgqc35pvxxnl@doriath/. However I think the formulation \nis awkward to begin with : commits are \"fetched\", but commits are not \"updated\", the submodules working tree \nare updated. So maybe:\n\nThis option controls if new commits of populated submodules should be fetched, \nand if the working trees of active submodules should be updated, too"},{"id":"393746","messageId":"xmqq4kug804j.fsf@gitster.c.googlers.com","threadId":"52903","inReplyTo":"260F83FF-484B-438A-B70A-8348A5267877@gmail.com","subject":"Re: [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-03-22T23:01:48Z","receivedAt":"2020-03-22T23:02:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philippe Blain writes:\n\n>> -\tThis option can be either set to a boolean value or to 'on-demand'.\n>> +\tThis option can be set either to a boolean value or to 'on-demand'.\n>> \tSetting it to a boolean changes the behavior of fetch and pull to\n>\n> I think in the context of patch 5 maybe it would be good to be\n> careful here, and state that this only affects the underlying\n> \"fetch\" in \"pull\", and not the whole pull ?\n\nMeaning that sub(sub)*modules are fetched but the merge is done only\nfor the top-level superproject? I guess it does not hurt to spell\nit out. Good suggestion.\n\n>> +\tIf not set, 'on-demand' is used by default, unless\n>> +\t'submodule.recurse' is set.\n>\n> I know Junio seems to think otherwise, but to me it would be\n> clearer if this would be clearly spelled out:\n>\n> Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.\n\nWell, between the above two, I'd actually have slight preference to\nyours, but they both look clear enough to almost the same degree, at\nleast to me.\n\nThanks.\n\n"},{"id":"393747","messageId":"818591DE-CD2C-4053-A9AB-49BFCEEBFA08@gmail.com","threadId":"52903","inReplyTo":"xmqq4kug804j.fsf@gitster.c.googlers.com","subject":"Re: [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-22T23:21:00Z","receivedAt":"2020-03-22T23:21:07Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 22 mars 2020 à 19:01, Junio C Hamano a écrit :\n> \n> Philippe Blain writes:\n> \n>>> -\tThis option can be either set to a boolean value or to 'on-demand'.\n>>> +\tThis option can be set either to a boolean value or to 'on-demand'.\n>>> \tSetting it to a boolean changes the behavior of fetch and pull to\n>> \n>> I think in the context of patch 5 maybe it would be good to be\n>> careful here, and state that this only affects the underlying\n>> \"fetch\" in \"pull\", and not the whole pull ?\n> \n> Meaning that sub(sub)*modules are fetched but the merge is done only\n> for the top-level superproject? I guess it does not hurt to spell\n> it out. Good suggestion.\n\nI simply meant that since this option is 'fetch.recurseSubmodules', it applies\nto the fetching operation done by 'git pull' under the hood, and not to the\n \"updating the working tree\" operation that is also done by git pull if \n'--recurse-submodules' is passed to it.\n\nRegarding nested submodules, both operations would recurse down the hierarchy:\nthe fetching fetches all (nested) populated submodules because of the call to \nsubmodule.c::fetch_populated_submodules near the end of builtin/fetch.c::cmd_fetch \nand the \"updating the working tree\", which is controlled \nby the '--recurse-submodules' flag of 'git pull', updates all active submodules \nbecause it spawns 'git submodule update --recursive', (as per rebase_submodules\nand update_submodules in builtin/pull.c)."},{"id":"394010","messageId":"20200325210503.bhkwj5v2xdpjtnvp@doriath","threadId":"52903","inReplyTo":"298AFA4F-3D0D-46C7-872A-9B0A0F38E770@gmail.com","subject":"Re: [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-25T21:05:03Z","receivedAt":"2020-03-25T21:05:10Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"From Philippe Blain, Sun 22 Mar 2020 at 18:36:23 (-0400) :\n> > +--[no-]recurse-submodules::\n> > +\tWhen the working tree is updated, using --recurse-submodules will\n> > +\talso recursively reset the working tree of all active submodules\n> > +\taccording to the commit recorded in the superproject, also setting\n> > +\tthe submodules HEAD to be detached at that commit.\n\n> I *think* that should be \"the submodules' HEADs\" but I'd prefer that a native speaker confirm.\n\nThis was copied from read-tree. So I'll update it too in my next reroll.\n\n> > +\tthe working tree, the submodule will only be updated if this option\n> > +\tis given, in which case its working tree will be restored to the\n> > +\tcommit recorded in the superproject, and any local modifications\n> > +\toverwritten. If nothing (or `--no-recurse-submodules`) is used,\n> > +\tthe work trees of submodules will not be updated. Just like\n \n> For consistency I'd use \"working trees\" here also, as in the first sentence. \n> In fact I think it would read better as \"submodules working trees will not be updated\".\n\nLikewise, this was copied from checkout (and switch). I'll update all of\nthem.\n\n-- \nDamien Robert\nhttp://www.normalesup.org/~robert/pro\n"},{"id":"394011","messageId":"20200325210943.339240-1-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200320213729.571924-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v4 0/5] doc: --recurse-submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-25T21:09:38Z","receivedAt":"2020-03-25T21:10:29Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"No big changes this time, I just incorporated the latest round of remarks.\n(A big thanks to Philippe Blain for these!)\n\nDamien Robert (5):\n doc: list all commands affected by submodule.recurse\n doc: document --recurse-submodules for reset and restore\n doc: explain how to deactivate submodule.recurse completely\n doc: be more precise on (fetch|push).recurseSubmodules\n doc: --recurse-submodules mostly applies to active submodules\n\n Documentation/config/fetch.txt | 9 +++++----\n Documentation/config/push.txt | 2 ++\n Documentation/config/submodule.txt | 12 ++++++++++--\n Documentation/fetch-options.txt | 3 ++-\n Documentation/git-checkout.txt | 4 ++--\n Documentation/git-grep.txt | 2 +-\n Documentation/git-ls-files.txt | 2 +-\n Documentation/git-pull.txt | 5 +++--\n Documentation/git-read-tree.txt | 4 ++--\n Documentation/git-reset.txt | 6 ++++++\n Documentation/git-restore.txt | 11 +++++++++++\n Documentation/git-switch.txt | 4 ++--\n Documentation/gitsubmodules.txt | 3 ++-\n 13 files changed, 49 insertions(+), 18 deletions(-)\n\n-- \nPatched on top of v2.26.0 (git version 2.25.2)\n\n"},{"id":"394012","messageId":"20200325210943.339240-2-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200325210943.339240-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v4 1/5] doc: list all commands affected by submodule.recurse","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-25T21:09:39Z","receivedAt":"2020-03-25T21:10:29Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Note that `ls-files` is not affected, even though it has a\n`--recurse-submodules` option, so list it as an exception too.\n\nSigned-off-by: Damien Robert \n---\n Documentation/config/submodule.txt | 5 +++--\n Documentation/gitsubmodules.txt | 3 ++-\n 2 files changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\nindex b33177151c..5962f41ead 100644\n--- a/Documentation/config/submodule.txt\n+++ b/Documentation/config/submodule.txt\n@@ -59,8 +59,9 @@ submodule.active::\n \n submodule.recurse::\n \tSpecifies if commands recurse into submodules by default. This\n-\tapplies to all commands that have a `--recurse-submodules` option,\n-\texcept `clone`.\n+\tapplies to all commands that have a `--recurse-submodules` option\n+\t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n+\t`restore` and `switch`) except `clone` and `ls-files`.\n \tDefaults to false.\n \n submodule.fetchJobs::\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex c476f891b5..f9f4e65c9e 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse\n into submodules. The 'init' and 'update' subcommands of 'git submodule'\n will maintain submodules checked out and at an appropriate revision in\n your working tree. Alternatively you can set 'submodule.recurse' to have\n-'checkout' recursing into submodules.\n+'checkout' recursing into submodules (note that 'submodule.recurse' also\n+affects other git commands, see linkgit:git-config[1] for a complete list).\n \n \n SEE ALSO\n-- \nPatched on top of v2.26.0 (git version 2.25.2)\n\n"},{"id":"394013","messageId":"20200325210943.339240-3-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200325210943.339240-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v4 2/5] doc: document --recurse-submodules for reset and restore","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-25T21:09:40Z","receivedAt":"2020-03-25T21:10:31Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Also unify the formulation about --no-submodules for checkout and\nswitch, which we reuse for restore.\n\nAnd correct the formulation about submodules' HEAD in read-tree, which\nwe reuse in reset.\n\nSigned-off-by: Damien Robert \n---\n Documentation/git-checkout.txt | 2 +-\n Documentation/git-read-tree.txt | 2 +-\n Documentation/git-reset.txt | 6 ++++++\n Documentation/git-restore.txt | 11 +++++++++++\n Documentation/git-switch.txt | 2 +-\n 5 files changed, 20 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex c8fb995fa7..140bd3eabb 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -296,7 +296,7 @@ Note that this option uses the no overlay mode by default (see also\n \tsubmodules according to the commit recorded in the superproject. If\n \tlocal modifications in a submodule would be overwritten the checkout\n \twill fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)\n-\tis used, the work trees of submodules will not be updated.\n+\tis used, submodules working trees will not be updated.\n \tJust like linkgit:git-submodule[1], this will detach `HEAD` of the\n \tsubmodule.\n \ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex da33f84f33..807cad4691 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -118,7 +118,7 @@ OPTIONS\n --[no-]recurse-submodules::\n \tUsing --recurse-submodules will update the content of all initialized\n \tsubmodules according to the commit recorded in the superproject by\n-\tcalling read-tree recursively, also setting the submodules HEAD to be\n+\tcalling read-tree recursively, also setting the submodules' HEADs to be\n \tdetached at that commit.\n \n --no-sparse-checkout::\ndiff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\nindex 932080c55d..d7a09f11a0 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -87,6 +87,12 @@ but carries forward unmerged index entries.\n \tdifferent between `` and `HEAD`.\n \tIf a file that is different between `` and `HEAD` has local\n \tchanges, reset is aborted.\n+\n+--[no-]recurse-submodules::\n+\tWhen the working tree is updated, using --recurse-submodules will\n+\talso recursively reset the working tree of all active submodules\n+\taccording to the commit recorded in the superproject, also setting\n+\tthe submodules' HEADs to be detached at that commit.\n --\n \n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\ndiff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt\nindex 5bf60d4943..8e3b339802 100644\n--- a/Documentation/git-restore.txt\n+++ b/Documentation/git-restore.txt\n@@ -107,6 +107,17 @@ in linkgit:git-checkout[1] for details.\n \tpatterns and unconditionally restores any files in\n \t``.\n \n+--recurse-submodules::\n+--no-recurse-submodules::\n+\tIf `` names an active submodule and the restore location\n+\tincludes the working tree, the submodule will only be updated if\n+\tthis option is given, in which case its working tree will be\n+\trestored to the commit recorded in the superproject, and any local\n+\tmodifications overwritten. If nothing (or\n+\t`--no-recurse-submodules`) is used, submodules working trees will\n+\tnot be updated. Just like linkgit:git-checkout[1], this will detach\n+\t`HEAD` of the submodule.\n+\n --overlay::\n --no-overlay::\n \tIn overlay mode, the command never removes files when\ndiff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\nindex 197900363b..79dbc9624d 100644\n--- a/Documentation/git-switch.txt\n+++ b/Documentation/git-switch.txt\n@@ -183,7 +183,7 @@ name, the guessing is aborted. You can explicitly give a name with\n \tUsing `--recurse-submodules` will update the content of all\n \tinitialized submodules according to the commit recorded in the\n \tsuperproject. If nothing (or `--no-recurse-submodules`) is\n-\tused, the work trees of submodules will not be updated. Just\n+\tused, submodules working trees will not be updated. Just\n \tlike linkgit:git-submodule[1], this will detach `HEAD` of the\n \tsubmodules.\n \n-- \nPatched on top of v2.26.0 (git version 2.25.2)\n\n"},{"id":"394014","messageId":"20200325210943.339240-4-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200325210943.339240-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v4 3/5] doc: explain how to deactivate submodule.recurse completely","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-25T21:09:41Z","receivedAt":"2020-03-25T21:10:31Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Signed-off-by: Damien Robert \n---\n Documentation/config/submodule.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\nindex 5962f41ead..d7a63c8c12 100644\n--- a/Documentation/config/submodule.txt\n+++ b/Documentation/config/submodule.txt\n@@ -63,6 +63,13 @@ submodule.recurse::\n \t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n \t`restore` and `switch`) except `clone` and `ls-files`.\n \tDefaults to false.\n+\tWhen set to true, it can be deactivated via the\n+\t`--no-recurse-submodules` option. Note that some Git commands\n+\tlacking this option may call some of the above commands affected by\n+\t`submodule.recurse`; for instance `git remote update` will call\n+\t`git fetch` but does not have a `--no-recurse-submodules` option.\n+\tFor these commands a workaround is to temporarily change the\n+\tconfiguration value by using `git -c submodule.recurse=0`.\n \n submodule.fetchJobs::\n \tSpecifies how many submodules are fetched/cloned at the same time.\n-- \nPatched on top of v2.26.0 (git version 2.25.2)\n\n"},{"id":"394015","messageId":"20200325210943.339240-6-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200325210943.339240-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v4 5/5] doc: --recurse-submodules mostly applies to active submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-25T21:09:43Z","receivedAt":"2020-03-25T21:10:33Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"The documentation refers to \"initialized\" or \"populated\" submodules,\nto explain which submodules are affected by '--recurse-submodules', but\nthe real terminology here is 'active' submodules. Update the\ndocumentation accordingly.\n\nSome terminology:\n- Active is defined in gitsubmodules(7), it only involves the\n configuration variables 'submodule.active', 'submodule..active'\n and 'submodule..url'. The function\n submodule.c::is_submodule_active checks that a submodule is active.\n- Populated means that the submodule's working tree is present (and the\n gitfile correctly points to the submodule repository), i.e. either the\n superproject was cloned with ` --recurse-submodules`, or the user ran\n `git submodule update --init`, or `git submodule init []` and\n `git submodule update []` separately which populated the\n submodule working tree. This does not involve the 3 configuration\n variables above.\n- Initialized (at least in the context of the man pages involved in this\n patch) means both \"populated\" and \"active\" as defined above, i.e. what\n `git submodule update --init` does.\n\nThe --recurse-submodules option mostly affects active submodules. An\nexception is `git fetch` where the option affects populated submodules.\nAs a consequence, in `git pull --recurse-submodules` the fetch affects\npopulated submodules, but the resulting working tree update only affects\nactive submodules.\n\nIn the documentation of `git-pull`, let's distinguish between the\nfetching part which affects populated submodules, and the updating of\nworktrees, which only affects active submodules.\n\nSigned-off-by: Damien Robert \nHelped-by: Philippe Blain \n---\n Documentation/git-checkout.txt | 2 +-\n Documentation/git-grep.txt | 2 +-\n Documentation/git-ls-files.txt | 2 +-\n Documentation/git-pull.txt | 6 ++++--\n Documentation/git-read-tree.txt | 2 +-\n Documentation/git-switch.txt | 2 +-\n 6 files changed, 9 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 140bd3eabb..5b697eee1b 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also\n \n --recurse-submodules::\n --no-recurse-submodules::\n-\tUsing `--recurse-submodules` will update the content of all initialized\n+\tUsing `--recurse-submodules` will update the content of all active\n \tsubmodules according to the commit recorded in the superproject. If\n \tlocal modifications in a submodule would be overwritten the checkout\n \twill fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex ddb6acc025..cdf8e26b47 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -93,7 +93,7 @@ OPTIONS\n \twith `--no-index`.\n \n --recurse-submodules::\n-\tRecursively search in each submodule that has been initialized and\n+\tRecursively search in each submodule that is active and\n \tchecked out in the repository. When used in combination with the\n \t option the prefix of all submodule output will be the name of\n \tthe parent project's object. This option has no effect\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 8461c0e83e..3cb2ebb438 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -148,7 +148,7 @@ a space) at the start of each line:\n \ttop directory.\n \n --recurse-submodules::\n-\tRecursively calls ls-files on each submodule in the repository.\n+\tRecursively calls ls-files on each active submodule in the repository.\n \tCurrently there is only support for the --cached mode.\n \n --abbrev[=]::\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex 47bc4a7061..b336df00c7 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -85,8 +85,10 @@ OPTIONS\n \tPass --verbose to git-fetch and git-merge.\n \n --[no-]recurse-submodules[=yes|on-demand|no]::\n-\tThis option controls if new commits of all populated submodules should\n-\tbe fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).\n+\tThis option controls if new commits of populated submodules should\n+\tbe fetched, and if the working trees of active submodules should be\n+\tupdated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and\n+\tlinkgit:gitmodules[5]).\n +\n If the checkout is done via rebase, local submodule commits are rebased as well.\n +\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 807cad4691..a2350994ee 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -116,7 +116,7 @@ OPTIONS\n \tlocated in.\n \n --[no-]recurse-submodules::\n-\tUsing --recurse-submodules will update the content of all initialized\n+\tUsing --recurse-submodules will update the content of all active\n \tsubmodules according to the commit recorded in the superproject by\n \tcalling read-tree recursively, also setting the submodules' HEADs to be\n \tdetached at that commit.\ndiff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\nindex 79dbc9624d..3759c3a265 100644\n--- a/Documentation/git-switch.txt\n+++ b/Documentation/git-switch.txt\n@@ -181,7 +181,7 @@ name, the guessing is aborted. You can explicitly give a name with\n --recurse-submodules::\n --no-recurse-submodules::\n \tUsing `--recurse-submodules` will update the content of all\n-\tinitialized submodules according to the commit recorded in the\n+\tactive submodules according to the commit recorded in the\n \tsuperproject. If nothing (or `--no-recurse-submodules`) is\n \tused, submodules working trees will not be updated. Just\n \tlike linkgit:git-submodule[1], this will detach `HEAD` of the\n-- \nPatched on top of v2.26.0 (git version 2.25.2)\n\n"},{"id":"394017","messageId":"20200325210943.339240-5-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200325210943.339240-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v4 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-03-25T21:09:42Z","receivedAt":"2020-03-25T21:10:36Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"The default value also depends on the value of submodule.recurse.\nUse this opportunity to correct some grammar mistakes in\nDocumentation/config/fetch.txt signaled by Robert P. J. Day.\n\nAlso mention `fetch.recurseSubmodules` in fetch-options.txt. In\ngit-push.txt, `push.recurseSubmodules` is implicitly mentioned (by\nexplaining how to disable it), so no need to add it there.\n\nLastly add a link to `git-fetch` in `git-pull.txt` to explain the\nmeaning of `--recurse-submodules` there.\n\nSigned-off-by: Damien Robert \n---\n Documentation/config/fetch.txt | 9 +++++----\n Documentation/config/push.txt | 2 ++\n Documentation/fetch-options.txt | 3 ++-\n Documentation/git-pull.txt | 3 +--\n 4 files changed, 10 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt\nindex f11940280f..cd5b1417c4 100644\n--- a/Documentation/config/fetch.txt\n+++ b/Documentation/config/fetch.txt\n@@ -1,11 +1,12 @@\n fetch.recurseSubmodules::\n-\tThis option can be either set to a boolean value or to 'on-demand'.\n+\tThis option can be set either to a boolean value or to 'on-demand'.\n \tSetting it to a boolean changes the behavior of fetch and pull to\n-\tunconditionally recurse into submodules when set to true or to not\n-\trecurse at all when set to false. When set to 'on-demand' (the default\n-\tvalue), fetch and pull will only recurse into a populated submodule\n+\trecurse unconditionally into submodules when set to true or to not\n+\trecurse at all when set to false. When set to 'on-demand',\n+\tfetch and pull will only recurse fetching into a populated submodule\n \twhen its superproject retrieves a commit that updates the submodule's\n \treference.\n+\tDefaults to 'on-demand', or to the value of 'submodule.recurse' if set.\n \n fetch.fsckObjects::\n \tIf it is set to true, git-fetch-pack will check all fetched\ndiff --git a/Documentation/config/push.txt b/Documentation/config/push.txt\nindex 0a7aa322a9..f5e5b38c68 100644\n--- a/Documentation/config/push.txt\n+++ b/Documentation/config/push.txt\n@@ -112,3 +112,5 @@ push.recurseSubmodules::\n \tis 'no' then default behavior of ignoring submodules when pushing\n \tis retained. You may override this configuration at time of push by\n \tspecifying '--recurse-submodules=check|on-demand|no'.\n+\tIf not set, 'no' is used by default, unless 'submodule.recurse' is\n+\tset (in which case a 'true' value means 'on-demand').\ndiff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt\nindex a115a1ae0e..b1058d63bc 100644\n--- a/Documentation/fetch-options.txt\n+++ b/Documentation/fetch-options.txt\n@@ -163,7 +163,8 @@ ifndef::git-pull[]\n \tvalue. Use 'on-demand' to only recurse into a populated submodule\n \twhen the superproject retrieves a commit that updates the submodule's\n \treference to a commit that isn't already in the local submodule\n-\tclone.\n+\tclone. By default, 'on-demand' is used, unless\n+\t`fetch.recurseSubmodules` is set (see linkgit:git-config[1]).\n \n -j::\n --jobs=::\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex dfb901f8b8..47bc4a7061 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -86,8 +86,7 @@ OPTIONS\n \n --[no-]recurse-submodules[=yes|on-demand|no]::\n \tThis option controls if new commits of all populated submodules should\n-\tbe fetched and updated, too (see linkgit:git-config[1] and\n-\tlinkgit:gitmodules[5]).\n+\tbe fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).\n +\n If the checkout is done via rebase, local submodule commits are rebased as well.\n +\n-- \nPatched on top of v2.26.0 (git version 2.25.2)\n\n"},{"id":"394297","messageId":"F03FAA2F-EDFB-4497-A4E8-3AC267C779FC@gmail.com","threadId":"52903","inReplyTo":"20200325210943.339240-3-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v4 2/5] doc: document --recurse-submodules for reset and restore","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-29T20:34:50Z","receivedAt":"2020-03-29T20:34:58Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 25 mars 2020 à 17:09, Damien Robert a écrit :\n> \n> Also unify the formulation about --no-submodules\n\nthat should be '--no-recurse-submodules'\n\n> for checkout and\n> switch, which we reuse for restore.\n> \n> And correct the formulation about submodules' HEAD in read-tree, which\n> we reuse in reset.\n> \n> Signed-off-by: Damien Robert \n> ---\n> Documentation/git-checkout.txt | 2 +-\n> Documentation/git-read-tree.txt | 2 +-\n> Documentation/git-reset.txt | 6 ++++++\n> Documentation/git-restore.txt | 11 +++++++++++\n> Documentation/git-switch.txt | 2 +-\n> 5 files changed, 20 insertions(+), 3 deletions(-)\n> \n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index c8fb995fa7..140bd3eabb 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -296,7 +296,7 @@ Note that this option uses the no overlay mode by default (see also\n> \tsubmodules according to the commit recorded in the superproject. If\n> \tlocal modifications in a submodule would be overwritten the checkout\n> \twill fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)\n> -\tis used, the work trees of submodules will not be updated.\n> +\tis used, submodules working trees will not be updated.\n> \tJust like linkgit:git-submodule[1], this will detach `HEAD` of the\n> \tsubmodule.\n> \n> diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\n> index da33f84f33..807cad4691 100644\n> --- a/Documentation/git-read-tree.txt\n> +++ b/Documentation/git-read-tree.txt\n> @@ -118,7 +118,7 @@ OPTIONS\n> --[no-]recurse-submodules::\n> \tUsing --recurse-submodules will update the content of all initialized\n> \tsubmodules according to the commit recorded in the superproject by\n> -\tcalling read-tree recursively, also setting the submodules HEAD to be\n> +\tcalling read-tree recursively, also setting the submodules' HEADs to be\n\nI've rethought about that and I think it should be \"submodules' HEAD\" (sorry!)\n\n> \tdetached at that commit.\n> \n> --no-sparse-checkout::\n> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\n> index 932080c55d..d7a09f11a0 100644\n> --- a/Documentation/git-reset.txt\n> +++ b/Documentation/git-reset.txt\n> @@ -87,6 +87,12 @@ but carries forward unmerged index entries.\n> \tdifferent between `` and `HEAD`.\n> \tIf a file that is different between `` and `HEAD` has local\n> \tchanges, reset is aborted.\n> +\n> +--[no-]recurse-submodules::\n> +\tWhen the working tree is updated, using --recurse-submodules will\n> +\talso recursively reset the working tree of all active submodules\n> +\taccording to the commit recorded in the superproject, also setting\n> +\tthe submodules' HEADs to be detached at that commit.\n\nsame here\n\n> --\n> \n> See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n> diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt\n> index 5bf60d4943..8e3b339802 100644\n> --- a/Documentation/git-restore.txt\n> +++ b/Documentation/git-restore.txt\n> @@ -107,6 +107,17 @@ in linkgit:git-checkout[1] for details.\n> \tpatterns and unconditionally restores any files in\n> \t``.\n> \n> +--recurse-submodules::\n> +--no-recurse-submodules::\n> +\tIf `` names an active submodule and the restore location\n> +\tincludes the working tree, the submodule will only be updated if\n> +\tthis option is given, in which case its working tree will be\n> +\trestored to the commit recorded in the superproject, and any local\n> +\tmodifications overwritten. If nothing (or\n> +\t`--no-recurse-submodules`) is used, submodules working trees will\n> +\tnot be updated. Just like linkgit:git-checkout[1], this will detach\n> +\t`HEAD` of the submodule.\n> +\n> --overlay::\n> --no-overlay::\n> \tIn overlay mode, the command never removes files when\n> diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\n> index 197900363b..79dbc9624d 100644\n> --- a/Documentation/git-switch.txt\n> +++ b/Documentation/git-switch.txt\n> @@ -183,7 +183,7 @@ name, the guessing is aborted. You can explicitly give a name with\n> \tUsing `--recurse-submodules` will update the content of all\n> \tinitialized submodules according to the commit recorded in the\n> \tsuperproject. If nothing (or `--no-recurse-submodules`) is\n> -\tused, the work trees of submodules will not be updated. Just\n> +\tused, submodules working trees will not be updated. Just\n> \tlike linkgit:git-submodule[1], this will detach `HEAD` of the\n> \tsubmodules.\n> \n> -- \n> Patched on top of v2.26.0 (git version 2.25.2)\n> \n\n"},{"id":"394298","messageId":"1EA4CEB1-D329-4916-A9AC-2F64A7A4F6D0@gmail.com","threadId":"52903","inReplyTo":"20200325210943.339240-5-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v4 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-03-29T20:49:48Z","receivedAt":"2020-03-29T20:49:53Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n> Le 25 mars 2020 à 17:09, Damien Robert a écrit :\n> \n> The default value also depends on the value of submodule.recurse.\n> Use this opportunity to correct some grammar mistakes in\n> Documentation/config/fetch.txt signaled by Robert P. J. Day.\n> \n> Also mention `fetch.recurseSubmodules` in fetch-options.txt. In\n> git-push.txt, `push.recurseSubmodules` is implicitly mentioned (by\n> explaining how to disable it), so no need to add it there.\n> \n> Lastly add a link to `git-fetch` in `git-pull.txt` to explain the\n> meaning of `--recurse-submodules` there.\n> \n> Signed-off-by: Damien Robert \n> ---\n> Documentation/config/fetch.txt | 9 +++++----\n> Documentation/config/push.txt | 2 ++\n> Documentation/fetch-options.txt | 3 ++-\n> Documentation/git-pull.txt | 3 +--\n> 4 files changed, 10 insertions(+), 7 deletions(-)\n> \n> diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt\n> index f11940280f..cd5b1417c4 100644\n> --- a/Documentation/config/fetch.txt\n> +++ b/Documentation/config/fetch.txt\n> @@ -1,11 +1,12 @@\n> fetch.recurseSubmodules::\n> -\tThis option can be either set to a boolean value or to 'on-demand'.\n> +\tThis option can be set either to a boolean value or to 'on-demand'.\n> \tSetting it to a boolean changes the behavior of fetch and pull to\n> -\tunconditionally recurse into submodules when set to true or to not\n> -\trecurse at all when set to false. When set to 'on-demand' (the default\n> -\tvalue), fetch and pull will only recurse into a populated submodule\n> +\trecurse unconditionally into submodules when set to true or to not\n> +\trecurse at all when set to false. When set to 'on-demand',\n> +\tfetch and pull will only recurse fetching into a populated submodule\n\nThe chosen formulation seems to imply that only for \"on-demand\" will fetch and pull\nrecursively *fetch* in submodules, which is misleading. I think it might be clearer to just\nadd a sentence at the start :\n\nThis option controls whether `git fetch` (and the underlying fetch in `git pull`) \nwill recursively fetch into populated submodules.\nThis option can be set either to a boolean value or to 'on-demand'.\nSetting it to a boolean changes the behavior of fetch and pull to recurse unconditionally \ninto submodules when set to true or to not recurse at all when set to false.\nWhen set to on-demand, fetch and pull will only recurse into a populated submodule \nwhen its superproject retrieves a commit that updates the submodule’s reference.\n\n\n> \twhen its superproject retrieves a commit that updates the submodule's\n> \treference.\n> +\tDefaults to 'on-demand', or to the value of 'submodule.recurse' if set.\n> \n> fetch.fsckObjects::\n> \tIf it is set to true, git-fetch-pack will check all fetched\n> diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt\n> index 0a7aa322a9..f5e5b38c68 100644\n> --- a/Documentation/config/push.txt\n> +++ b/Documentation/config/push.txt\n> @@ -112,3 +112,5 @@ push.recurseSubmodules::\n> \tis 'no' then default behavior of ignoring submodules when pushing\n> \tis retained. You may override this configuration at time of push by\n> \tspecifying '--recurse-submodules=check|on-demand|no'.\n> +\tIf not set, 'no' is used by default, unless 'submodule.recurse' is\n> +\tset (in which case a 'true' value means 'on-demand').\n> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt\n> index a115a1ae0e..b1058d63bc 100644\n> --- a/Documentation/fetch-options.txt\n> +++ b/Documentation/fetch-options.txt\n> @@ -163,7 +163,8 @@ ifndef::git-pull[]\n> \tvalue. Use 'on-demand' to only recurse into a populated submodule\n> \twhen the superproject retrieves a commit that updates the submodule's\n> \treference to a commit that isn't already in the local submodule\n> -\tclone.\n> +\tclone. By default, 'on-demand' is used, unless\n> +\t`fetch.recurseSubmodules` is set (see linkgit:git-config[1]).\n> \n> -j::\n> --jobs=::\n> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\n> index dfb901f8b8..47bc4a7061 100644\n> --- a/Documentation/git-pull.txt\n> +++ b/Documentation/git-pull.txt\n> @@ -86,8 +86,7 @@ OPTIONS\n> \n> --[no-]recurse-submodules[=yes|on-demand|no]::\n> \tThis option controls if new commits of all populated submodules should\n> -\tbe fetched and updated, too (see linkgit:git-config[1] and\n> -\tlinkgit:gitmodules[5]).\n> +\tbe fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).\n> +\n> If the checkout is done via rebase, local submodule commits are rebased as well.\n> +\n> -- \n> Patched on top of v2.26.0 (git version 2.25.2)\n> \n\n"},{"id":"394800","messageId":"20200405201633.704987-1-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200320213729.571924-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v5 0/5] doc: --recurse-submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-05T20:16:28Z","receivedAt":"2020-04-05T20:16:55Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Sorry it took me a while, I have been busy.\nI incorporated the two remarks by Philippe Blain on v4.\n\nWe are converging!\n\nDamien Robert (5):\n doc: list all commands affected by submodule.recurse\n doc: document --recurse-submodules for reset and restore\n doc: explain how to deactivate submodule.recurse completely\n doc: be more precise on (fetch|push).recurseSubmodules\n doc: --recurse-submodules mostly applies to active submodules\n\n Documentation/config/fetch.txt | 13 ++++++++-----\n Documentation/config/push.txt | 2 ++\n Documentation/config/submodule.txt | 12 ++++++++++--\n Documentation/fetch-options.txt | 3 ++-\n Documentation/git-checkout.txt | 4 ++--\n Documentation/git-grep.txt | 2 +-\n Documentation/git-ls-files.txt | 2 +-\n Documentation/git-pull.txt | 5 +++--\n Documentation/git-read-tree.txt | 4 ++--\n Documentation/git-reset.txt | 6 ++++++\n Documentation/git-restore.txt | 11 +++++++++++\n Documentation/git-switch.txt | 4 ++--\n Documentation/gitsubmodules.txt | 3 ++-\n 13 files changed, 52 insertions(+), 19 deletions(-)\n\n-- \nPatched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)\n\n"},{"id":"394801","messageId":"20200405201633.704987-2-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200405201633.704987-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v5 1/5] doc: list all commands affected by submodule.recurse","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-05T20:16:29Z","receivedAt":"2020-04-05T20:16:55Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Note that `ls-files` is not affected, even though it has a\n`--recurse-submodules` option, so list it as an exception too.\n\nSigned-off-by: Damien Robert \n---\n Documentation/config/submodule.txt | 5 +++--\n Documentation/gitsubmodules.txt | 3 ++-\n 2 files changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\nindex b33177151c..5962f41ead 100644\n--- a/Documentation/config/submodule.txt\n+++ b/Documentation/config/submodule.txt\n@@ -59,8 +59,9 @@ submodule.active::\n \n submodule.recurse::\n \tSpecifies if commands recurse into submodules by default. This\n-\tapplies to all commands that have a `--recurse-submodules` option,\n-\texcept `clone`.\n+\tapplies to all commands that have a `--recurse-submodules` option\n+\t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n+\t`restore` and `switch`) except `clone` and `ls-files`.\n \tDefaults to false.\n \n submodule.fetchJobs::\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex c476f891b5..f9f4e65c9e 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse\n into submodules. The 'init' and 'update' subcommands of 'git submodule'\n will maintain submodules checked out and at an appropriate revision in\n your working tree. Alternatively you can set 'submodule.recurse' to have\n-'checkout' recursing into submodules.\n+'checkout' recursing into submodules (note that 'submodule.recurse' also\n+affects other git commands, see linkgit:git-config[1] for a complete list).\n \n \n SEE ALSO\n-- \nPatched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)\n\n"},{"id":"394802","messageId":"20200405201633.704987-4-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200405201633.704987-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v5 3/5] doc: explain how to deactivate submodule.recurse completely","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-05T20:16:31Z","receivedAt":"2020-04-05T20:16:56Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Signed-off-by: Damien Robert \n---\n Documentation/config/submodule.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt\nindex 5962f41ead..d7a63c8c12 100644\n--- a/Documentation/config/submodule.txt\n+++ b/Documentation/config/submodule.txt\n@@ -63,6 +63,13 @@ submodule.recurse::\n \t(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,\n \t`restore` and `switch`) except `clone` and `ls-files`.\n \tDefaults to false.\n+\tWhen set to true, it can be deactivated via the\n+\t`--no-recurse-submodules` option. Note that some Git commands\n+\tlacking this option may call some of the above commands affected by\n+\t`submodule.recurse`; for instance `git remote update` will call\n+\t`git fetch` but does not have a `--no-recurse-submodules` option.\n+\tFor these commands a workaround is to temporarily change the\n+\tconfiguration value by using `git -c submodule.recurse=0`.\n \n submodule.fetchJobs::\n \tSpecifies how many submodules are fetched/cloned at the same time.\n-- \nPatched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)\n\n"},{"id":"394803","messageId":"20200405201633.704987-3-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200405201633.704987-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v5 2/5] doc: document --recurse-submodules for reset and restore","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-05T20:16:30Z","receivedAt":"2020-04-05T20:16:56Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Also unify the formulation about --no-recurse-submodules for checkout\nand switch, which we reuse for restore.\n\nAnd correct the formulation about submodules' HEAD in read-tree, which\nwe reuse in reset.\n\nSigned-off-by: Damien Robert \n---\n Documentation/git-checkout.txt | 2 +-\n Documentation/git-read-tree.txt | 2 +-\n Documentation/git-reset.txt | 6 ++++++\n Documentation/git-restore.txt | 11 +++++++++++\n Documentation/git-switch.txt | 2 +-\n 5 files changed, 20 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex c8fb995fa7..140bd3eabb 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -296,7 +296,7 @@ Note that this option uses the no overlay mode by default (see also\n \tsubmodules according to the commit recorded in the superproject. If\n \tlocal modifications in a submodule would be overwritten the checkout\n \twill fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)\n-\tis used, the work trees of submodules will not be updated.\n+\tis used, submodules working trees will not be updated.\n \tJust like linkgit:git-submodule[1], this will detach `HEAD` of the\n \tsubmodule.\n \ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex da33f84f33..501f2ec375 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -118,7 +118,7 @@ OPTIONS\n --[no-]recurse-submodules::\n \tUsing --recurse-submodules will update the content of all initialized\n \tsubmodules according to the commit recorded in the superproject by\n-\tcalling read-tree recursively, also setting the submodules HEAD to be\n+\tcalling read-tree recursively, also setting the submodules' HEAD to be\n \tdetached at that commit.\n \n --no-sparse-checkout::\ndiff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\nindex 932080c55d..252e2d4e47 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -87,6 +87,12 @@ but carries forward unmerged index entries.\n \tdifferent between `` and `HEAD`.\n \tIf a file that is different between `` and `HEAD` has local\n \tchanges, reset is aborted.\n+\n+--[no-]recurse-submodules::\n+\tWhen the working tree is updated, using --recurse-submodules will\n+\talso recursively reset the working tree of all active submodules\n+\taccording to the commit recorded in the superproject, also setting\n+\tthe submodules' HEAD to be detached at that commit.\n --\n \n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\ndiff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt\nindex 5bf60d4943..8e3b339802 100644\n--- a/Documentation/git-restore.txt\n+++ b/Documentation/git-restore.txt\n@@ -107,6 +107,17 @@ in linkgit:git-checkout[1] for details.\n \tpatterns and unconditionally restores any files in\n \t``.\n \n+--recurse-submodules::\n+--no-recurse-submodules::\n+\tIf `` names an active submodule and the restore location\n+\tincludes the working tree, the submodule will only be updated if\n+\tthis option is given, in which case its working tree will be\n+\trestored to the commit recorded in the superproject, and any local\n+\tmodifications overwritten. If nothing (or\n+\t`--no-recurse-submodules`) is used, submodules working trees will\n+\tnot be updated. Just like linkgit:git-checkout[1], this will detach\n+\t`HEAD` of the submodule.\n+\n --overlay::\n --no-overlay::\n \tIn overlay mode, the command never removes files when\ndiff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\nindex 197900363b..79dbc9624d 100644\n--- a/Documentation/git-switch.txt\n+++ b/Documentation/git-switch.txt\n@@ -183,7 +183,7 @@ name, the guessing is aborted. You can explicitly give a name with\n \tUsing `--recurse-submodules` will update the content of all\n \tinitialized submodules according to the commit recorded in the\n \tsuperproject. If nothing (or `--no-recurse-submodules`) is\n-\tused, the work trees of submodules will not be updated. Just\n+\tused, submodules working trees will not be updated. Just\n \tlike linkgit:git-submodule[1], this will detach `HEAD` of the\n \tsubmodules.\n \n-- \nPatched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)\n\n"},{"id":"394804","messageId":"20200405201633.704987-6-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200405201633.704987-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v5 5/5] doc: --recurse-submodules mostly applies to active submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-05T20:16:33Z","receivedAt":"2020-04-05T20:16:59Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"The documentation refers to \"initialized\" or \"populated\" submodules,\nto explain which submodules are affected by '--recurse-submodules', but\nthe real terminology here is 'active' submodules. Update the\ndocumentation accordingly.\n\nSome terminology:\n- Active is defined in gitsubmodules(7), it only involves the\n configuration variables 'submodule.active', 'submodule..active'\n and 'submodule..url'. The function\n submodule.c::is_submodule_active checks that a submodule is active.\n- Populated means that the submodule's working tree is present (and the\n gitfile correctly points to the submodule repository), i.e. either the\n superproject was cloned with ` --recurse-submodules`, or the user ran\n `git submodule update --init`, or `git submodule init []` and\n `git submodule update []` separately which populated the\n submodule working tree. This does not involve the 3 configuration\n variables above.\n- Initialized (at least in the context of the man pages involved in this\n patch) means both \"populated\" and \"active\" as defined above, i.e. what\n `git submodule update --init` does.\n\nThe --recurse-submodules option mostly affects active submodules. An\nexception is `git fetch` where the option affects populated submodules.\nAs a consequence, in `git pull --recurse-submodules` the fetch affects\npopulated submodules, but the resulting working tree update only affects\nactive submodules.\n\nIn the documentation of `git-pull`, let's distinguish between the\nfetching part which affects populated submodules, and the updating of\nworktrees, which only affects active submodules.\n\nSigned-off-by: Damien Robert \nHelped-by: Philippe Blain \n---\n Documentation/git-checkout.txt | 2 +-\n Documentation/git-grep.txt | 2 +-\n Documentation/git-ls-files.txt | 2 +-\n Documentation/git-pull.txt | 6 ++++--\n Documentation/git-read-tree.txt | 2 +-\n Documentation/git-switch.txt | 2 +-\n 6 files changed, 9 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 140bd3eabb..5b697eee1b 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also\n \n --recurse-submodules::\n --no-recurse-submodules::\n-\tUsing `--recurse-submodules` will update the content of all initialized\n+\tUsing `--recurse-submodules` will update the content of all active\n \tsubmodules according to the commit recorded in the superproject. If\n \tlocal modifications in a submodule would be overwritten the checkout\n \twill fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex ddb6acc025..cdf8e26b47 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -93,7 +93,7 @@ OPTIONS\n \twith `--no-index`.\n \n --recurse-submodules::\n-\tRecursively search in each submodule that has been initialized and\n+\tRecursively search in each submodule that is active and\n \tchecked out in the repository. When used in combination with the\n \t option the prefix of all submodule output will be the name of\n \tthe parent project's object. This option has no effect\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 8461c0e83e..3cb2ebb438 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -148,7 +148,7 @@ a space) at the start of each line:\n \ttop directory.\n \n --recurse-submodules::\n-\tRecursively calls ls-files on each submodule in the repository.\n+\tRecursively calls ls-files on each active submodule in the repository.\n \tCurrently there is only support for the --cached mode.\n \n --abbrev[=]::\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex 47bc4a7061..b336df00c7 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -85,8 +85,10 @@ OPTIONS\n \tPass --verbose to git-fetch and git-merge.\n \n --[no-]recurse-submodules[=yes|on-demand|no]::\n-\tThis option controls if new commits of all populated submodules should\n-\tbe fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).\n+\tThis option controls if new commits of populated submodules should\n+\tbe fetched, and if the working trees of active submodules should be\n+\tupdated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and\n+\tlinkgit:gitmodules[5]).\n +\n If the checkout is done via rebase, local submodule commits are rebased as well.\n +\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 501f2ec375..5fa8bab64c 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -116,7 +116,7 @@ OPTIONS\n \tlocated in.\n \n --[no-]recurse-submodules::\n-\tUsing --recurse-submodules will update the content of all initialized\n+\tUsing --recurse-submodules will update the content of all active\n \tsubmodules according to the commit recorded in the superproject by\n \tcalling read-tree recursively, also setting the submodules' HEAD to be\n \tdetached at that commit.\ndiff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\nindex 79dbc9624d..3759c3a265 100644\n--- a/Documentation/git-switch.txt\n+++ b/Documentation/git-switch.txt\n@@ -181,7 +181,7 @@ name, the guessing is aborted. You can explicitly give a name with\n --recurse-submodules::\n --no-recurse-submodules::\n \tUsing `--recurse-submodules` will update the content of all\n-\tinitialized submodules according to the commit recorded in the\n+\tactive submodules according to the commit recorded in the\n \tsuperproject. If nothing (or `--no-recurse-submodules`) is\n \tused, submodules working trees will not be updated. Just\n \tlike linkgit:git-submodule[1], this will detach `HEAD` of the\n-- \nPatched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)\n\n"},{"id":"394805","messageId":"20200405201633.704987-5-damien.olivier.robert+git@gmail.com","threadId":"52903","inReplyTo":"20200405201633.704987-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-05T20:16:32Z","receivedAt":"2020-04-05T20:16:59Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"The default value also depends on the value of submodule.recurse.\nUse this opportunity to correct some grammar mistakes in\nDocumentation/config/fetch.txt signaled by Robert P. J. Day.\n\nAlso mention `fetch.recurseSubmodules` in fetch-options.txt. In\ngit-push.txt, `push.recurseSubmodules` is implicitly mentioned (by\nexplaining how to disable it), so no need to add it there.\n\nLastly add a link to `git-fetch` in `git-pull.txt` to explain the\nmeaning of `--recurse-submodules` there.\n\nSigned-off-by: Damien Robert \n---\n Documentation/config/fetch.txt | 13 ++++++++-----\n Documentation/config/push.txt | 2 ++\n Documentation/fetch-options.txt | 3 ++-\n Documentation/git-pull.txt | 3 +--\n 4 files changed, 13 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt\nindex f11940280f..4114af4b3b 100644\n--- a/Documentation/config/fetch.txt\n+++ b/Documentation/config/fetch.txt\n@@ -1,11 +1,14 @@\n fetch.recurseSubmodules::\n-\tThis option can be either set to a boolean value or to 'on-demand'.\n+\tThis option controls whether `git fetch` (and the underlying fetch\n+\tin `git pull`) will recursively fetch into populated submodules.\n+\tThis option can be set either to a boolean value or to 'on-demand'.\n \tSetting it to a boolean changes the behavior of fetch and pull to\n-\tunconditionally recurse into submodules when set to true or to not\n-\trecurse at all when set to false. When set to 'on-demand' (the default\n-\tvalue), fetch and pull will only recurse into a populated submodule\n-\twhen its superproject retrieves a commit that updates the submodule's\n+\trecurse unconditionally into submodules when set to true or to not\n+\trecurse at all when set to false. When set to on-demand, fetch and\n+\tpull will only recurse into a populated submodule when its\n+\tsuperproject retrieves a commit that updates the submodule's\n \treference.\n+\tDefaults to 'on-demand', or to the value of 'submodule.recurse' if set.\n \n fetch.fsckObjects::\n \tIf it is set to true, git-fetch-pack will check all fetched\ndiff --git a/Documentation/config/push.txt b/Documentation/config/push.txt\nindex 0a7aa322a9..f5e5b38c68 100644\n--- a/Documentation/config/push.txt\n+++ b/Documentation/config/push.txt\n@@ -112,3 +112,5 @@ push.recurseSubmodules::\n \tis 'no' then default behavior of ignoring submodules when pushing\n \tis retained. You may override this configuration at time of push by\n \tspecifying '--recurse-submodules=check|on-demand|no'.\n+\tIf not set, 'no' is used by default, unless 'submodule.recurse' is\n+\tset (in which case a 'true' value means 'on-demand').\ndiff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt\nindex 00d03ec8c3..833f935cd0 100644\n--- a/Documentation/fetch-options.txt\n+++ b/Documentation/fetch-options.txt\n@@ -163,7 +163,8 @@ ifndef::git-pull[]\n \tvalue. Use 'on-demand' to only recurse into a populated submodule\n \twhen the superproject retrieves a commit that updates the submodule's\n \treference to a commit that isn't already in the local submodule\n-\tclone.\n+\tclone. By default, 'on-demand' is used, unless\n+\t`fetch.recurseSubmodules` is set (see linkgit:git-config[1]).\n endif::git-pull[]\n \n -j::\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex dfb901f8b8..47bc4a7061 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -86,8 +86,7 @@ OPTIONS\n \n --[no-]recurse-submodules[=yes|on-demand|no]::\n \tThis option controls if new commits of all populated submodules should\n-\tbe fetched and updated, too (see linkgit:git-config[1] and\n-\tlinkgit:gitmodules[5]).\n+\tbe fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).\n +\n If the checkout is done via rebase, local submodule commits are rebased as well.\n +\n-- \nPatched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)\n\n"},{"id":"394812","messageId":"xmqqk12twq7x.fsf@gitster.c.googlers.com","threadId":"52903","inReplyTo":"20200405201633.704987-5-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-05T21:57:22Z","receivedAt":"2020-04-05T21:57:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Damien Robert writes:\n\n> The default value also depends on the value of submodule.recurse.\n> Use this opportunity to correct some grammar mistakes in\n> Documentation/config/fetch.txt signaled by Robert P. J. Day.\n>\n> Also mention `fetch.recurseSubmodules` in fetch-options.txt. In\n> git-push.txt, `push.recurseSubmodules` is implicitly mentioned (by\n> explaining how to disable it), so no need to add it there.\n>\n> Lastly add a link to `git-fetch` in `git-pull.txt` to explain the\n> meaning of `--recurse-submodules` there.\n>\n> Signed-off-by: Damien Robert \n> ---\n> Documentation/config/fetch.txt | 13 ++++++++-----\n> Documentation/config/push.txt | 2 ++\n> Documentation/fetch-options.txt | 3 ++-\n> Documentation/git-pull.txt | 3 +--\n> 4 files changed, 13 insertions(+), 8 deletions(-)\n>\n> diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt\n> index f11940280f..4114af4b3b 100644\n> --- a/Documentation/config/fetch.txt\n> +++ b/Documentation/config/fetch.txt\n> @@ -1,11 +1,14 @@\n> fetch.recurseSubmodules::\n> -\tThis option can be either set to a boolean value or to 'on-demand'.\n> +\tThis option controls whether `git fetch` (and the underlying fetch\n> +\tin `git pull`) will recursively fetch into populated submodules.\n> +\tThis option can be set either to a boolean value or to 'on-demand'.\n> \tSetting it to a boolean changes the behavior of fetch and pull to\n> -\tunconditionally recurse into submodules when set to true or to not\n> -\trecurse at all when set to false. When set to 'on-demand' (the default\n> -\tvalue), fetch and pull will only recurse into a populated submodule\n> -\twhen its superproject retrieves a commit that updates the submodule's\n> +\trecurse unconditionally into submodules when set to true or to not\n> +\trecurse at all when set to false. When set to on-demand, fetch and\n\nWhy did you lose quotes around on-demand on this line? Shouldn't it\nbe typeset the same way as the other one in the sentence \"Defaults\nto ...\"?\n\n> +\tpull will only recurse into a populated submodule when its\n> +\tsuperproject retrieves a commit that updates the submodule's\n> \treference.\n> +\tDefaults to 'on-demand', or to the value of 'submodule.recurse' if set.\n"},{"id":"394831","messageId":"20200406134926.fid74suincbqlibu@feanor","threadId":"52903","inReplyTo":"xmqqk12twq7x.fsf@gitster.c.googlers.com","subject":"Re: [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-06T13:49:26Z","receivedAt":"2020-04-06T13:49:32Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"From Junio C Hamano, Sun 05 Apr 2020 at 14:57:22 (-0700) :\n> Why did you lose quotes around on-demand on this line? Shouldn't it\n> be typeset the same way as the other one in the sentence \"Defaults\n> to ...\"?\n\nYes it should, sorry it's my mistake, I'll send a new version.\n"},{"id":"394866","messageId":"xmqq8sj8wl9a.fsf@gitster.c.googlers.com","threadId":"52903","inReplyTo":"20200406134926.fid74suincbqlibu@feanor","subject":"Re: [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-06T17:56:49Z","receivedAt":"2020-04-06T17:56:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Damien Robert writes:\n\n> From Junio C Hamano, Sun 05 Apr 2020 at 14:57:22 (-0700) :\n>> Why did you lose quotes around on-demand on this line? Shouldn't it\n>> be typeset the same way as the other one in the sentence \"Defaults\n>> to ...\"?\n>\n> Yes it should, sorry it's my mistake, I'll send a new version.\n\nThanks. You may want to wait a bit so that (1) others can spot\nsimilar mistakes, if any, in the version on the list and (2) you\nyourself find some similar errors while waiting for others.\n\n\n"},{"id":"394877","messageId":"20200406184227.zdej7q7eynjwosfv@doriath","threadId":"52903","inReplyTo":"xmqq8sj8wl9a.fsf@gitster.c.googlers.com","subject":"Re: [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-06T18:42:27Z","receivedAt":"2020-04-06T18:42:33Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"From Junio C Hamano, Mon 06 Apr 2020 at 10:56:49 (-0700) :\n> Thanks. You may want to wait a bit so that (1) others can spot\n> similar mistakes, if any, in the version on the list and (2) you\n> yourself find some similar errors while waiting for others.\n\nWell this was mainly the only change compared to v4 which was sent 10 days\nago. This change was suggested by Philippe Blain, so it has already been\nread by him, me, you, and then me again when I sent v6 and checked\ncarefully I did not miss another quote around 'on-demand'.\n\nHopefully that will be enough :)\n"}]}