{"thread":{"id":"53169","subject":"[PATCH v6 1/5] doc: list all commands affected by submodule.recurse","startedAt":"2020-04-06T13:57:39Z","lastAt":"2020-04-16T13:09:41Z","messageCount":7,"participants":["Damien Robert","Philippe Blain"],"isPatch":true,"patchVersion":6,"patchTotal":5},"messages":[{"id":"394832","messageId":"20200406135709.60041-2-damien.olivier.robert+git@gmail.com","threadId":"53169","inReplyTo":"20200406135709.60041-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v6 1/5] doc: list all commands affected by submodule.recurse","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-06T13:57:05Z","receivedAt":"2020-04-06T13:57:39Z","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":"394833","messageId":"20200406135709.60041-1-damien.olivier.robert+git@gmail.com","threadId":"53169","inReplyTo":"20200320213729.571924-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v6 0/5] doc: --recurse-submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-06T13:57:04Z","receivedAt":"2020-04-06T13:57:39Z","isPatch":true,"sender":{"key":"damien.olivier.robert@gmail.com","avatar":null},"body":"Fix typo mentioned by Junio.\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":"394834","messageId":"20200406135709.60041-4-damien.olivier.robert+git@gmail.com","threadId":"53169","inReplyTo":"20200406135709.60041-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v6 3/5] doc: explain how to deactivate submodule.recurse completely","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-06T13:57:07Z","receivedAt":"2020-04-06T13:57:41Z","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":"394835","messageId":"20200406135709.60041-3-damien.olivier.robert+git@gmail.com","threadId":"53169","inReplyTo":"20200406135709.60041-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v6 2/5] doc: document --recurse-submodules for reset and restore","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-06T13:57:06Z","receivedAt":"2020-04-06T13:57:42Z","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":"394836","messageId":"20200406135709.60041-5-damien.olivier.robert+git@gmail.com","threadId":"53169","inReplyTo":"20200406135709.60041-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v6 4/5] doc: be more precise on (fetch|push).recurseSubmodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-06T13:57:08Z","receivedAt":"2020-04-06T13:57:43Z","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..b1a9b1461d 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":"394837","messageId":"20200406135709.60041-6-damien.olivier.robert+git@gmail.com","threadId":"53169","inReplyTo":"20200406135709.60041-1-damien.olivier.robert+git@gmail.com","subject":"[PATCH v6 5/5] doc: --recurse-submodules mostly applies to active submodules","fromName":"Damien Robert","fromEmail":"damien.olivier.robert@gmail.com","sentAt":"2020-04-06T13:57:09Z","receivedAt":"2020-04-06T13:57:46Z","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":"395585","messageId":"7B4732CF-967E-4FF6-86F0-CE3612AB3CA4@gmail.com","threadId":"53169","inReplyTo":"20200406135709.60041-1-damien.olivier.robert+git@gmail.com","subject":"Re: [PATCH v6 0/5] doc: --recurse-submodules","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2020-04-16T13:09:32Z","receivedAt":"2020-04-16T13:09:41Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Damien,\n\n> Le 6 avr. 2020 à 09:57, Damien Robert a écrit :\n> \n> Fix typo mentioned by Junio.\n> \n> Damien 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\nA little late to the game, but consider this series\n\nReviewed-by: Philippe Blain \n\n\n(It's my first review, so I don't know if I should explicitly add that to each patch?...)\n\nAnyway, thanks a lot for putting time into this!\n\nPhilippe.\n\n\n"}]}