[PATCH 0/4] doc: --recurse-submodules

[PATCH 0/4] doc: --recurse-submodules

[Damien Robert]

This series add some extra documentation on --recurse-submodules.

Damien Robert (4):
  doc: list all commands affected by recurse.submodule
  doc: document --recurse-submodules for reset and restore
  doc: explain how to deactivate recurse.submodule completely
  doc: be more precise on (fetch|pull).recurseSubmodules

 Documentation/config/fetch.txt     |  6 ++++--
 Documentation/config/push.txt      |  3 +++
 Documentation/config/submodule.txt | 11 +++++++++--
 Documentation/git-reset.txt        |  6 ++++++
 Documentation/git-restore.txt      |  9 +++++++++
 5 files changed, 31 insertions(+), 4 deletions(-)

-- 
Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)

[PATCH 1/4] doc: list all commands affected by recurse.submodule

[Damien Robert]

Note that `ls-files` is not affected, even though it has a
`--recurse-submodules` option, so list it as an exception too.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/submodule.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index b33177151c..5962f41ead 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -59,8 +59,9 @@ submodule.active::
 
 submodule.recurse::
 	Specifies if commands recurse into submodules by default. This
-	applies to all commands that have a `--recurse-submodules` option,
-	except `clone`.
+	applies to all commands that have a `--recurse-submodules` option
+	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
+	`restore` and `switch`) except `clone` and `ls-files`.
 	Defaults to false.
 
 submodule.fetchJobs::
-- 
Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)

Re: [PATCH 1/4] doc: list all commands affected by recurse.submodule

[Philippe Blain]

HI Damien,

The commit title has the option name reversed: it’s submodule.recurse and not recurse.submodule

> Le 28 févr. 2020 à 05:35, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> Note that `ls-files` is not affected, even though it has a
> `--recurse-submodules` option, so list it as an exception too.

Good find.

> 
> Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
> ---
> Documentation/config/submodule.txt | 5 +++--
> 1 file changed, 3 insertions(+), 2 deletions(-)

I’d also add the same list to the "Implementation details" section of the gitsubmodules guide [1], which just mentions `checkout`
at the moment.

[1] https://git-scm.com/docs/gitsubmodules#_implementation_details

> 
> diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
> index b33177151c..5962f41ead 100644
> --- a/Documentation/config/submodule.txt
> +++ b/Documentation/config/submodule.txt
> @@ -59,8 +59,9 @@ submodule.active::
> 
> submodule.recurse::
> 	Specifies if commands recurse into submodules by default. This
> -	applies to all commands that have a `--recurse-submodules` option,
> -	except `clone`.
> +	applies to all commands that have a `--recurse-submodules` option
> +	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
> +	`restore` and `switch`) except `clone` and `ls-files`.
> 	Defaults to false.
> 
> submodule.fetchJobs::
> -- 
> Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)
> 

Re: [PATCH 1/4] doc: list all commands affected by recurse.submodule

[Damien Robert]

From Philippe Blain, Sun 01 Mar 2020 at 23:43:35 (-0500) :
> I’d also add the same list to the "Implementation details" section of the gitsubmodules guide [1], which just mentions `checkout`
> at the moment.

The implementation details section really is about the behaviour of
cloning and checkout. So I just added a link to git-config.

[PATCH 2/4] doc: document --recurse-submodules for reset and restore

[Damien Robert]

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/git-reset.txt   | 6 ++++++
 Documentation/git-restore.txt | 9 +++++++++
 2 files changed, 15 insertions(+)

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 932080c55d..838c0f1101 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -87,6 +87,12 @@ but carries forward unmerged index entries.
 	different between `<commit>` and `HEAD`.
 	If a file that is different between `<commit>` and `HEAD` has local
 	changes, reset is aborted.
+
+--[no-]recurse-submodules::
+	When the working tree is updated, using --recurse-submodules will
+	also recursively reset the content of all active submodules
+	according to the commit recorded in the superproject, also setting
+	the submodules HEAD to be detached at that commit.
 --
 
 See "Reset, restore and revert" in linkgit:git[1] for the differences
diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
index 5bf60d4943..b94b2559c7 100644
--- a/Documentation/git-restore.txt
+++ b/Documentation/git-restore.txt
@@ -107,6 +107,15 @@ in linkgit:git-checkout[1] for details.
 	patterns and unconditionally restores any files in
 	`<pathspec>`.
 
+--recurse-submodules::
+--no-recurse-submodules::
+	Using `--recurse-submodules` will update the content of all
+	restored submodules according to the commit recorded in the
+	superproject. Local modifications in a restored submodule are
+	overwritten. If nothing (or `--no-recurse-submodules`) is used, the
+	work trees of submodules will not be updated. Just like
+	linkgit:git-submodule[1], this will detach `HEAD` of the submodule.
+
 --overlay::
 --no-overlay::
 	In overlay mode, the command never removes files when
-- 
Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)

Re: [PATCH 2/4] doc: document --recurse-submodules for reset and restore

[Philippe Blain]

> Le 28 févr. 2020 à 05:35, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
> ---
> Documentation/git-reset.txt   | 6 ++++++
> Documentation/git-restore.txt | 9 +++++++++
> 2 files changed, 15 insertions(+)
> 
> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
> index 932080c55d..838c0f1101 100644
> --- a/Documentation/git-reset.txt
> +++ b/Documentation/git-reset.txt
> @@ -87,6 +87,12 @@ but carries forward unmerged index entries.
> 	different between `<commit>` and `HEAD`.
> 	If a file that is different between `<commit>` and `HEAD` has local
> 	changes, reset is aborted.
> +
> +--[no-]recurse-submodules::
> +	When the working tree is updated, using --recurse-submodules will
> +	also recursively reset the content of all active submodules
> +	according to the commit recorded in the superproject, also setting
> +	the submodules HEAD to be detached at that commit.
> —

From previous testing I had done, when the submodule is modified (either modified content, 
new commits or new commits, staged)  and `git reset` is invoked (and so `git reset HEAD` is assumed),
the submodule is only touched if `--hard` or `--merge` is given, 
i.e. not when `--soft`, `--mixed` (the default action) or `--keep` are given.
So this is in line with this option just coming into play "When the working tree is updated", as you wrote.
However I just noticed that according to the doc `--merge` should abort in that case (I think?), but it does not if 
`--recurse-submodules` is given. I don’t know if it’s a doc oversight or a real bug though...

> 
> See "Reset, restore and revert" in linkgit:git[1] for the differences
> diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
> index 5bf60d4943..b94b2559c7 100644
> --- a/Documentation/git-restore.txt
> +++ b/Documentation/git-restore.txt
> @@ -107,6 +107,15 @@ in linkgit:git-checkout[1] for details.
> 	patterns and unconditionally restores any files in
> 	`<pathspec>`.
> 
> +--recurse-submodules::
> +--no-recurse-submodules::
> +	Using `--recurse-submodules` will update the content of all
> +	restored submodules according to the commit recorded in the
> +	superproject.

I’d phrase it more like so :
If `<pathspec>` names a submodule and the restore location includes the working tree, 
the submodule will only be updated if this option is given, 
in which case it’s working tree will be restored to the commit recorded in the superproject 
at the tree-ish given as the restore source.

This makes it clearer that `git restore -- submodule` does nothing, and one has to say
`git restore --recurse-submodules -- submodule` for the submodule working tree to be updated.

> Local modifications in a restored submodule are
> +	overwritten. If nothing (or `--no-recurse-submodules`) is used, the
> +	work trees of submodules will not be updated. Just like
> +	linkgit:git-submodule[1], this will detach `HEAD` of the submodule.
> +

In fact `git submodule` does not unconditionally detach the submodules HEAD 
(if `git submodule update` is invoked and a branch is checked out in the submodule that points
to the same commit as the one recorded in the superproject, the HEAD is not detached and the branch
stays checked out unless `--force` is given.) So I would instead link to `checkout`, 
which does unconditionally detach the submodules HEAD.

> --overlay::
> --no-overlay::
> 	In overlay mode, the command never removes files when
> -- 
> Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)
> 

Re: [PATCH 2/4] doc: document --recurse-submodules for reset and restore

[Damien Robert]

From Philippe Blain, Sun 01 Mar 2020 at 23:45:02 (-0500) :
> 

> From previous testing I had done, when the submodule is modified (either modified content, 
> new commits or new commits, staged)  and `git reset` is invoked (and so `git reset HEAD` is assumed),
> the submodule is only touched if `--hard` or `--merge` is given, 
> i.e. not when `--soft`, `--mixed` (the default action) or `--keep` are given.
> So this is in line with this option just coming into play "When the working tree is updated", as you wrote.

Yes essentially reset.c only update the value of submodule.recurse
according to --recurse-submodules. Then it is 'unpack-trees.c' that handle
recursive submodules.

> However I just noticed that according to the doc `--merge` should abort in that case (I think?), but it does not if 
> `--recurse-submodules` is given. I don’t know if it’s a doc oversight or a real bug though...

Good question...

> > +	work trees of submodules will not be updated. Just like
> > +	linkgit:git-submodule[1], this will detach `HEAD` of the submodule.

> In fact `git submodule` does not unconditionally detach the submodules HEAD 
> (if `git submodule update` is invoked and a branch is checked out in the submodule that points
> to the same commit as the one recorded in the superproject, the HEAD is not detached and the branch
> stays checked out unless `--force` is given.) So I would instead link to `checkout`, 
> which does unconditionally detach the submodules HEAD.

Ok. I copied the above line from git-switch[1]. Should I also update it?
git-checkout[1] also says that git-submodule will detach HEAD by the way.

Re: [PATCH 2/4] doc: document --recurse-submodules for reset and restore

[Philippe Blain]

> Le 3 mars 2020 à 12:26, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
>>> +	work trees of submodules will not be updated. Just like
>>> +	linkgit:git-submodule[1], this will detach `HEAD` of the submodule.
> 
>> In fact `git submodule` does not unconditionally detach the submodules HEAD 
>> (if `git submodule update` is invoked and a branch is checked out in the submodule that points
>> to the same commit as the one recorded in the superproject, the HEAD is not detached and the branch
>> stays checked out unless `--force` is given.) So I would instead link to `checkout`, 
>> which does unconditionally detach the submodules HEAD.
> 
> Ok. I copied the above line from git-switch[1]. Should I also update it?
> git-checkout[1] also says that git-submodule will detach HEAD by the way.

I would say yes: git-switch(1) should be updated to refer to git-checkout(1) instead of git-submodule(1),
and git-checkout(1) should drop the reference to git-submodule(1) 
and just say that it will detach the submodule HEAD. 
Maybe in a separate patch before this one ?

[PATCH 3/4] doc: explain how to deactivate recurse.submodule completely

[Damien Robert]

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/submodule.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index 5962f41ead..f4edc6cad0 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -62,6 +62,12 @@ submodule.recurse::
 	applies to all commands that have a `--recurse-submodules` option
 	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
 	`restore` and `switch`) except `clone` and `ls-files`.
+	When set to true, it can be deactivated by calling
+	`--no-recurse-submodules`. But note that since `submodule.recurse`
+	also applies to internal calls to git commands (issued by other git
+	commands), adding `--no-recurse-submodules` might not be enough to
+	completely turn off the effect of that config. A solution is to use
+	`git -c submodule.recurse=0` instead.
 	Defaults to false.
 
 submodule.fetchJobs::
-- 
Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)

Re: [PATCH 3/4] doc: explain how to deactivate recurse.submodule completely

[Philippe Blain]

Again, the commit title has the option name backwards :
s/recurse.submodule/submodule.recurse/

> Le 28 févr. 2020 à 05:35, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>

I think the commit message for this one could be more detailed 
(even if it would say something very similar to the text added to the doc).
I think it could be made clearer, for example, that the `-c submodule.recurse=0` is
especially useful to deactivate the config when calling commands that do *not* have a `--recurse-submodules` flag,
but that internally call other commands that do support that flag.

> ---
> Documentation/config/submodule.txt | 6 ++++++
> 1 file changed, 6 insertions(+)
> 
> diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
> index 5962f41ead..f4edc6cad0 100644
> --- a/Documentation/config/submodule.txt
> +++ b/Documentation/config/submodule.txt
> @@ -62,6 +62,12 @@ submodule.recurse::
> 	applies to all commands that have a `--recurse-submodules` option
> 	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
> 	`restore` and `switch`) except `clone` and `ls-files`.
> +	When set to true, it can be deactivated by calling
> +	`--no-recurse-submodules`.

I’d say "can be deactivated for a specific call by adding --no-recurse-submodules."

> But note that since `submodule.recurse`
> +	also applies to internal calls to git commands (issued by other git
> +	commands),

We tend to capitalize "Git" when talking about the system as a whole.

> adding `--no-recurse-submodules` might not be enough to
> +	completely turn off the effect of that config. A solution is to use
> +	`git -c submodule.recurse=0` instead.
> 	Defaults to false.

Personally I’d let "Defaults to false" just after the list of affected commands.

> 
> submodule.fetchJobs::
> -- 
> Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)
> 

[PATCH 4/4] doc: be more precise on (fetch|pull).recurseSubmodules

[Damien Robert]

The default value also depends on the value of submodule.recurse

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/fetch.txt | 6 ++++--
 Documentation/config/push.txt  | 3 +++
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
index f11940280f..8f716809f9 100644
--- a/Documentation/config/fetch.txt
+++ b/Documentation/config/fetch.txt
@@ -2,10 +2,12 @@ fetch.recurseSubmodules::
 	This option can be either set to a boolean value or to 'on-demand'.
 	Setting it to a boolean changes the behavior of fetch and pull to
 	unconditionally recurse into submodules when set to true or to not
-	recurse at all when set to false. When set to 'on-demand' (the default
-	value), fetch and pull will only recurse into a populated submodule
+	recurse at all when set to false. When set to 'on-demand', 
+	fetch and pull will only recurse into a populated submodule
 	when its superproject retrieves a commit that updates the submodule's
 	reference.
+	If not set, it fallbacks to the value of `submodule.recurse`, and
+	if both are not set the default value is 'on-demand'.
 
 fetch.fsckObjects::
 	If it is set to true, git-fetch-pack will check all fetched
diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt
index 54871f8213..2a5250cf5c 100644
--- a/Documentation/config/push.txt
+++ b/Documentation/config/push.txt
@@ -112,3 +112,6 @@ push.recurseSubmodules::
 	is 'no' then default behavior of ignoring submodules when pushing
 	is retained. You may override this configuration at time of push by
 	specifying '--recurse-submodules=check|on-demand|no'.
+	If not set, it fallbacks to the value of `submodule.recurse` (where
+	a 'true' value means 'on-demand'), and if both are not set the
+	default value is 'no'.
-- 
Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)

Re: [PATCH 4/4] doc: be more precise on (fetch|pull).recurseSubmodules

[Philippe Blain]

The commit message title mentions fetch and pull but the patch also talks about push, maybe add that to the title ?

> Le 28 févr. 2020 à 05:35, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> The default value also depends on the value of submodule.recurse
> 
> Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
> ---
> Documentation/config/fetch.txt | 6 ++++--
> Documentation/config/push.txt  | 3 +++
> 2 files changed, 7 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
> index f11940280f..8f716809f9 100644
> --- a/Documentation/config/fetch.txt
> +++ b/Documentation/config/fetch.txt
> @@ -2,10 +2,12 @@ fetch.recurseSubmodules::
> 	This option can be either set to a boolean value or to 'on-demand'.
> 	Setting it to a boolean changes the behavior of fetch and pull to
> 	unconditionally recurse into submodules when set to true or to not
> -	recurse at all when set to false. When set to 'on-demand' (the default
> -	value), fetch and pull will only recurse into a populated submodule
> +	recurse at all when set to false. When set to 'on-demand', 
> +	fetch and pull will only recurse into a populated submodule
> 	when its superproject retrieves a commit that updates the submodule's
> 	reference.
> +	If not set, it fallbacks to the value of `submodule.recurse`, and
> +	if both are not set the default value is 'on-demand’.

For such a change to the doc, I’d expect the commit message to point 
to the relevant part of the code that supports the behaviour that is being described, 
or to the specific test that enforces this behaviour (I briefly looked at t5526 but couldn’t spot one).
If such a test is missing it would be good to add it.

> 
> fetch.fsckObjects::
> 	If it is set to true, git-fetch-pack will check all fetched
> diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt
> index 54871f8213..2a5250cf5c 100644
> --- a/Documentation/config/push.txt
> +++ b/Documentation/config/push.txt
> @@ -112,3 +112,6 @@ push.recurseSubmodules::
> 	is 'no' then default behavior of ignoring submodules when pushing
> 	is retained. You may override this configuration at time of push by
> 	specifying '--recurse-submodules=check|on-demand|no'.
> +	If not set, it fallbacks to the value of `submodule.recurse` (where
> +	a 'true' value means 'on-demand'), and if both are not set the
> +	default value is 'no’.

Same thing here. Also, I do not think it’s good UI that setting ‘submodule,recurse’ to true will make ‘push' default to ‘on-demand’ 
but will make ‘fetch’ unconditionally fetch, but I guess that would be for another series...

> -- 
> Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)
> 

Re: [PATCH 0/4] doc: --recurse-submodules

[Damien Robert]

Note that git-switch.txt states that
	Using `--recurse-submodules` will update the content of all
	initialized submodules according to the commit recorded in the
	superproject.
but actually only 'active' submodules will be updated.

Should I also update the doc? It is already stated in `gitsubmodules(7)`
that only 'active' submodules are considered for recursion.

-- 
Damien Robert
http://www.normalesup.org/~robert/pro

Re: [PATCH 0/4] doc: --recurse-submodules

[Philippe Blain]

> Le 28 févr. 2020 à 05:44, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> Note that git-switch.txt states that
> 	Using `--recurse-submodules` will update the content of all
> 	initialized submodules according to the commit recorded in the
> 	superproject.
> but actually only 'active' submodules will be updated.

Technically that’s true, but I’d say that in a "simple" workflow (you clone a superproject then do
`git submodule update --init`, then maybe set `submodule.recurse` to true), then being active and 
being initialized are equivalent. So I don’t think it’s that big of an issue. 

In any case, if such a change is made, the doc for
all commands that have the flag should be revised, as both "initialized" (grep, checkout, switch, read-tree)
and "populated" (fetch, pull) seems to be used currently.

> 
> Should I also update the doc? It is already stated in `gitsubmodules(7)`
> that only 'active' submodules are considered for recursion.
> 
> -- 
> Damien Robert
> http://www.normalesup.org/~robert/pro

Re: [PATCH 0/4] doc: --recurse-submodules

[Philippe Blain]

Hi Damien,
> Le 28 févr. 2020 à 05:35, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> This series add some extra documentation on --recurse-submodules.
> 
> Damien Robert (4):
>  doc: list all commands affected by recurse.submodule
>  doc: document --recurse-submodules for reset and restore
>  doc: explain how to deactivate recurse.submodule completely
>  doc: be more precise on (fetch|pull).recurseSubmodules
> 
> Documentation/config/fetch.txt     |  6 ++++--
> Documentation/config/push.txt      |  3 +++
> Documentation/config/submodule.txt | 11 +++++++++--
> Documentation/git-reset.txt        |  6 ++++++
> Documentation/git-restore.txt      |  9 +++++++++
> 5 files changed, 31 insertions(+), 4 deletions(-)

Thanks a lot for working on that!

Cheers,
Philippe.

> 
> -- 
> Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)
> 

[PATCH v2 0/5] doc: --recurse-submodules

[Damien Robert]

Incorporated the comments of Philippe Blain.

Other changes since v1:
- Patch 4: also updated a little the man page of git fetch and git pull.
- Added a new patch to refer to 'active' submodules.

Damien Robert (5):
  doc: list all commands affected by submodule.recurse
  doc: document --recurse-submodules for reset and restore
  doc: explain how to deactivate recurse.submodule completely
  doc: be more precise on (fetch|push).recurseSubmodules
  doc: --recurse-submodules only apply to active submodules

 Documentation/config/fetch.txt     |  6 ++++--
 Documentation/config/push.txt      |  3 +++
 Documentation/config/submodule.txt | 12 ++++++++++--
 Documentation/fetch-options.txt    |  9 +++++----
 Documentation/git-checkout.txt     |  2 +-
 Documentation/git-grep.txt         |  2 +-
 Documentation/git-pull.txt         |  5 ++---
 Documentation/git-read-tree.txt    |  2 +-
 Documentation/git-reset.txt        |  6 ++++++
 Documentation/git-restore.txt      | 10 ++++++++++
 Documentation/git-switch.txt       |  2 +-
 Documentation/gitsubmodules.txt    |  3 ++-
 12 files changed, 46 insertions(+), 16 deletions(-)

-- 
Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)

[PATCH v2 1/5] doc: list all commands affected by submodule.recurse

[Damien Robert]

Note that `ls-files` is not affected, even though it has a
`--recurse-submodules` option, so list it as an exception too.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/submodule.txt | 5 +++--
 Documentation/gitsubmodules.txt    | 3 ++-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index b33177151c..5962f41ead 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -59,8 +59,9 @@ submodule.active::
 
 submodule.recurse::
 	Specifies if commands recurse into submodules by default. This
-	applies to all commands that have a `--recurse-submodules` option,
-	except `clone`.
+	applies to all commands that have a `--recurse-submodules` option
+	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
+	`restore` and `switch`) except `clone` and `ls-files`.
 	Defaults to false.
 
 submodule.fetchJobs::
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index c476f891b5..f9f4e65c9e 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse
 into submodules. The 'init' and 'update' subcommands of 'git submodule'
 will maintain submodules checked out and at an appropriate revision in
 your working tree. Alternatively you can set 'submodule.recurse' to have
-'checkout' recursing into submodules.
+'checkout' recursing into submodules (note that 'submodule.recurse' also
+affects other git commands, see linkgit:git-config[1] for a complete list).
 
 
 SEE ALSO
-- 
Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)

[PATCH v2 2/5] doc: document --recurse-submodules for reset and restore

[Damien Robert]

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/git-reset.txt   |  6 ++++++
 Documentation/git-restore.txt | 10 ++++++++++
 2 files changed, 16 insertions(+)

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 932080c55d..838c0f1101 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -87,6 +87,12 @@ but carries forward unmerged index entries.
 	different between `<commit>` and `HEAD`.
 	If a file that is different between `<commit>` and `HEAD` has local
 	changes, reset is aborted.
+
+--[no-]recurse-submodules::
+	When the working tree is updated, using --recurse-submodules will
+	also recursively reset the content of all active submodules
+	according to the commit recorded in the superproject, also setting
+	the submodules HEAD to be detached at that commit.
 --
 
 See "Reset, restore and revert" in linkgit:git[1] for the differences
diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
index 5bf60d4943..5036f91132 100644
--- a/Documentation/git-restore.txt
+++ b/Documentation/git-restore.txt
@@ -107,6 +107,16 @@ in linkgit:git-checkout[1] for details.
 	patterns and unconditionally restores any files in
 	`<pathspec>`.
 
+--recurse-submodules::
+--no-recurse-submodules::
+	If `<pathspec>` names a submodule and the restore location includes
+	the working tree, the submodule will only be updated if this option
+	is given, in which case it's working tree will be restored to the
+	commit recorded in the superproject, and it's local modifications
+	overwritten. If nothing (or `--no-recurse-submodules`) is used,
+	the work trees of submodules will not be updated. Just like
+	linkgit:git-checkout[1], this will detach `HEAD` of the submodule.
+
 --overlay::
 --no-overlay::
 	In overlay mode, the command never removes files when
-- 
Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)

Re: [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore

[Junio C Hamano]

Damien Robert <damien.olivier.robert@gmail.com> writes:

> +
> +--[no-]recurse-submodules::
> +	When the working tree is updated, using --recurse-submodules will
> +...
>  
> +--recurse-submodules::
> +--no-recurse-submodules::
> +	If `<pathspec>` names a submodule and the restore location includes
> +...

Hmph, this inconsistency across files is a bit unfortunate.  

I think (please somebody correct me from sideways) we have been
moving towards using the "--[no-]option-name", so we would want to
clean up the latter (together with the "--[no-]overlay" entry in the
same file, with which the above tries to be consistent) sometime
later when the dust settles, iow, not as a part of this series.

> +	is given, in which case it's working tree will be restored to the
> +	commit recorded in the superproject, and it's local modifications
> +	overwritten. If nothing (or `--no-recurse-submodules`) is used,
> +	the work trees of submodules will not be updated. Just like
> +	linkgit:git-checkout[1], this will detach `HEAD` of the submodule.
> +
>  --overlay::
>  --no-overlay::
>  	In overlay mode, the command never removes files when

Re: [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore

[Philippe Blain]

> Le 3 mars 2020 à 12:07, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
> ---
> Documentation/git-reset.txt   |  6 ++++++
> Documentation/git-restore.txt | 10 ++++++++++
> 2 files changed, 16 insertions(+)
> 
> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
> index 932080c55d..838c0f1101 100644
> --- a/Documentation/git-reset.txt
> +++ b/Documentation/git-reset.txt
> @@ -87,6 +87,12 @@ but carries forward unmerged index entries.
> 	different between `<commit>` and `HEAD`.
> 	If a file that is different between `<commit>` and `HEAD` has local
> 	changes, reset is aborted.
> +
> +--[no-]recurse-submodules::
> +	When the working tree is updated, using --recurse-submodules will
> +	also recursively reset the content of all active submodules
> +	according to the commit recorded in the superproject, also setting
> +	the submodules HEAD to be detached at that commit.
> —

Maybe "working tree" instead of "content" ?

> 
> See "Reset, restore and revert" in linkgit:git[1] for the differences
> diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
> index 5bf60d4943..5036f91132 100644
> --- a/Documentation/git-restore.txt
> +++ b/Documentation/git-restore.txt
> @@ -107,6 +107,16 @@ in linkgit:git-checkout[1] for details.
> 	patterns and unconditionally restores any files in
> 	`<pathspec>`.
> 
> +--recurse-submodules::
> +--no-recurse-submodules::
> +	If `<pathspec>` names a submodule and the restore location includes
> +	the working tree, the submodule will only be updated if this option
> +	is given, in which case it's working tree will be restored to the
> +	commit recorded in the superproject, and it's local modifications
> +	overwritten. If nothing (or `--no-recurse-submodules`) is used,
> +	the work trees of submodules will not be updated. Just like
> +	linkgit:git-checkout[1], this will detach `HEAD` of the submodule.
> +

both "it's" should be "its". In fact I'd personally prefer "any local modifications" instead of "its local modifications"

[PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely

[Damien Robert]

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/submodule.txt | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index 5962f41ead..74e691a487 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -63,6 +63,13 @@ submodule.recurse::
 	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
 	`restore` and `switch`) except `clone` and `ls-files`.
 	Defaults to false.
+	When set to true, it can be deactivated by calling
+	`--no-recurse-submodules`. Note that some Git commands without this
+	option may call some of the above commands affected by
+	`submodule.recurse`; for instance `git remote update` will call
+	`git fetch` but does not have a `--no-recurse-submodules` option.
+	since `submodule.recurse`. In this case a solution is to temporary
+	change the configuration value by using `git -c submodule.recurse=0`.
 
 submodule.fetchJobs::
 	Specifies how many submodules are fetched/cloned at the same time.
-- 
Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)

Re: [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely

[Junio C Hamano]

Damien Robert <damien.olivier.robert@gmail.com> writes:

> Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
> ---
>  Documentation/config/submodule.txt | 7 +++++++
>  1 file changed, 7 insertions(+)
>
> diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
> index 5962f41ead..74e691a487 100644
> --- a/Documentation/config/submodule.txt
> +++ b/Documentation/config/submodule.txt
> @@ -63,6 +63,13 @@ submodule.recurse::
>  	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
>  	`restore` and `switch`) except `clone` and `ls-files`.
>  	Defaults to false.
> +	When set to true, it can be deactivated by calling
> +	`--no-recurse-submodules`. Note that some Git commands without this

You do not "call" an option [*1*].  Perhaps "... can be overriden by
passing the `--no-recurse-submodules` option from the command line."

> +	option may call some of the above commands affected by
> +	`submodule.recurse`; for instance `git remote update` will call
> +	`git fetch` but does not have a `--no-recurse-submodules` option.
> +	since `submodule.recurse`. In this case a solution is to temporary
> +	change the configuration value by using `git -c submodule.recurse=0`.

A good piece of advice.



[Footnote]

*1* ... unless you are in a different business, that is ;-).

Re: [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely

[Robert P. J. Day]

On Tue, 3 Mar 2020, Junio C Hamano wrote:

> Damien Robert <damien.olivier.robert@gmail.com> writes:
>
> > Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
> > ---
> >  Documentation/config/submodule.txt | 7 +++++++
> >  1 file changed, 7 insertions(+)
> >
> > diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
> > index 5962f41ead..74e691a487 100644
> > --- a/Documentation/config/submodule.txt
> > +++ b/Documentation/config/submodule.txt
> > @@ -63,6 +63,13 @@ submodule.recurse::
> >  	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
> >  	`restore` and `switch`) except `clone` and `ls-files`.
> >  	Defaults to false.
> > +	When set to true, it can be deactivated by calling
> > +	`--no-recurse-submodules`. Note that some Git commands without this
>
> You do not "call" an option [*1*].  Perhaps "... can be overriden by
> passing the `--no-recurse-submodules` option from the command line."

  nooooooo ... my biggest gripe with documentation is the unnecessary
use of superfluous words. :-)

  simply, "can be deactivated via the '--no-recurse-submodules'
option." no one here's getting paid by the word.

rday

Re: [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely

[Damien Robert]

From Damien Robert, Tue 03 Mar 2020 at 18:07:38 (+0100) :
> +	When set to true, it can be deactivated by calling
> +	`--no-recurse-submodules`. Note that some Git commands without this
> +	option may call some of the above commands affected by
> +	`submodule.recurse`; for instance `git remote update` will call
> +	`git fetch` but does not have a `--no-recurse-submodules` option.
> +	since `submodule.recurse`. In this case a solution is to temporary
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
Sorry this is a leftover from a previous formulation, I'll clean that up.

> +	change the configuration value by using `git -c submodule.recurse=0`.

Re: [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely

[Philippe Blain]

> Le 3 mars 2020 à 17:04, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
>> +	since `submodule.recurse`. In this case a solution is to temporary
>        ^^^^^^^^^^^^^^^^^^^^^^^^^^
> Sorry this is a leftover from a previous formulation, I'll clean that up.

Also, the commit title still has the option name reversed:
s/recurse.submodule/submodule.recurse/

[PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Damien Robert]

The default value also depends on the value of submodule.recurse.

Also mention `fetch.recurseSubmodules` in fetch-options.txt. In
git-push.txt, `push.recurseSubmodules` is implicitly mentioned (by
explaining how to disable it), so no need to add it there.

Lastly add a link to `git-fetch` in `git-pull.txt` to explain the
meaning of `--recurse-submodules` there.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/fetch.txt  | 6 ++++--
 Documentation/config/push.txt   | 3 +++
 Documentation/fetch-options.txt | 3 ++-
 Documentation/git-pull.txt      | 3 +--
 4 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
index f11940280f..8f716809f9 100644
--- a/Documentation/config/fetch.txt
+++ b/Documentation/config/fetch.txt
@@ -2,10 +2,12 @@ fetch.recurseSubmodules::
 	This option can be either set to a boolean value or to 'on-demand'.
 	Setting it to a boolean changes the behavior of fetch and pull to
 	unconditionally recurse into submodules when set to true or to not
-	recurse at all when set to false. When set to 'on-demand' (the default
-	value), fetch and pull will only recurse into a populated submodule
+	recurse at all when set to false. When set to 'on-demand', 
+	fetch and pull will only recurse into a populated submodule
 	when its superproject retrieves a commit that updates the submodule's
 	reference.
+	If not set, it fallbacks to the value of `submodule.recurse`, and
+	if both are not set the default value is 'on-demand'.
 
 fetch.fsckObjects::
 	If it is set to true, git-fetch-pack will check all fetched
diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt
index 54871f8213..2a5250cf5c 100644
--- a/Documentation/config/push.txt
+++ b/Documentation/config/push.txt
@@ -112,3 +112,6 @@ push.recurseSubmodules::
 	is 'no' then default behavior of ignoring submodules when pushing
 	is retained. You may override this configuration at time of push by
 	specifying '--recurse-submodules=check|on-demand|no'.
+	If not set, it fallbacks to the value of `submodule.recurse` (where
+	a 'true' value means 'on-demand'), and if both are not set the
+	default value is 'no'.
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index a115a1ae0e..58972b1a05 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -163,7 +163,8 @@ ifndef::git-pull[]
 	value. Use 'on-demand' to only recurse into a populated submodule
 	when the superproject retrieves a commit that updates the submodule's
 	reference to a commit that isn't already in the local submodule
-	clone.
+	clone. By default this uses the fetch.recurseSubmodules value (see
+	linkgit:git-config), and the default value is 'on-demand'.
 
 -j::
 --jobs=<n>::
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index dfb901f8b8..47bc4a7061 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -86,8 +86,7 @@ OPTIONS
 
 --[no-]recurse-submodules[=yes|on-demand|no]::
 	This option controls if new commits of all populated submodules should
-	be fetched and updated, too (see linkgit:git-config[1] and
-	linkgit:gitmodules[5]).
+	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
 +
 If the checkout is done via rebase, local submodule commits are rebased as well.
 +
-- 
Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)

Re: [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Junio C Hamano]

Damien Robert <damien.olivier.robert@gmail.com> writes:

> diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
> index f11940280f..8f716809f9 100644
> --- a/Documentation/config/fetch.txt
> +++ b/Documentation/config/fetch.txt
> @@ -2,10 +2,12 @@ fetch.recurseSubmodules::
>  	This option can be either set to a boolean value or to 'on-demand'.
>  	Setting it to a boolean changes the behavior of fetch and pull to
>  	unconditionally recurse into submodules when set to true or to not
> -	recurse at all when set to false. When set to 'on-demand' (the default
> -	value), fetch and pull will only recurse into a populated submodule
> +	recurse at all when set to false. When set to 'on-demand', 
> +	fetch and pull will only recurse into a populated submodule
>  	when its superproject retrieves a commit that updates the submodule's
>  	reference.
> +	If not set, it fallbacks to the value of `submodule.recurse`, and
> +	if both are not set the default value is 'on-demand'.

I do not think "fallback" is a single-word verb.  If you must use
the phrase, "it falls back to the value of ...", but I personally
prefer to give the simplest case first and then its variants second
(i.e. if you do not do anything, this is what you get, and then if
you do this thing, this other thing happens).

In other words:

	If not set, 'on-demand' is used by default, unless
	'submodule.recurse' is set, in which case it is used.

But in this case it is so obvious that it would not be necessary to
add ", in which case it is used" at the end.

> diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt
> index 54871f8213..2a5250cf5c 100644
> --- a/Documentation/config/push.txt
> +++ b/Documentation/config/push.txt
> @@ -112,3 +112,6 @@ push.recurseSubmodules::
>  	is 'no' then default behavior of ignoring submodules when pushing
>  	is retained. You may override this configuration at time of push by
>  	specifying '--recurse-submodules=check|on-demand|no'.
> +	If not set, it fallbacks to the value of `submodule.recurse` (where
> +	a 'true' value means 'on-demand'), and if both are not set the
> +	default value is 'no'.

Likewise.

> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
> index a115a1ae0e..58972b1a05 100644
> --- a/Documentation/fetch-options.txt
> +++ b/Documentation/fetch-options.txt
> @@ -163,7 +163,8 @@ ifndef::git-pull[]
>  	value. Use 'on-demand' to only recurse into a populated submodule
>  	when the superproject retrieves a commit that updates the submodule's
>  	reference to a commit that isn't already in the local submodule
> -	clone.
> +	clone. By default this uses the fetch.recurseSubmodules value (see
> +	linkgit:git-config), and the default value is 'on-demand'.

	By default, 'on-demand' is used, unless
	`fetch.recurseSubmodules` is set (see linkgit:git-config[1]).

Re: [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Robert P. J. Day]

On Tue, 3 Mar 2020, Junio C Hamano wrote:

> Damien Robert <damien.olivier.robert@gmail.com> writes:
>
> > diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
> > index f11940280f..8f716809f9 100644
> > --- a/Documentation/config/fetch.txt
> > +++ b/Documentation/config/fetch.txt
> > @@ -2,10 +2,12 @@ fetch.recurseSubmodules::
> >  	This option can be either set to a boolean value or to 'on-demand'.
> >  	Setting it to a boolean changes the behavior of fetch and pull to
> >  	unconditionally recurse into submodules when set to true or to not
> > -	recurse at all when set to false. When set to 'on-demand' (the default
> > -	value), fetch and pull will only recurse into a populated submodule
> > +	recurse at all when set to false. When set to 'on-demand',
> > +	fetch and pull will only recurse into a populated submodule
> >  	when its superproject retrieves a commit that updates the submodule's
> >  	reference.
> > +	If not set, it fallbacks to the value of `submodule.recurse`, and
> > +	if both are not set the default value is 'on-demand'.

  missed earlier post ... "either set" should be "set either." also,
adverbs technically *follow* what they qualify, so "unconditionally
recusrse" should be "recurse unconditionally" and so on.

  it has always been thus.

rday

p.s. avoid use of the word "it" if it's potentially unclear what it
refers to. in the above, one reads, "If not set, it falls back ..."

*what* falls back?

[PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules

[Damien Robert]

The documentation refers to "initialized" or "populated" submodules,
to explain which submodules are affected by '--recurse-submodules', but
the real terminology here is 'active' submodules. Update the
documentation accordingly.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/fetch-options.txt | 6 +++---
 Documentation/git-checkout.txt  | 2 +-
 Documentation/git-grep.txt      | 2 +-
 Documentation/git-pull.txt      | 2 +-
 Documentation/git-read-tree.txt | 2 +-
 Documentation/git-switch.txt    | 2 +-
 6 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 58972b1a05..ba33009253 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -156,11 +156,11 @@ ifndef::git-pull[]
 
 --recurse-submodules[=yes|on-demand|no]::
 	This option controls if and under what conditions new commits of
-	populated submodules should be fetched too. It can be used as a
+	active submodules should be fetched too. It can be used as a
 	boolean option to completely disable recursion when set to 'no' or to
-	unconditionally recurse into all populated submodules when set to
+	unconditionally recurse into all active submodules when set to
 	'yes', which is the default when this option is used without any
-	value. Use 'on-demand' to only recurse into a populated submodule
+	value. Use 'on-demand' to only recurse into a active submodule
 	when the superproject retrieves a commit that updates the submodule's
 	reference to a commit that isn't already in the local submodule
 	clone. By default this uses the fetch.recurseSubmodules value (see
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c8fb995fa7..3be0a28284 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also
 
 --recurse-submodules::
 --no-recurse-submodules::
-	Using `--recurse-submodules` will update the content of all initialized
+	Using `--recurse-submodules` will update the content of all active
 	submodules according to the commit recorded in the superproject. If
 	local modifications in a submodule would be overwritten the checkout
 	will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index ddb6acc025..cdf8e26b47 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -93,7 +93,7 @@ OPTIONS
 	with `--no-index`.
 
 --recurse-submodules::
-	Recursively search in each submodule that has been initialized and
+	Recursively search in each submodule that is active and
 	checked out in the repository.  When used in combination with the
 	<tree> option the prefix of all submodule output will be the name of
 	the parent project's <tree> object. This option has no effect
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 47bc4a7061..2285f3729d 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -85,7 +85,7 @@ OPTIONS
 	Pass --verbose to git-fetch and git-merge.
 
 --[no-]recurse-submodules[=yes|on-demand|no]::
-	This option controls if new commits of all populated submodules should
+	This option controls if new commits of all active submodules should
 	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
 +
 If the checkout is done via rebase, local submodule commits are rebased as well.
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index da33f84f33..aab6856341 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -116,7 +116,7 @@ OPTIONS
 	located in.
 
 --[no-]recurse-submodules::
-	Using --recurse-submodules will update the content of all initialized
+	Using --recurse-submodules will update the content of all active
 	submodules according to the commit recorded in the superproject by
 	calling read-tree recursively, also setting the submodules HEAD to be
 	detached at that commit.
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index 197900363b..337852d86b 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -181,7 +181,7 @@ name, the guessing is aborted.  You can explicitly give a name with
 --recurse-submodules::
 --no-recurse-submodules::
 	Using `--recurse-submodules` will update the content of all
-	initialized submodules according to the commit recorded in the
+	active submodules according to the commit recorded in the
 	superproject. If nothing (or `--no-recurse-submodules`) is
 	used, the work trees of submodules will not be updated. Just
 	like linkgit:git-submodule[1], this will detach `HEAD` of the
-- 
Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1)

Re: [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules

[Philippe Blain]

In the commit title: s/apply/applies

> Le 3 mars 2020 à 12:07, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> The documentation refers to "initialized" or "populated" submodules,
> to explain which submodules are affected by '--recurse-submodules', but
> the real terminology here is 'active' submodules. Update the
> documentation accordingly.

Initialized, active and populated, as far as I understand, are three different concepts.
- Active is defined in gitsubmodules(7), it only involves the configuration variables 'submodule.active', 
'submodule.<name>.active' and 'submodule.<name>.url'. The function 
submodule.c::is_submodule_active checks that a submodule is active.
- My understanding is that "populated" means that the submodule's working tree is 
present (and the gitfile correctly points to the submodule repository), 
i.e. either the superproject was cloned with ` --recurse-submodules`, or
the user ran `git submodule update --init`, or `git submodule init [<path>]` and `git submodule update [<path]`
separately which populated the submodule working tree. 
This does not involve the 3 configuration variables above.
- My understanding is that "initialized" (at least in the context of the man pages involved in this patch) means 
both "populated" and "active" as defined above, i.e. what `git submodule update --init` does.

> 
> Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
> ---
> Documentation/fetch-options.txt | 6 +++---
> Documentation/git-checkout.txt  | 2 +-
> Documentation/git-grep.txt      | 2 +-
> Documentation/git-pull.txt      | 2 +-
> Documentation/git-read-tree.txt | 2 +-
> Documentation/git-switch.txt    | 2 +-
> 6 files changed, 8 insertions(+), 8 deletions(-)

What about ls-files ? builtin/ls-files.c:231 indicates that it does call
submodule.c::is_submodule_active, so its doc should also be updated.

> 
> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
> index 58972b1a05..ba33009253 100644
> --- a/Documentation/fetch-options.txt
> +++ b/Documentation/fetch-options.txt
> @@ -156,11 +156,11 @@ ifndef::git-pull[]

From what I understand of the code, git-fetch really recurses into *populated* submodules,
and does not consult the submodule.active or submodule.<name>.active config settings.
If you look at builtin/fetch.c::cmd_fetch, and the functions it calls, but is_submodule_active is not in the call chain.
I tested that setting submodule.<name>.active to false and calling 

    git fetch --recurse-submodules=yes

still fetches in the submodule(s). So this should stay as "populated".

> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index c8fb995fa7..3be0a28284 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also
> 
> --recurse-submodules::
> --no-recurse-submodules::
> -	Using `--recurse-submodules` will update the content of all initialized
> +	Using `--recurse-submodules` will update the content of all active
> 	submodules according to the commit recorded in the superproject. If
> 	local modifications in a submodule would be overwritten the checkout
> 	will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)

That's correct as checkout uses the unpack-trees machinery,
which calls submodule_move_head, and submodule_move_head calls 
is_submodule_active (submodule.c:1894).

> diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
> index ddb6acc025..cdf8e26b47 100644
> --- a/Documentation/git-grep.txt
> +++ b/Documentation/git-grep.txt
> @@ -93,7 +93,7 @@ OPTIONS
> 	with `--no-index`.
> 
> --recurse-submodules::
> -	Recursively search in each submodule that has been initialized and
> +	Recursively search in each submodule that is active and
> 	checked out in the repository.  When used in combination with the
> 	<tree> option the prefix of all submodule output will be the name of
> 	the parent project's <tree> object. This option has no effect

That's correct (builtin/grep.c:423).

> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
> index 47bc4a7061..2285f3729d 100644
> --- a/Documentation/git-pull.txt
> +++ b/Documentation/git-pull.txt
> @@ -85,7 +85,7 @@ OPTIONS
> 	Pass --verbose to git-fetch and git-merge.
> 
> --[no-]recurse-submodules[=yes|on-demand|no]::
> -	This option controls if new commits of all populated submodules should
> +	This option controls if new commits of all active submodules should
> 	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
> +
> If the checkout is done via rebase, local submodule commits are rebased as well.

That's only partly correct: I tested setting submodule.<name>.active to false and doing

    git pull --recurse-submodules

This does fetches the submodule but does not update its working tree, due to the call to 
is_submodule_active in prepare_to_clone_next_submodule in builtin/submodule--helper.c

> diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
> index da33f84f33..aab6856341 100644
> --- a/Documentation/git-read-tree.txt
> +++ b/Documentation/git-read-tree.txt
> @@ -116,7 +116,7 @@ OPTIONS
> 	located in.
> 
> --[no-]recurse-submodules::
> -	Using --recurse-submodules will update the content of all initialized
> +	Using --recurse-submodules will update the content of all active
> 	submodules according to the commit recorded in the superproject by
> 	calling read-tree recursively, also setting the submodules HEAD to be
> 	detached at that commit.

`read-tree` is also in the unpack-trees machinery, so that's correct.

> diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
> index 197900363b..337852d86b 100644
> --- a/Documentation/git-switch.txt
> +++ b/Documentation/git-switch.txt
> @@ -181,7 +181,7 @@ name, the guessing is aborted.  You can explicitly give a name with
> --recurse-submodules::
> --no-recurse-submodules::
> 	Using `--recurse-submodules` will update the content of all
> -	initialized submodules according to the commit recorded in the
> +	active submodules according to the commit recorded in the
> 	superproject. If nothing (or `--no-recurse-submodules`) is
> 	used, the work trees of submodules will not be updated. Just
> 	like linkgit:git-submodule[1], this will detach `HEAD` of the

`switch` is `checkout <branch>` under the hood, so that's also correct.

In light of these facts, I think the commit title should be :
doc: --recurse-submodules mostly applies to active submodules

Re: [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules

[Damien Robert]

From Philippe Blain, Thu 05 Mar 2020 at 23:17:54 (-0500) :
> In the commit title: s/apply/applies

Oups, missed this one.

> Initialized, active and populated, as far as I understand, are three different concepts.
[...]

> From what I understand of the code, git-fetch really recurses into *populated* submodules,
> and does not consult the submodule.active or submodule.<name>.active config settings.
> If you look at builtin/fetch.c::cmd_fetch, and the functions it calls, but is_submodule_active is not in the call chain.
> I tested that setting submodule.<name>.active to false and calling 
> 
>     git fetch --recurse-submodules=yes
> 
> still fetches in the submodule(s). So this should stay as "populated".

Thanks for the thorough review! I had tested that `git-pull` was only
updating the worktree of active submodules, but missed that it was still
fetching non active submodules.

In light of this I think this is even more important to mention which
command affects which submodules in the doc.

> That's only partly correct: I tested setting submodule.<name>.active to false and doing
> 
>     git pull --recurse-submodules
> 
> This does fetches the submodule but does not update its working tree, due to the call to 
> is_submodule_active in prepare_to_clone_next_submodule in builtin/submodule--helper.c

I still left 'active submodule' here in order to not render the formulation
too heavy. Since it is implicit that `pull` goes through fetch, I hope it
is clear that the fetching still involves all populated submodules.

-- 
Damien Robert
http://www.normalesup.org/~robert/pro

[PATCH v3 0/5] doc: --recurse-submodules

[Damien Robert]

This is v3, incorporating all remarks received:
- The typos mistakes mentioned by Robert and Junio.
- The main change is patch 5/5 where I incorporated the nice explanations of
  Philippe Blain.

Damien Robert (5):
  doc: list all commands affected by submodule.recurse
  doc: document --recurse-submodules for reset and restore
  doc: explain how to deactivate submodule.recurse completely
  doc: be more precise on (fetch|push).recurseSubmodules
  doc: --recurse-submodules mostly only apply to active submodules

 Documentation/config/fetch.txt     | 10 ++++++----
 Documentation/config/push.txt      |  2 ++
 Documentation/config/submodule.txt | 12 ++++++++++--
 Documentation/fetch-options.txt    |  3 ++-
 Documentation/git-checkout.txt     |  2 +-
 Documentation/git-grep.txt         |  2 +-
 Documentation/git-ls-files.txt     |  2 +-
 Documentation/git-pull.txt         |  5 ++---
 Documentation/git-read-tree.txt    |  2 +-
 Documentation/git-reset.txt        |  6 ++++++
 Documentation/git-restore.txt      | 10 ++++++++++
 Documentation/git-switch.txt       |  2 +-
 Documentation/gitsubmodules.txt    |  3 ++-
 13 files changed, 45 insertions(+), 16 deletions(-)

-- 
Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)

[PATCH v3 1/5] doc: list all commands affected by submodule.recurse

[Damien Robert]

Note that `ls-files` is not affected, even though it has a
`--recurse-submodules` option, so list it as an exception too.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/submodule.txt | 5 +++--
 Documentation/gitsubmodules.txt    | 3 ++-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index b33177151c..5962f41ead 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -59,8 +59,9 @@ submodule.active::
 
 submodule.recurse::
 	Specifies if commands recurse into submodules by default. This
-	applies to all commands that have a `--recurse-submodules` option,
-	except `clone`.
+	applies to all commands that have a `--recurse-submodules` option
+	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
+	`restore` and `switch`) except `clone` and `ls-files`.
 	Defaults to false.
 
 submodule.fetchJobs::
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index c476f891b5..f9f4e65c9e 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse
 into submodules. The 'init' and 'update' subcommands of 'git submodule'
 will maintain submodules checked out and at an appropriate revision in
 your working tree. Alternatively you can set 'submodule.recurse' to have
-'checkout' recursing into submodules.
+'checkout' recursing into submodules (note that 'submodule.recurse' also
+affects other git commands, see linkgit:git-config[1] for a complete list).
 
 
 SEE ALSO
-- 
Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)

[PATCH v3 2/5] doc: document --recurse-submodules for reset and restore

[Damien Robert]

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/git-reset.txt   |  6 ++++++
 Documentation/git-restore.txt | 10 ++++++++++
 2 files changed, 16 insertions(+)

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 932080c55d..c8623cfc34 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -87,6 +87,12 @@ but carries forward unmerged index entries.
 	different between `<commit>` and `HEAD`.
 	If a file that is different between `<commit>` and `HEAD` has local
 	changes, reset is aborted.
+
+--[no-]recurse-submodules::
+	When the working tree is updated, using --recurse-submodules will
+	also recursively reset the working tree of all active submodules
+	according to the commit recorded in the superproject, also setting
+	the submodules HEAD to be detached at that commit.
 --
 
 See "Reset, restore and revert" in linkgit:git[1] for the differences
diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
index 5bf60d4943..47f31d4a0f 100644
--- a/Documentation/git-restore.txt
+++ b/Documentation/git-restore.txt
@@ -107,6 +107,16 @@ in linkgit:git-checkout[1] for details.
 	patterns and unconditionally restores any files in
 	`<pathspec>`.
 
+--recurse-submodules::
+--no-recurse-submodules::
+	If `<pathspec>` names a submodule and the restore location includes
+	the working tree, the submodule will only be updated if this option
+	is given, in which case its working tree will be restored to the
+	commit recorded in the superproject, and any local modifications
+	overwritten. If nothing (or `--no-recurse-submodules`) is used,
+	the work trees of submodules will not be updated. Just like
+	linkgit:git-checkout[1], this will detach `HEAD` of the submodule.
+
 --overlay::
 --no-overlay::
 	In overlay mode, the command never removes files when
-- 
Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)

Re: [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore

[Philippe Blain]

> Le 20 mars 2020 à 17:37, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
> ---
> Documentation/git-reset.txt   |  6 ++++++
> Documentation/git-restore.txt | 10 ++++++++++
> 2 files changed, 16 insertions(+)
> 
> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
> index 932080c55d..c8623cfc34 100644
> --- a/Documentation/git-reset.txt
> +++ b/Documentation/git-reset.txt
> @@ -87,6 +87,12 @@ but carries forward unmerged index entries.
> 	different between `<commit>` and `HEAD`.
> 	If a file that is different between `<commit>` and `HEAD` has local
> 	changes, reset is aborted.
> +
> +--[no-]recurse-submodules::
> +	When the working tree is updated, using --recurse-submodules will
> +	also recursively reset the working tree of all active submodules
> +	according to the commit recorded in the superproject, also setting
> +	the submodules HEAD to be detached at that commit.

I *think* that should be "the submodules' HEADs" but I'd prefer that a native speaker confirm.

> --
> 
> See "Reset, restore and revert" in linkgit:git[1] for the differences
> diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
> index 5bf60d4943..47f31d4a0f 100644
> --- a/Documentation/git-restore.txt
> +++ b/Documentation/git-restore.txt
> @@ -107,6 +107,16 @@ in linkgit:git-checkout[1] for details.
> 	patterns and unconditionally restores any files in
> 	`<pathspec>`.
> 
> +--recurse-submodules::
> +--no-recurse-submodules::
> +	If `<pathspec>` names a submodule and the restore location includes

To be consistent with patch 5, I think that should be "names an active submodule".
(restore is in the unpack-trees machinery so that would be correct; I checked this behaviour).

> +	the working tree, the submodule will only be updated if this option
> +	is given, in which case its working tree will be restored to the
> +	commit recorded in the superproject, and any local modifications
> +	overwritten. If nothing (or `--no-recurse-submodules`) is used,
> +	the work trees of submodules will not be updated. Just like

For consistency I'd use "working trees" here also, as in the first sentence. 
In fact I think it would read better as "submodules working trees will not be updated".

Re: [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore

[Damien Robert]

From Philippe Blain, Sun 22 Mar 2020 at 18:36:23 (-0400) :
> > +--[no-]recurse-submodules::
> > +	When the working tree is updated, using --recurse-submodules will
> > +	also recursively reset the working tree of all active submodules
> > +	according to the commit recorded in the superproject, also setting
> > +	the submodules HEAD to be detached at that commit.

> I *think* that should be "the submodules' HEADs" but I'd prefer that a native speaker confirm.

This was copied from read-tree. So I'll update it too in my next reroll.

> > +	the working tree, the submodule will only be updated if this option
> > +	is given, in which case its working tree will be restored to the
> > +	commit recorded in the superproject, and any local modifications
> > +	overwritten. If nothing (or `--no-recurse-submodules`) is used,
> > +	the work trees of submodules will not be updated. Just like
 
> For consistency I'd use "working trees" here also, as in the first sentence. 
> In fact I think it would read better as "submodules working trees will not be updated".

Likewise, this was copied from checkout (and switch). I'll update all of
them.

-- 
Damien Robert
http://www.normalesup.org/~robert/pro

[PATCH v3 3/5] doc: explain how to deactivate submodule.recurse completely

[Damien Robert]

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/submodule.txt | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index 5962f41ead..900d374385 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -63,6 +63,13 @@ submodule.recurse::
 	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
 	`restore` and `switch`) except `clone` and `ls-files`.
 	Defaults to false.
+	When set to true, it can be deactivated via the
+	`--no-recurse-submodules` option. Note that some Git commands
+	without this option may call some of the above commands affected by
+	`submodule.recurse`; for instance `git remote update` will call
+	`git fetch` but does not have a `--no-recurse-submodules` option.
+	In this case a solution is to temporary change the configuration
+	value by using `git -c submodule.recurse=0`.
 
 submodule.fetchJobs::
 	Specifies how many submodules are fetched/cloned at the same time.
-- 
Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)

Re: [PATCH v3 3/5] doc: explain how to deactivate submodule.recurse completely

[Philippe Blain]

> Le 20 mars 2020 à 17:37, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> +	When set to true, it can be deactivated via the
> +	`--no-recurse-submodules` option. Note that some Git commands
> +	without this option may call some of the above commands affected by

For clarity I'd write "some Git commands lacking this option" instead,  as "without this option" 
*could* be interpreted as "invoked without this option".

> +	`submodule.recurse`; for instance `git remote update` will call
> +	`git fetch` but does not have a `--no-recurse-submodules` option.
> +	In this case a solution

I'm not sure "solution" is the best word here, maybe:

"For these commands a workaround is to temporarily change the configuration..."

Note: s/temporary/temporarily/

> is to temporary change the configuration
> +	value by using `git -c submodule.recurse=0`.

[PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Damien Robert]

The default value also depends on the value of submodule.recurse.
Use this opportunity to correct some grammar mistakes in
Documentation/config/fetch.txt signaled by Robert P. J. Day.

Also mention `fetch.recurseSubmodules` in fetch-options.txt. In
git-push.txt, `push.recurseSubmodules` is implicitly mentioned (by
explaining how to disable it), so no need to add it there.

Lastly add a link to `git-fetch` in `git-pull.txt` to explain the
meaning of `--recurse-submodules` there.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/fetch.txt  | 10 ++++++----
 Documentation/config/push.txt   |  2 ++
 Documentation/fetch-options.txt |  3 ++-
 Documentation/git-pull.txt      |  3 +--
 4 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
index f11940280f..8778a99fa6 100644
--- a/Documentation/config/fetch.txt
+++ b/Documentation/config/fetch.txt
@@ -1,11 +1,13 @@
 fetch.recurseSubmodules::
-	This option can be either set to a boolean value or to 'on-demand'.
+	This option can be set either to a boolean value or to 'on-demand'.
 	Setting it to a boolean changes the behavior of fetch and pull to
-	unconditionally recurse into submodules when set to true or to not
-	recurse at all when set to false. When set to 'on-demand' (the default
-	value), fetch and pull will only recurse into a populated submodule
+	recurse unconditionally into submodules when set to true or to not
+	recurse at all when set to false. When set to 'on-demand',
+	fetch and pull will only recurse into a populated submodule
 	when its superproject retrieves a commit that updates the submodule's
 	reference.
+	If not set, 'on-demand' is used by default, unless
+	'submodule.recurse' is set.
 
 fetch.fsckObjects::
 	If it is set to true, git-fetch-pack will check all fetched
diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt
index 0a7aa322a9..f5e5b38c68 100644
--- a/Documentation/config/push.txt
+++ b/Documentation/config/push.txt
@@ -112,3 +112,5 @@ push.recurseSubmodules::
 	is 'no' then default behavior of ignoring submodules when pushing
 	is retained. You may override this configuration at time of push by
 	specifying '--recurse-submodules=check|on-demand|no'.
+	If not set, 'no' is used by default, unless 'submodule.recurse' is
+	set (in which case a 'true' value means 'on-demand').
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index a115a1ae0e..b1058d63bc 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -163,7 +163,8 @@ ifndef::git-pull[]
 	value. Use 'on-demand' to only recurse into a populated submodule
 	when the superproject retrieves a commit that updates the submodule's
 	reference to a commit that isn't already in the local submodule
-	clone.
+	clone. By default, 'on-demand' is used, unless
+	`fetch.recurseSubmodules` is set (see linkgit:git-config[1]).
 
 -j::
 --jobs=<n>::
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index dfb901f8b8..47bc4a7061 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -86,8 +86,7 @@ OPTIONS
 
 --[no-]recurse-submodules[=yes|on-demand|no]::
 	This option controls if new commits of all populated submodules should
-	be fetched and updated, too (see linkgit:git-config[1] and
-	linkgit:gitmodules[5]).
+	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
 +
 If the checkout is done via rebase, local submodule commits are rebased as well.
 +
-- 
Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)

Re: [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Philippe Blain]

> Le 20 mars 2020 à 17:37, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
> index f11940280f..8778a99fa6 100644
> --- a/Documentation/config/fetch.txt
> +++ b/Documentation/config/fetch.txt
> @@ -1,11 +1,13 @@
> fetch.recurseSubmodules::
> -	This option can be either set to a boolean value or to 'on-demand'.
> +	This option can be set either to a boolean value or to 'on-demand'.
> 	Setting it to a boolean changes the behavior of fetch and pull to

I think in the context of patch 5 maybe it would be good to be careful here, 
and state that this only affects the underlying "fetch" in "pull", and not the whole pull ?

> -	unconditionally recurse into submodules when set to true or to not
> -	recurse at all when set to false. When set to 'on-demand' (the default
> -	value), fetch and pull will only recurse into a populated submodule
> +	recurse unconditionally into submodules when set to true or to not
> +	recurse at all when set to false. When set to 'on-demand',
> +	fetch and pull will only recurse into a populated submodule
> 	when its superproject retrieves a commit that updates the submodule's
> 	reference.
> +	If not set, 'on-demand' is used by default, unless
> +	'submodule.recurse' is set.

I know Junio seems to think otherwise, but to me it would be clearer if this would be 
clearly spelled out: 

Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.

Re: [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Junio C Hamano]

Philippe Blain <levraiphilippeblain@gmail.com> writes:

>> -	This option can be either set to a boolean value or to 'on-demand'.
>> +	This option can be set either to a boolean value or to 'on-demand'.
>> 	Setting it to a boolean changes the behavior of fetch and pull to
>
> I think in the context of patch 5 maybe it would be good to be
> careful here, and state that this only affects the underlying
> "fetch" in "pull", and not the whole pull ?

Meaning that sub(sub)*modules are fetched but the merge is done only
for the top-level superproject?  I guess it does not hurt to spell
it out.  Good suggestion.

>> +	If not set, 'on-demand' is used by default, unless
>> +	'submodule.recurse' is set.
>
> I know Junio seems to think otherwise, but to me it would be
> clearer if this would be clearly spelled out:
>
> Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.

Well, between the above two, I'd actually have slight preference to
yours, but they both look clear enough to almost the same degree, at
least to me.

Thanks.

Re: [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Philippe Blain]

> Le 22 mars 2020 à 19:01, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> Philippe Blain <levraiphilippeblain@gmail.com> writes:
> 
>>> -	This option can be either set to a boolean value or to 'on-demand'.
>>> +	This option can be set either to a boolean value or to 'on-demand'.
>>> 	Setting it to a boolean changes the behavior of fetch and pull to
>> 
>> I think in the context of patch 5 maybe it would be good to be
>> careful here, and state that this only affects the underlying
>> "fetch" in "pull", and not the whole pull ?
> 
> Meaning that sub(sub)*modules are fetched but the merge is done only
> for the top-level superproject?  I guess it does not hurt to spell
> it out.  Good suggestion.

I simply meant that since this option is 'fetch.recurseSubmodules', it applies
to the fetching operation done by 'git pull' under the hood, and not to the
 "updating the working tree" operation that is also done by git pull if 
'--recurse-submodules' is passed to it.

Regarding nested submodules, both operations would recurse down the hierarchy:
the fetching fetches all (nested) populated submodules because of the call to 
submodule.c::fetch_populated_submodules near the end of builtin/fetch.c::cmd_fetch 
and the "updating the working tree", which is controlled 
by the '--recurse-submodules' flag of 'git pull',  updates all active submodules  
because it spawns 'git submodule update --recursive', (as per rebase_submodules
and update_submodules in builtin/pull.c).

[PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules

[Damien Robert]

The documentation refers to "initialized" or "populated" submodules,
to explain which submodules are affected by '--recurse-submodules', but
the real terminology here is 'active' submodules. Update the
documentation accordingly.

Some terminology:
- Active is defined in gitsubmodules(7), it only involves the
  configuration variables 'submodule.active', 'submodule.<name>.active'
  and 'submodule.<name>.url'. The function
  submodule.c::is_submodule_active checks that a submodule is active.
- Populated means that the submodule's working tree is present (and the
  gitfile correctly points to the submodule repository), i.e. either the
  superproject was cloned with ` --recurse-submodules`, or the user ran
  `git submodule update --init`, or `git submodule init [<path>]` and
  `git submodule update [<path]` separately which populated the
  submodule working tree. This does not involve the 3 configuration
  variables above.
- Initialized (at least in the context of the man pages involved in this
  patch) means both "populated" and "active" as defined above, i.e. what
  `git submodule update --init` does.

The --recurse-submodules option mostly affects submodules. An exception
is `git fetch` where the option affects populated submodules.
As a consequence, in `git pull` the fetch affects populated submodules,
but the resulting working tree update only affects active submodules.

In the documentation of `git-pull` we only refer to active submodules,
since it is implicit that the fetching behaviour is governed by the
fetch command.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
Helped-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 Documentation/git-checkout.txt  | 2 +-
 Documentation/git-grep.txt      | 2 +-
 Documentation/git-ls-files.txt  | 2 +-
 Documentation/git-pull.txt      | 2 +-
 Documentation/git-read-tree.txt | 2 +-
 Documentation/git-switch.txt    | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c8fb995fa7..3be0a28284 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also
 
 --recurse-submodules::
 --no-recurse-submodules::
-	Using `--recurse-submodules` will update the content of all initialized
+	Using `--recurse-submodules` will update the content of all active
 	submodules according to the commit recorded in the superproject. If
 	local modifications in a submodule would be overwritten the checkout
 	will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index ddb6acc025..cdf8e26b47 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -93,7 +93,7 @@ OPTIONS
 	with `--no-index`.
 
 --recurse-submodules::
-	Recursively search in each submodule that has been initialized and
+	Recursively search in each submodule that is active and
 	checked out in the repository.  When used in combination with the
 	<tree> option the prefix of all submodule output will be the name of
 	the parent project's <tree> object. This option has no effect
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 8461c0e83e..3cb2ebb438 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -148,7 +148,7 @@ a space) at the start of each line:
 	top directory.
 
 --recurse-submodules::
-	Recursively calls ls-files on each submodule in the repository.
+	Recursively calls ls-files on each active submodule in the repository.
 	Currently there is only support for the --cached mode.
 
 --abbrev[=<n>]::
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 47bc4a7061..2285f3729d 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -85,7 +85,7 @@ OPTIONS
 	Pass --verbose to git-fetch and git-merge.
 
 --[no-]recurse-submodules[=yes|on-demand|no]::
-	This option controls if new commits of all populated submodules should
+	This option controls if new commits of all active submodules should
 	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
 +
 If the checkout is done via rebase, local submodule commits are rebased as well.
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index da33f84f33..aab6856341 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -116,7 +116,7 @@ OPTIONS
 	located in.
 
 --[no-]recurse-submodules::
-	Using --recurse-submodules will update the content of all initialized
+	Using --recurse-submodules will update the content of all active
 	submodules according to the commit recorded in the superproject by
 	calling read-tree recursively, also setting the submodules HEAD to be
 	detached at that commit.
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index 197900363b..337852d86b 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -181,7 +181,7 @@ name, the guessing is aborted.  You can explicitly give a name with
 --recurse-submodules::
 --no-recurse-submodules::
 	Using `--recurse-submodules` will update the content of all
-	initialized submodules according to the commit recorded in the
+	active submodules according to the commit recorded in the
 	superproject. If nothing (or `--no-recurse-submodules`) is
 	used, the work trees of submodules will not be updated. Just
 	like linkgit:git-submodule[1], this will detach `HEAD` of the
-- 
Patched on top of v2.26.0-rc2-27-gbe8661a328 (git version 2.25.2)

Re: [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules

[Philippe Blain]

> Le 20 mars 2020 à 17:37, Damien Robert <damien.olivier.robert@gmail.com> a écrit

in the title, I'd drop the "only"
"mostly only apply" -> "mostly applies"

> :
> 
> The documentation refers to "initialized" or "populated" submodules,
> to explain which submodules are affected by '--recurse-submodules', but
> the real terminology here is 'active' submodules. Update the
> documentation accordingly.
> 
> Some terminology:
> - Active is defined in gitsubmodules(7), it only involves the
>  configuration variables 'submodule.active', 'submodule.<name>.active'
>  and 'submodule.<name>.url'. The function
>  submodule.c::is_submodule_active checks that a submodule is active.
> - Populated means that the submodule's working tree is present (and the
>  gitfile correctly points to the submodule repository), i.e. either the
>  superproject was cloned with ` --recurse-submodules`, or the user ran
>  `git submodule update --init`, or `git submodule init [<path>]` and
>  `git submodule update [<path]`

missing a closing '>' here (my mistake).

> separately which populated the
>  submodule working tree. This does not involve the 3 configuration
>  variables above.
> - Initialized (at least in the context of the man pages involved in this
>  patch) means both "populated" and "active" as defined above, i.e. what
>  `git submodule update --init` does.
> 
> The --recurse-submodules option mostly affects submodules.

I think you meant  "mostly affects active submodules" here, right?

> An exception
> is `git fetch` where the option affects populated submodules.
> As a consequence, in `git pull` the fetch affects populated submodules,
> but the resulting working tree update only affects active submodules.
> 
> In the documentation of `git-pull` we only refer to active submodules,
> since it is implicit that the fetching behaviour is governed by the
> fetch command.

This last paragraph is not a description of the current state of the code base, 
but describes the changes introduced by this patch. As such, it's customary
to write it in the imperative mode. A simple suggestion to fix that:

s/we/let's/

> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
> index 47bc4a7061..2285f3729d 100644
> --- a/Documentation/git-pull.txt
> +++ b/Documentation/git-pull.txt
> @@ -85,7 +85,7 @@ OPTIONS
> 	Pass --verbose to git-fetch and git-merge.
> 
> --[no-]recurse-submodules[=yes|on-demand|no]::
> -	This option controls if new commits of all populated submodules should
> +	This option controls if new commits of all active submodules should
> 	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).

I understand that the goal here is to make the formulation not too heavy, as you wrote in 
https://lore.kernel.org/git/20200320222328.lynvrgqc35pvxxnl@doriath/. However I think the formulation 
is awkward to begin with : commits are "fetched", but commits are not "updated", the submodules working tree 
are updated. So maybe:

This option controls if new commits of populated submodules should be fetched, 
and if the working trees of active submodules should be updated, too

[PATCH v4 0/5] doc: --recurse-submodules

[Damien Robert]

No big changes this time, I just incorporated the latest round of remarks.
(A big thanks to Philippe Blain for these!)

Damien Robert (5):
  doc: list all commands affected by submodule.recurse
  doc: document --recurse-submodules for reset and restore
  doc: explain how to deactivate submodule.recurse completely
  doc: be more precise on (fetch|push).recurseSubmodules
  doc: --recurse-submodules mostly applies to active submodules

 Documentation/config/fetch.txt     |  9 +++++----
 Documentation/config/push.txt      |  2 ++
 Documentation/config/submodule.txt | 12 ++++++++++--
 Documentation/fetch-options.txt    |  3 ++-
 Documentation/git-checkout.txt     |  4 ++--
 Documentation/git-grep.txt         |  2 +-
 Documentation/git-ls-files.txt     |  2 +-
 Documentation/git-pull.txt         |  5 +++--
 Documentation/git-read-tree.txt    |  4 ++--
 Documentation/git-reset.txt        |  6 ++++++
 Documentation/git-restore.txt      | 11 +++++++++++
 Documentation/git-switch.txt       |  4 ++--
 Documentation/gitsubmodules.txt    |  3 ++-
 13 files changed, 49 insertions(+), 18 deletions(-)

-- 
Patched on top of v2.26.0 (git version 2.25.2)

[PATCH v4 1/5] doc: list all commands affected by submodule.recurse

[Damien Robert]

Note that `ls-files` is not affected, even though it has a
`--recurse-submodules` option, so list it as an exception too.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/submodule.txt | 5 +++--
 Documentation/gitsubmodules.txt    | 3 ++-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index b33177151c..5962f41ead 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -59,8 +59,9 @@ submodule.active::
 
 submodule.recurse::
 	Specifies if commands recurse into submodules by default. This
-	applies to all commands that have a `--recurse-submodules` option,
-	except `clone`.
+	applies to all commands that have a `--recurse-submodules` option
+	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
+	`restore` and `switch`) except `clone` and `ls-files`.
 	Defaults to false.
 
 submodule.fetchJobs::
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index c476f891b5..f9f4e65c9e 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse
 into submodules. The 'init' and 'update' subcommands of 'git submodule'
 will maintain submodules checked out and at an appropriate revision in
 your working tree. Alternatively you can set 'submodule.recurse' to have
-'checkout' recursing into submodules.
+'checkout' recursing into submodules (note that 'submodule.recurse' also
+affects other git commands, see linkgit:git-config[1] for a complete list).
 
 
 SEE ALSO
-- 
Patched on top of v2.26.0 (git version 2.25.2)

[PATCH v4 2/5] doc: document --recurse-submodules for reset and restore

[Damien Robert]

Also unify the formulation about --no-submodules for checkout and
switch, which we reuse for restore.

And correct the formulation about submodules' HEAD in read-tree, which
we reuse in reset.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/git-checkout.txt  |  2 +-
 Documentation/git-read-tree.txt |  2 +-
 Documentation/git-reset.txt     |  6 ++++++
 Documentation/git-restore.txt   | 11 +++++++++++
 Documentation/git-switch.txt    |  2 +-
 5 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c8fb995fa7..140bd3eabb 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -296,7 +296,7 @@ Note that this option uses the no overlay mode by default (see also
 	submodules according to the commit recorded in the superproject. If
 	local modifications in a submodule would be overwritten the checkout
 	will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)
-	is used, the work trees of submodules will not be updated.
+	is used, submodules working trees will not be updated.
 	Just like linkgit:git-submodule[1], this will detach `HEAD` of the
 	submodule.
 
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index da33f84f33..807cad4691 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -118,7 +118,7 @@ OPTIONS
 --[no-]recurse-submodules::
 	Using --recurse-submodules will update the content of all initialized
 	submodules according to the commit recorded in the superproject by
-	calling read-tree recursively, also setting the submodules HEAD to be
+	calling read-tree recursively, also setting the submodules' HEADs to be
 	detached at that commit.
 
 --no-sparse-checkout::
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 932080c55d..d7a09f11a0 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -87,6 +87,12 @@ but carries forward unmerged index entries.
 	different between `<commit>` and `HEAD`.
 	If a file that is different between `<commit>` and `HEAD` has local
 	changes, reset is aborted.
+
+--[no-]recurse-submodules::
+	When the working tree is updated, using --recurse-submodules will
+	also recursively reset the working tree of all active submodules
+	according to the commit recorded in the superproject, also setting
+	the submodules' HEADs to be detached at that commit.
 --
 
 See "Reset, restore and revert" in linkgit:git[1] for the differences
diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
index 5bf60d4943..8e3b339802 100644
--- a/Documentation/git-restore.txt
+++ b/Documentation/git-restore.txt
@@ -107,6 +107,17 @@ in linkgit:git-checkout[1] for details.
 	patterns and unconditionally restores any files in
 	`<pathspec>`.
 
+--recurse-submodules::
+--no-recurse-submodules::
+	If `<pathspec>` names an active submodule and the restore location
+	includes the working tree, the submodule will only be updated if
+	this option is given, in which case its working tree will be
+	restored to the commit recorded in the superproject, and any local
+	modifications overwritten. If nothing (or
+	`--no-recurse-submodules`) is used, submodules working trees will
+	not be updated. Just like linkgit:git-checkout[1], this will detach
+	`HEAD` of the submodule.
+
 --overlay::
 --no-overlay::
 	In overlay mode, the command never removes files when
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index 197900363b..79dbc9624d 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -183,7 +183,7 @@ name, the guessing is aborted.  You can explicitly give a name with
 	Using `--recurse-submodules` will update the content of all
 	initialized submodules according to the commit recorded in the
 	superproject. If nothing (or `--no-recurse-submodules`) is
-	used, the work trees of submodules will not be updated. Just
+	used, submodules working trees will not be updated. Just
 	like linkgit:git-submodule[1], this will detach `HEAD` of the
 	submodules.
 
-- 
Patched on top of v2.26.0 (git version 2.25.2)

Re: [PATCH v4 2/5] doc: document --recurse-submodules for reset and restore

[Philippe Blain]

> Le 25 mars 2020 à 17:09, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> Also unify the formulation about --no-submodules

that should be '--no-recurse-submodules'

> for checkout and
> switch, which we reuse for restore.
> 
> And correct the formulation about submodules' HEAD in read-tree, which
> we reuse in reset.
> 
> Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
> ---
> Documentation/git-checkout.txt  |  2 +-
> Documentation/git-read-tree.txt |  2 +-
> Documentation/git-reset.txt     |  6 ++++++
> Documentation/git-restore.txt   | 11 +++++++++++
> Documentation/git-switch.txt    |  2 +-
> 5 files changed, 20 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index c8fb995fa7..140bd3eabb 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -296,7 +296,7 @@ Note that this option uses the no overlay mode by default (see also
> 	submodules according to the commit recorded in the superproject. If
> 	local modifications in a submodule would be overwritten the checkout
> 	will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)
> -	is used, the work trees of submodules will not be updated.
> +	is used, submodules working trees will not be updated.
> 	Just like linkgit:git-submodule[1], this will detach `HEAD` of the
> 	submodule.
> 
> diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
> index da33f84f33..807cad4691 100644
> --- a/Documentation/git-read-tree.txt
> +++ b/Documentation/git-read-tree.txt
> @@ -118,7 +118,7 @@ OPTIONS
> --[no-]recurse-submodules::
> 	Using --recurse-submodules will update the content of all initialized
> 	submodules according to the commit recorded in the superproject by
> -	calling read-tree recursively, also setting the submodules HEAD to be
> +	calling read-tree recursively, also setting the submodules' HEADs to be

I've rethought about that and I think it should be "submodules' HEAD" (sorry!)

> 	detached at that commit.
> 
> --no-sparse-checkout::
> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
> index 932080c55d..d7a09f11a0 100644
> --- a/Documentation/git-reset.txt
> +++ b/Documentation/git-reset.txt
> @@ -87,6 +87,12 @@ but carries forward unmerged index entries.
> 	different between `<commit>` and `HEAD`.
> 	If a file that is different between `<commit>` and `HEAD` has local
> 	changes, reset is aborted.
> +
> +--[no-]recurse-submodules::
> +	When the working tree is updated, using --recurse-submodules will
> +	also recursively reset the working tree of all active submodules
> +	according to the commit recorded in the superproject, also setting
> +	the submodules' HEADs to be detached at that commit.

same here

> --
> 
> See "Reset, restore and revert" in linkgit:git[1] for the differences
> diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
> index 5bf60d4943..8e3b339802 100644
> --- a/Documentation/git-restore.txt
> +++ b/Documentation/git-restore.txt
> @@ -107,6 +107,17 @@ in linkgit:git-checkout[1] for details.
> 	patterns and unconditionally restores any files in
> 	`<pathspec>`.
> 
> +--recurse-submodules::
> +--no-recurse-submodules::
> +	If `<pathspec>` names an active submodule and the restore location
> +	includes the working tree, the submodule will only be updated if
> +	this option is given, in which case its working tree will be
> +	restored to the commit recorded in the superproject, and any local
> +	modifications overwritten. If nothing (or
> +	`--no-recurse-submodules`) is used, submodules working trees will
> +	not be updated. Just like linkgit:git-checkout[1], this will detach
> +	`HEAD` of the submodule.
> +
> --overlay::
> --no-overlay::
> 	In overlay mode, the command never removes files when
> diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
> index 197900363b..79dbc9624d 100644
> --- a/Documentation/git-switch.txt
> +++ b/Documentation/git-switch.txt
> @@ -183,7 +183,7 @@ name, the guessing is aborted.  You can explicitly give a name with
> 	Using `--recurse-submodules` will update the content of all
> 	initialized submodules according to the commit recorded in the
> 	superproject. If nothing (or `--no-recurse-submodules`) is
> -	used, the work trees of submodules will not be updated. Just
> +	used, submodules working trees will not be updated. Just
> 	like linkgit:git-submodule[1], this will detach `HEAD` of the
> 	submodules.
> 
> -- 
> Patched on top of v2.26.0 (git version 2.25.2)
> 

[PATCH v4 3/5] doc: explain how to deactivate submodule.recurse completely

[Damien Robert]

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/submodule.txt | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index 5962f41ead..d7a63c8c12 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -63,6 +63,13 @@ submodule.recurse::
 	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
 	`restore` and `switch`) except `clone` and `ls-files`.
 	Defaults to false.
+	When set to true, it can be deactivated via the
+	`--no-recurse-submodules` option. Note that some Git commands
+	lacking this option may call some of the above commands affected by
+	`submodule.recurse`; for instance `git remote update` will call
+	`git fetch` but does not have a `--no-recurse-submodules` option.
+	For these commands a workaround is to temporarily change the
+	configuration value by using `git -c submodule.recurse=0`.
 
 submodule.fetchJobs::
 	Specifies how many submodules are fetched/cloned at the same time.
-- 
Patched on top of v2.26.0 (git version 2.25.2)

[PATCH v4 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Damien Robert]

The default value also depends on the value of submodule.recurse.
Use this opportunity to correct some grammar mistakes in
Documentation/config/fetch.txt signaled by Robert P. J. Day.

Also mention `fetch.recurseSubmodules` in fetch-options.txt. In
git-push.txt, `push.recurseSubmodules` is implicitly mentioned (by
explaining how to disable it), so no need to add it there.

Lastly add a link to `git-fetch` in `git-pull.txt` to explain the
meaning of `--recurse-submodules` there.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/fetch.txt  | 9 +++++----
 Documentation/config/push.txt   | 2 ++
 Documentation/fetch-options.txt | 3 ++-
 Documentation/git-pull.txt      | 3 +--
 4 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
index f11940280f..cd5b1417c4 100644
--- a/Documentation/config/fetch.txt
+++ b/Documentation/config/fetch.txt
@@ -1,11 +1,12 @@
 fetch.recurseSubmodules::
-	This option can be either set to a boolean value or to 'on-demand'.
+	This option can be set either to a boolean value or to 'on-demand'.
 	Setting it to a boolean changes the behavior of fetch and pull to
-	unconditionally recurse into submodules when set to true or to not
-	recurse at all when set to false. When set to 'on-demand' (the default
-	value), fetch and pull will only recurse into a populated submodule
+	recurse unconditionally into submodules when set to true or to not
+	recurse at all when set to false. When set to 'on-demand',
+	fetch and pull will only recurse fetching into a populated submodule
 	when its superproject retrieves a commit that updates the submodule's
 	reference.
+	Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.
 
 fetch.fsckObjects::
 	If it is set to true, git-fetch-pack will check all fetched
diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt
index 0a7aa322a9..f5e5b38c68 100644
--- a/Documentation/config/push.txt
+++ b/Documentation/config/push.txt
@@ -112,3 +112,5 @@ push.recurseSubmodules::
 	is 'no' then default behavior of ignoring submodules when pushing
 	is retained. You may override this configuration at time of push by
 	specifying '--recurse-submodules=check|on-demand|no'.
+	If not set, 'no' is used by default, unless 'submodule.recurse' is
+	set (in which case a 'true' value means 'on-demand').
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index a115a1ae0e..b1058d63bc 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -163,7 +163,8 @@ ifndef::git-pull[]
 	value. Use 'on-demand' to only recurse into a populated submodule
 	when the superproject retrieves a commit that updates the submodule's
 	reference to a commit that isn't already in the local submodule
-	clone.
+	clone. By default, 'on-demand' is used, unless
+	`fetch.recurseSubmodules` is set (see linkgit:git-config[1]).
 
 -j::
 --jobs=<n>::
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index dfb901f8b8..47bc4a7061 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -86,8 +86,7 @@ OPTIONS
 
 --[no-]recurse-submodules[=yes|on-demand|no]::
 	This option controls if new commits of all populated submodules should
-	be fetched and updated, too (see linkgit:git-config[1] and
-	linkgit:gitmodules[5]).
+	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
 +
 If the checkout is done via rebase, local submodule commits are rebased as well.
 +
-- 
Patched on top of v2.26.0 (git version 2.25.2)

Re: [PATCH v4 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Philippe Blain]

> Le 25 mars 2020 à 17:09, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> The default value also depends on the value of submodule.recurse.
> Use this opportunity to correct some grammar mistakes in
> Documentation/config/fetch.txt signaled by Robert P. J. Day.
> 
> Also mention `fetch.recurseSubmodules` in fetch-options.txt. In
> git-push.txt, `push.recurseSubmodules` is implicitly mentioned (by
> explaining how to disable it), so no need to add it there.
> 
> Lastly add a link to `git-fetch` in `git-pull.txt` to explain the
> meaning of `--recurse-submodules` there.
> 
> Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
> ---
> Documentation/config/fetch.txt  | 9 +++++----
> Documentation/config/push.txt   | 2 ++
> Documentation/fetch-options.txt | 3 ++-
> Documentation/git-pull.txt      | 3 +--
> 4 files changed, 10 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
> index f11940280f..cd5b1417c4 100644
> --- a/Documentation/config/fetch.txt
> +++ b/Documentation/config/fetch.txt
> @@ -1,11 +1,12 @@
> fetch.recurseSubmodules::
> -	This option can be either set to a boolean value or to 'on-demand'.
> +	This option can be set either to a boolean value or to 'on-demand'.
> 	Setting it to a boolean changes the behavior of fetch and pull to
> -	unconditionally recurse into submodules when set to true or to not
> -	recurse at all when set to false. When set to 'on-demand' (the default
> -	value), fetch and pull will only recurse into a populated submodule
> +	recurse unconditionally into submodules when set to true or to not
> +	recurse at all when set to false. When set to 'on-demand',
> +	fetch and pull will only recurse fetching into a populated submodule

The chosen formulation seems to imply that only for "on-demand" will fetch and pull
recursively *fetch* in submodules, which is misleading. I think it might be clearer to just
add a sentence at the start :

This option controls whether `git fetch` (and the underlying fetch in `git pull`) 
will recursively fetch into populated submodules.
This option can be set either to a boolean value or to 'on-demand'.
Setting it to a boolean changes the behavior of fetch and pull to recurse unconditionally 
into submodules when set to true or to not recurse at all when set to false.
When set to on-demand, fetch and pull will only recurse into a populated submodule 
when its superproject retrieves a commit that updates the submodule’s reference.


> 	when its superproject retrieves a commit that updates the submodule's
> 	reference.
> +	Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.
> 
> fetch.fsckObjects::
> 	If it is set to true, git-fetch-pack will check all fetched
> diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt
> index 0a7aa322a9..f5e5b38c68 100644
> --- a/Documentation/config/push.txt
> +++ b/Documentation/config/push.txt
> @@ -112,3 +112,5 @@ push.recurseSubmodules::
> 	is 'no' then default behavior of ignoring submodules when pushing
> 	is retained. You may override this configuration at time of push by
> 	specifying '--recurse-submodules=check|on-demand|no'.
> +	If not set, 'no' is used by default, unless 'submodule.recurse' is
> +	set (in which case a 'true' value means 'on-demand').
> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
> index a115a1ae0e..b1058d63bc 100644
> --- a/Documentation/fetch-options.txt
> +++ b/Documentation/fetch-options.txt
> @@ -163,7 +163,8 @@ ifndef::git-pull[]
> 	value. Use 'on-demand' to only recurse into a populated submodule
> 	when the superproject retrieves a commit that updates the submodule's
> 	reference to a commit that isn't already in the local submodule
> -	clone.
> +	clone. By default, 'on-demand' is used, unless
> +	`fetch.recurseSubmodules` is set (see linkgit:git-config[1]).
> 
> -j::
> --jobs=<n>::
> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
> index dfb901f8b8..47bc4a7061 100644
> --- a/Documentation/git-pull.txt
> +++ b/Documentation/git-pull.txt
> @@ -86,8 +86,7 @@ OPTIONS
> 
> --[no-]recurse-submodules[=yes|on-demand|no]::
> 	This option controls if new commits of all populated submodules should
> -	be fetched and updated, too (see linkgit:git-config[1] and
> -	linkgit:gitmodules[5]).
> +	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
> +
> If the checkout is done via rebase, local submodule commits are rebased as well.
> +
> -- 
> Patched on top of v2.26.0 (git version 2.25.2)
> 

[PATCH v4 5/5] doc: --recurse-submodules mostly applies to active submodules

[Damien Robert]

The documentation refers to "initialized" or "populated" submodules,
to explain which submodules are affected by '--recurse-submodules', but
the real terminology here is 'active' submodules. Update the
documentation accordingly.

Some terminology:
- Active is defined in gitsubmodules(7), it only involves the
  configuration variables 'submodule.active', 'submodule.<name>.active'
  and 'submodule.<name>.url'. The function
  submodule.c::is_submodule_active checks that a submodule is active.
- Populated means that the submodule's working tree is present (and the
  gitfile correctly points to the submodule repository), i.e. either the
  superproject was cloned with ` --recurse-submodules`, or the user ran
  `git submodule update --init`, or `git submodule init [<path>]` and
  `git submodule update [<path>]` separately which populated the
  submodule working tree. This does not involve the 3 configuration
  variables above.
- Initialized (at least in the context of the man pages involved in this
  patch) means both "populated" and "active" as defined above, i.e. what
  `git submodule update --init` does.

The --recurse-submodules option mostly affects active submodules. An
exception is `git fetch` where the option affects populated submodules.
As a consequence, in `git pull --recurse-submodules` the fetch affects
populated submodules, but the resulting working tree update only affects
active submodules.

In the documentation of `git-pull`, let's distinguish between the
fetching part which affects populated submodules, and the updating of
worktrees, which only affects active submodules.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
Helped-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 Documentation/git-checkout.txt  | 2 +-
 Documentation/git-grep.txt      | 2 +-
 Documentation/git-ls-files.txt  | 2 +-
 Documentation/git-pull.txt      | 6 ++++--
 Documentation/git-read-tree.txt | 2 +-
 Documentation/git-switch.txt    | 2 +-
 6 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 140bd3eabb..5b697eee1b 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also
 
 --recurse-submodules::
 --no-recurse-submodules::
-	Using `--recurse-submodules` will update the content of all initialized
+	Using `--recurse-submodules` will update the content of all active
 	submodules according to the commit recorded in the superproject. If
 	local modifications in a submodule would be overwritten the checkout
 	will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index ddb6acc025..cdf8e26b47 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -93,7 +93,7 @@ OPTIONS
 	with `--no-index`.
 
 --recurse-submodules::
-	Recursively search in each submodule that has been initialized and
+	Recursively search in each submodule that is active and
 	checked out in the repository.  When used in combination with the
 	<tree> option the prefix of all submodule output will be the name of
 	the parent project's <tree> object. This option has no effect
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 8461c0e83e..3cb2ebb438 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -148,7 +148,7 @@ a space) at the start of each line:
 	top directory.
 
 --recurse-submodules::
-	Recursively calls ls-files on each submodule in the repository.
+	Recursively calls ls-files on each active submodule in the repository.
 	Currently there is only support for the --cached mode.
 
 --abbrev[=<n>]::
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 47bc4a7061..b336df00c7 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -85,8 +85,10 @@ OPTIONS
 	Pass --verbose to git-fetch and git-merge.
 
 --[no-]recurse-submodules[=yes|on-demand|no]::
-	This option controls if new commits of all populated submodules should
-	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
+	This option controls if new commits of populated submodules should
+	be fetched, and if the working trees of active submodules should be
+	updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and
+	linkgit:gitmodules[5]).
 +
 If the checkout is done via rebase, local submodule commits are rebased as well.
 +
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 807cad4691..a2350994ee 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -116,7 +116,7 @@ OPTIONS
 	located in.
 
 --[no-]recurse-submodules::
-	Using --recurse-submodules will update the content of all initialized
+	Using --recurse-submodules will update the content of all active
 	submodules according to the commit recorded in the superproject by
 	calling read-tree recursively, also setting the submodules' HEADs to be
 	detached at that commit.
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index 79dbc9624d..3759c3a265 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -181,7 +181,7 @@ name, the guessing is aborted.  You can explicitly give a name with
 --recurse-submodules::
 --no-recurse-submodules::
 	Using `--recurse-submodules` will update the content of all
-	initialized submodules according to the commit recorded in the
+	active submodules according to the commit recorded in the
 	superproject. If nothing (or `--no-recurse-submodules`) is
 	used, submodules working trees will not be updated. Just
 	like linkgit:git-submodule[1], this will detach `HEAD` of the
-- 
Patched on top of v2.26.0 (git version 2.25.2)

[PATCH v5 0/5] doc: --recurse-submodules

[Damien Robert]

Sorry it took me a while, I have been busy.
I incorporated the two remarks by Philippe Blain on v4.

We are converging!

Damien Robert (5):
  doc: list all commands affected by submodule.recurse
  doc: document --recurse-submodules for reset and restore
  doc: explain how to deactivate submodule.recurse completely
  doc: be more precise on (fetch|push).recurseSubmodules
  doc: --recurse-submodules mostly applies to active submodules

 Documentation/config/fetch.txt     | 13 ++++++++-----
 Documentation/config/push.txt      |  2 ++
 Documentation/config/submodule.txt | 12 ++++++++++--
 Documentation/fetch-options.txt    |  3 ++-
 Documentation/git-checkout.txt     |  4 ++--
 Documentation/git-grep.txt         |  2 +-
 Documentation/git-ls-files.txt     |  2 +-
 Documentation/git-pull.txt         |  5 +++--
 Documentation/git-read-tree.txt    |  4 ++--
 Documentation/git-reset.txt        |  6 ++++++
 Documentation/git-restore.txt      | 11 +++++++++++
 Documentation/git-switch.txt       |  4 ++--
 Documentation/gitsubmodules.txt    |  3 ++-
 13 files changed, 52 insertions(+), 19 deletions(-)

-- 
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)

[PATCH v5 1/5] doc: list all commands affected by submodule.recurse

[Damien Robert]

Note that `ls-files` is not affected, even though it has a
`--recurse-submodules` option, so list it as an exception too.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/submodule.txt | 5 +++--
 Documentation/gitsubmodules.txt    | 3 ++-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index b33177151c..5962f41ead 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -59,8 +59,9 @@ submodule.active::
 
 submodule.recurse::
 	Specifies if commands recurse into submodules by default. This
-	applies to all commands that have a `--recurse-submodules` option,
-	except `clone`.
+	applies to all commands that have a `--recurse-submodules` option
+	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
+	`restore` and `switch`) except `clone` and `ls-files`.
 	Defaults to false.
 
 submodule.fetchJobs::
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index c476f891b5..f9f4e65c9e 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse
 into submodules. The 'init' and 'update' subcommands of 'git submodule'
 will maintain submodules checked out and at an appropriate revision in
 your working tree. Alternatively you can set 'submodule.recurse' to have
-'checkout' recursing into submodules.
+'checkout' recursing into submodules (note that 'submodule.recurse' also
+affects other git commands, see linkgit:git-config[1] for a complete list).
 
 
 SEE ALSO
-- 
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)

[PATCH v5 2/5] doc: document --recurse-submodules for reset and restore

[Damien Robert]

Also unify the formulation about --no-recurse-submodules for checkout
and switch, which we reuse for restore.

And correct the formulation about submodules' HEAD in read-tree, which
we reuse in reset.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/git-checkout.txt  |  2 +-
 Documentation/git-read-tree.txt |  2 +-
 Documentation/git-reset.txt     |  6 ++++++
 Documentation/git-restore.txt   | 11 +++++++++++
 Documentation/git-switch.txt    |  2 +-
 5 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c8fb995fa7..140bd3eabb 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -296,7 +296,7 @@ Note that this option uses the no overlay mode by default (see also
 	submodules according to the commit recorded in the superproject. If
 	local modifications in a submodule would be overwritten the checkout
 	will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)
-	is used, the work trees of submodules will not be updated.
+	is used, submodules working trees will not be updated.
 	Just like linkgit:git-submodule[1], this will detach `HEAD` of the
 	submodule.
 
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index da33f84f33..501f2ec375 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -118,7 +118,7 @@ OPTIONS
 --[no-]recurse-submodules::
 	Using --recurse-submodules will update the content of all initialized
 	submodules according to the commit recorded in the superproject by
-	calling read-tree recursively, also setting the submodules HEAD to be
+	calling read-tree recursively, also setting the submodules' HEAD to be
 	detached at that commit.
 
 --no-sparse-checkout::
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 932080c55d..252e2d4e47 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -87,6 +87,12 @@ but carries forward unmerged index entries.
 	different between `<commit>` and `HEAD`.
 	If a file that is different between `<commit>` and `HEAD` has local
 	changes, reset is aborted.
+
+--[no-]recurse-submodules::
+	When the working tree is updated, using --recurse-submodules will
+	also recursively reset the working tree of all active submodules
+	according to the commit recorded in the superproject, also setting
+	the submodules' HEAD to be detached at that commit.
 --
 
 See "Reset, restore and revert" in linkgit:git[1] for the differences
diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
index 5bf60d4943..8e3b339802 100644
--- a/Documentation/git-restore.txt
+++ b/Documentation/git-restore.txt
@@ -107,6 +107,17 @@ in linkgit:git-checkout[1] for details.
 	patterns and unconditionally restores any files in
 	`<pathspec>`.
 
+--recurse-submodules::
+--no-recurse-submodules::
+	If `<pathspec>` names an active submodule and the restore location
+	includes the working tree, the submodule will only be updated if
+	this option is given, in which case its working tree will be
+	restored to the commit recorded in the superproject, and any local
+	modifications overwritten. If nothing (or
+	`--no-recurse-submodules`) is used, submodules working trees will
+	not be updated. Just like linkgit:git-checkout[1], this will detach
+	`HEAD` of the submodule.
+
 --overlay::
 --no-overlay::
 	In overlay mode, the command never removes files when
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index 197900363b..79dbc9624d 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -183,7 +183,7 @@ name, the guessing is aborted.  You can explicitly give a name with
 	Using `--recurse-submodules` will update the content of all
 	initialized submodules according to the commit recorded in the
 	superproject. If nothing (or `--no-recurse-submodules`) is
-	used, the work trees of submodules will not be updated. Just
+	used, submodules working trees will not be updated. Just
 	like linkgit:git-submodule[1], this will detach `HEAD` of the
 	submodules.
 
-- 
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)

[PATCH v5 3/5] doc: explain how to deactivate submodule.recurse completely

[Damien Robert]

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/submodule.txt | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index 5962f41ead..d7a63c8c12 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -63,6 +63,13 @@ submodule.recurse::
 	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
 	`restore` and `switch`) except `clone` and `ls-files`.
 	Defaults to false.
+	When set to true, it can be deactivated via the
+	`--no-recurse-submodules` option. Note that some Git commands
+	lacking this option may call some of the above commands affected by
+	`submodule.recurse`; for instance `git remote update` will call
+	`git fetch` but does not have a `--no-recurse-submodules` option.
+	For these commands a workaround is to temporarily change the
+	configuration value by using `git -c submodule.recurse=0`.
 
 submodule.fetchJobs::
 	Specifies how many submodules are fetched/cloned at the same time.
-- 
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)

[PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Damien Robert]

The default value also depends on the value of submodule.recurse.
Use this opportunity to correct some grammar mistakes in
Documentation/config/fetch.txt signaled by Robert P. J. Day.

Also mention `fetch.recurseSubmodules` in fetch-options.txt. In
git-push.txt, `push.recurseSubmodules` is implicitly mentioned (by
explaining how to disable it), so no need to add it there.

Lastly add a link to `git-fetch` in `git-pull.txt` to explain the
meaning of `--recurse-submodules` there.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/fetch.txt  | 13 ++++++++-----
 Documentation/config/push.txt   |  2 ++
 Documentation/fetch-options.txt |  3 ++-
 Documentation/git-pull.txt      |  3 +--
 4 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
index f11940280f..4114af4b3b 100644
--- a/Documentation/config/fetch.txt
+++ b/Documentation/config/fetch.txt
@@ -1,11 +1,14 @@
 fetch.recurseSubmodules::
-	This option can be either set to a boolean value or to 'on-demand'.
+	This option controls whether `git fetch` (and the underlying fetch
+	in `git pull`) will recursively fetch into populated submodules.
+	This option can be set either to a boolean value or to 'on-demand'.
 	Setting it to a boolean changes the behavior of fetch and pull to
-	unconditionally recurse into submodules when set to true or to not
-	recurse at all when set to false. When set to 'on-demand' (the default
-	value), fetch and pull will only recurse into a populated submodule
-	when its superproject retrieves a commit that updates the submodule's
+	recurse unconditionally into submodules when set to true or to not
+	recurse at all when set to false. When set to on-demand, fetch and
+	pull will only recurse into a populated submodule when its
+	superproject retrieves a commit that updates the submodule's
 	reference.
+	Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.
 
 fetch.fsckObjects::
 	If it is set to true, git-fetch-pack will check all fetched
diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt
index 0a7aa322a9..f5e5b38c68 100644
--- a/Documentation/config/push.txt
+++ b/Documentation/config/push.txt
@@ -112,3 +112,5 @@ push.recurseSubmodules::
 	is 'no' then default behavior of ignoring submodules when pushing
 	is retained. You may override this configuration at time of push by
 	specifying '--recurse-submodules=check|on-demand|no'.
+	If not set, 'no' is used by default, unless 'submodule.recurse' is
+	set (in which case a 'true' value means 'on-demand').
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 00d03ec8c3..833f935cd0 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -163,7 +163,8 @@ ifndef::git-pull[]
 	value. Use 'on-demand' to only recurse into a populated submodule
 	when the superproject retrieves a commit that updates the submodule's
 	reference to a commit that isn't already in the local submodule
-	clone.
+	clone. By default, 'on-demand' is used, unless
+	`fetch.recurseSubmodules` is set (see linkgit:git-config[1]).
 endif::git-pull[]
 
 -j::
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index dfb901f8b8..47bc4a7061 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -86,8 +86,7 @@ OPTIONS
 
 --[no-]recurse-submodules[=yes|on-demand|no]::
 	This option controls if new commits of all populated submodules should
-	be fetched and updated, too (see linkgit:git-config[1] and
-	linkgit:gitmodules[5]).
+	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
 +
 If the checkout is done via rebase, local submodule commits are rebased as well.
 +
-- 
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)

Re: [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Junio C Hamano]

Damien Robert <damien.olivier.robert@gmail.com> writes:

> The default value also depends on the value of submodule.recurse.
> Use this opportunity to correct some grammar mistakes in
> Documentation/config/fetch.txt signaled by Robert P. J. Day.
>
> Also mention `fetch.recurseSubmodules` in fetch-options.txt. In
> git-push.txt, `push.recurseSubmodules` is implicitly mentioned (by
> explaining how to disable it), so no need to add it there.
>
> Lastly add a link to `git-fetch` in `git-pull.txt` to explain the
> meaning of `--recurse-submodules` there.
>
> Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
> ---
>  Documentation/config/fetch.txt  | 13 ++++++++-----
>  Documentation/config/push.txt   |  2 ++
>  Documentation/fetch-options.txt |  3 ++-
>  Documentation/git-pull.txt      |  3 +--
>  4 files changed, 13 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
> index f11940280f..4114af4b3b 100644
> --- a/Documentation/config/fetch.txt
> +++ b/Documentation/config/fetch.txt
> @@ -1,11 +1,14 @@
>  fetch.recurseSubmodules::
> -	This option can be either set to a boolean value or to 'on-demand'.
> +	This option controls whether `git fetch` (and the underlying fetch
> +	in `git pull`) will recursively fetch into populated submodules.
> +	This option can be set either to a boolean value or to 'on-demand'.
>  	Setting it to a boolean changes the behavior of fetch and pull to
> -	unconditionally recurse into submodules when set to true or to not
> -	recurse at all when set to false. When set to 'on-demand' (the default
> -	value), fetch and pull will only recurse into a populated submodule
> -	when its superproject retrieves a commit that updates the submodule's
> +	recurse unconditionally into submodules when set to true or to not
> +	recurse at all when set to false. When set to on-demand, fetch and

Why did you lose quotes around on-demand on this line?  Shouldn't it
be typeset the same way as the other one in the sentence "Defaults
to ..."?

> +	pull will only recurse into a populated submodule when its
> +	superproject retrieves a commit that updates the submodule's
>  	reference.
> +	Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.

Re: [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Damien Robert]

From Junio C Hamano, Sun 05 Apr 2020 at 14:57:22 (-0700) :
> Why did you lose quotes around on-demand on this line?  Shouldn't it
> be typeset the same way as the other one in the sentence "Defaults
> to ..."?

Yes it should, sorry it's my mistake, I'll send a new version.

Re: [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Junio C Hamano]

Damien Robert <damien.olivier.robert@gmail.com> writes:

> From Junio C Hamano, Sun 05 Apr 2020 at 14:57:22 (-0700) :
>> Why did you lose quotes around on-demand on this line?  Shouldn't it
>> be typeset the same way as the other one in the sentence "Defaults
>> to ..."?
>
> Yes it should, sorry it's my mistake, I'll send a new version.

Thanks.  You may want to wait a bit so that (1) others can spot
similar mistakes, if any, in the version on the list and (2) you
yourself find some similar errors while waiting for others.

Re: [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Damien Robert]

From Junio C Hamano, Mon 06 Apr 2020 at 10:56:49 (-0700) :
> Thanks.  You may want to wait a bit so that (1) others can spot
> similar mistakes, if any, in the version on the list and (2) you
> yourself find some similar errors while waiting for others.

Well this was mainly the only change compared to v4 which was sent 10 days
ago. This change was suggested by Philippe Blain, so it has already been
read by him, me, you, and then me again when I sent v6 and checked
carefully I did not miss another quote around 'on-demand'.

Hopefully that will be enough :)

[PATCH v5 5/5] doc: --recurse-submodules mostly applies to active submodules

[Damien Robert]

The documentation refers to "initialized" or "populated" submodules,
to explain which submodules are affected by '--recurse-submodules', but
the real terminology here is 'active' submodules. Update the
documentation accordingly.

Some terminology:
- Active is defined in gitsubmodules(7), it only involves the
  configuration variables 'submodule.active', 'submodule.<name>.active'
  and 'submodule.<name>.url'. The function
  submodule.c::is_submodule_active checks that a submodule is active.
- Populated means that the submodule's working tree is present (and the
  gitfile correctly points to the submodule repository), i.e. either the
  superproject was cloned with ` --recurse-submodules`, or the user ran
  `git submodule update --init`, or `git submodule init [<path>]` and
  `git submodule update [<path>]` separately which populated the
  submodule working tree. This does not involve the 3 configuration
  variables above.
- Initialized (at least in the context of the man pages involved in this
  patch) means both "populated" and "active" as defined above, i.e. what
  `git submodule update --init` does.

The --recurse-submodules option mostly affects active submodules. An
exception is `git fetch` where the option affects populated submodules.
As a consequence, in `git pull --recurse-submodules` the fetch affects
populated submodules, but the resulting working tree update only affects
active submodules.

In the documentation of `git-pull`, let's distinguish between the
fetching part which affects populated submodules, and the updating of
worktrees, which only affects active submodules.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
Helped-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 Documentation/git-checkout.txt  | 2 +-
 Documentation/git-grep.txt      | 2 +-
 Documentation/git-ls-files.txt  | 2 +-
 Documentation/git-pull.txt      | 6 ++++--
 Documentation/git-read-tree.txt | 2 +-
 Documentation/git-switch.txt    | 2 +-
 6 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 140bd3eabb..5b697eee1b 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also
 
 --recurse-submodules::
 --no-recurse-submodules::
-	Using `--recurse-submodules` will update the content of all initialized
+	Using `--recurse-submodules` will update the content of all active
 	submodules according to the commit recorded in the superproject. If
 	local modifications in a submodule would be overwritten the checkout
 	will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index ddb6acc025..cdf8e26b47 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -93,7 +93,7 @@ OPTIONS
 	with `--no-index`.
 
 --recurse-submodules::
-	Recursively search in each submodule that has been initialized and
+	Recursively search in each submodule that is active and
 	checked out in the repository.  When used in combination with the
 	<tree> option the prefix of all submodule output will be the name of
 	the parent project's <tree> object. This option has no effect
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 8461c0e83e..3cb2ebb438 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -148,7 +148,7 @@ a space) at the start of each line:
 	top directory.
 
 --recurse-submodules::
-	Recursively calls ls-files on each submodule in the repository.
+	Recursively calls ls-files on each active submodule in the repository.
 	Currently there is only support for the --cached mode.
 
 --abbrev[=<n>]::
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 47bc4a7061..b336df00c7 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -85,8 +85,10 @@ OPTIONS
 	Pass --verbose to git-fetch and git-merge.
 
 --[no-]recurse-submodules[=yes|on-demand|no]::
-	This option controls if new commits of all populated submodules should
-	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
+	This option controls if new commits of populated submodules should
+	be fetched, and if the working trees of active submodules should be
+	updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and
+	linkgit:gitmodules[5]).
 +
 If the checkout is done via rebase, local submodule commits are rebased as well.
 +
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 501f2ec375..5fa8bab64c 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -116,7 +116,7 @@ OPTIONS
 	located in.
 
 --[no-]recurse-submodules::
-	Using --recurse-submodules will update the content of all initialized
+	Using --recurse-submodules will update the content of all active
 	submodules according to the commit recorded in the superproject by
 	calling read-tree recursively, also setting the submodules' HEAD to be
 	detached at that commit.
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index 79dbc9624d..3759c3a265 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -181,7 +181,7 @@ name, the guessing is aborted.  You can explicitly give a name with
 --recurse-submodules::
 --no-recurse-submodules::
 	Using `--recurse-submodules` will update the content of all
-	initialized submodules according to the commit recorded in the
+	active submodules according to the commit recorded in the
 	superproject. If nothing (or `--no-recurse-submodules`) is
 	used, submodules working trees will not be updated. Just
 	like linkgit:git-submodule[1], this will detach `HEAD` of the
-- 
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)

[PATCH v6 0/5] doc: --recurse-submodules

[Damien Robert]

Fix typo mentioned by Junio.

Damien Robert (5):
  doc: list all commands affected by submodule.recurse
  doc: document --recurse-submodules for reset and restore
  doc: explain how to deactivate submodule.recurse completely
  doc: be more precise on (fetch|push).recurseSubmodules
  doc: --recurse-submodules mostly applies to active submodules

 Documentation/config/fetch.txt     | 13 ++++++++-----
 Documentation/config/push.txt      |  2 ++
 Documentation/config/submodule.txt | 12 ++++++++++--
 Documentation/fetch-options.txt    |  3 ++-
 Documentation/git-checkout.txt     |  4 ++--
 Documentation/git-grep.txt         |  2 +-
 Documentation/git-ls-files.txt     |  2 +-
 Documentation/git-pull.txt         |  5 +++--
 Documentation/git-read-tree.txt    |  4 ++--
 Documentation/git-reset.txt        |  6 ++++++
 Documentation/git-restore.txt      | 11 +++++++++++
 Documentation/git-switch.txt       |  4 ++--
 Documentation/gitsubmodules.txt    |  3 ++-
 13 files changed, 52 insertions(+), 19 deletions(-)

-- 
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)

[PATCH v6 1/5] doc: list all commands affected by submodule.recurse

[Damien Robert]

Note that `ls-files` is not affected, even though it has a
`--recurse-submodules` option, so list it as an exception too.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/submodule.txt | 5 +++--
 Documentation/gitsubmodules.txt    | 3 ++-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index b33177151c..5962f41ead 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -59,8 +59,9 @@ submodule.active::
 
 submodule.recurse::
 	Specifies if commands recurse into submodules by default. This
-	applies to all commands that have a `--recurse-submodules` option,
-	except `clone`.
+	applies to all commands that have a `--recurse-submodules` option
+	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
+	`restore` and `switch`) except `clone` and `ls-files`.
 	Defaults to false.
 
 submodule.fetchJobs::
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index c476f891b5..f9f4e65c9e 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -271,7 +271,8 @@ will not be checked out by default; You can instruct 'clone' to recurse
 into submodules. The 'init' and 'update' subcommands of 'git submodule'
 will maintain submodules checked out and at an appropriate revision in
 your working tree. Alternatively you can set 'submodule.recurse' to have
-'checkout' recursing into submodules.
+'checkout' recursing into submodules (note that 'submodule.recurse' also
+affects other git commands, see linkgit:git-config[1] for a complete list).
 
 
 SEE ALSO
-- 
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)

[PATCH v6 2/5] doc: document --recurse-submodules for reset and restore

[Damien Robert]

Also unify the formulation about --no-recurse-submodules for checkout
and switch, which we reuse for restore.

And correct the formulation about submodules' HEAD in read-tree, which
we reuse in reset.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/git-checkout.txt  |  2 +-
 Documentation/git-read-tree.txt |  2 +-
 Documentation/git-reset.txt     |  6 ++++++
 Documentation/git-restore.txt   | 11 +++++++++++
 Documentation/git-switch.txt    |  2 +-
 5 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c8fb995fa7..140bd3eabb 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -296,7 +296,7 @@ Note that this option uses the no overlay mode by default (see also
 	submodules according to the commit recorded in the superproject. If
 	local modifications in a submodule would be overwritten the checkout
 	will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)
-	is used, the work trees of submodules will not be updated.
+	is used, submodules working trees will not be updated.
 	Just like linkgit:git-submodule[1], this will detach `HEAD` of the
 	submodule.
 
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index da33f84f33..501f2ec375 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -118,7 +118,7 @@ OPTIONS
 --[no-]recurse-submodules::
 	Using --recurse-submodules will update the content of all initialized
 	submodules according to the commit recorded in the superproject by
-	calling read-tree recursively, also setting the submodules HEAD to be
+	calling read-tree recursively, also setting the submodules' HEAD to be
 	detached at that commit.
 
 --no-sparse-checkout::
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 932080c55d..252e2d4e47 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -87,6 +87,12 @@ but carries forward unmerged index entries.
 	different between `<commit>` and `HEAD`.
 	If a file that is different between `<commit>` and `HEAD` has local
 	changes, reset is aborted.
+
+--[no-]recurse-submodules::
+	When the working tree is updated, using --recurse-submodules will
+	also recursively reset the working tree of all active submodules
+	according to the commit recorded in the superproject, also setting
+	the submodules' HEAD to be detached at that commit.
 --
 
 See "Reset, restore and revert" in linkgit:git[1] for the differences
diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt
index 5bf60d4943..8e3b339802 100644
--- a/Documentation/git-restore.txt
+++ b/Documentation/git-restore.txt
@@ -107,6 +107,17 @@ in linkgit:git-checkout[1] for details.
 	patterns and unconditionally restores any files in
 	`<pathspec>`.
 
+--recurse-submodules::
+--no-recurse-submodules::
+	If `<pathspec>` names an active submodule and the restore location
+	includes the working tree, the submodule will only be updated if
+	this option is given, in which case its working tree will be
+	restored to the commit recorded in the superproject, and any local
+	modifications overwritten. If nothing (or
+	`--no-recurse-submodules`) is used, submodules working trees will
+	not be updated. Just like linkgit:git-checkout[1], this will detach
+	`HEAD` of the submodule.
+
 --overlay::
 --no-overlay::
 	In overlay mode, the command never removes files when
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index 197900363b..79dbc9624d 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -183,7 +183,7 @@ name, the guessing is aborted.  You can explicitly give a name with
 	Using `--recurse-submodules` will update the content of all
 	initialized submodules according to the commit recorded in the
 	superproject. If nothing (or `--no-recurse-submodules`) is
-	used, the work trees of submodules will not be updated. Just
+	used, submodules working trees will not be updated. Just
 	like linkgit:git-submodule[1], this will detach `HEAD` of the
 	submodules.
 
-- 
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)

[PATCH v6 3/5] doc: explain how to deactivate submodule.recurse completely

[Damien Robert]

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/submodule.txt | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt
index 5962f41ead..d7a63c8c12 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.txt
@@ -63,6 +63,13 @@ submodule.recurse::
 	(`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`,
 	`restore` and `switch`) except `clone` and `ls-files`.
 	Defaults to false.
+	When set to true, it can be deactivated via the
+	`--no-recurse-submodules` option. Note that some Git commands
+	lacking this option may call some of the above commands affected by
+	`submodule.recurse`; for instance `git remote update` will call
+	`git fetch` but does not have a `--no-recurse-submodules` option.
+	For these commands a workaround is to temporarily change the
+	configuration value by using `git -c submodule.recurse=0`.
 
 submodule.fetchJobs::
 	Specifies how many submodules are fetched/cloned at the same time.
-- 
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)

[PATCH v6 4/5] doc: be more precise on (fetch|push).recurseSubmodules

[Damien Robert]

The default value also depends on the value of submodule.recurse.
Use this opportunity to correct some grammar mistakes in
Documentation/config/fetch.txt signaled by Robert P. J. Day.

Also mention `fetch.recurseSubmodules` in fetch-options.txt. In
git-push.txt, `push.recurseSubmodules` is implicitly mentioned (by
explaining how to disable it), so no need to add it there.

Lastly add a link to `git-fetch` in `git-pull.txt` to explain the
meaning of `--recurse-submodules` there.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
---
 Documentation/config/fetch.txt  | 13 ++++++++-----
 Documentation/config/push.txt   |  2 ++
 Documentation/fetch-options.txt |  3 ++-
 Documentation/git-pull.txt      |  3 +--
 4 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
index f11940280f..b1a9b1461d 100644
--- a/Documentation/config/fetch.txt
+++ b/Documentation/config/fetch.txt
@@ -1,11 +1,14 @@
 fetch.recurseSubmodules::
-	This option can be either set to a boolean value or to 'on-demand'.
+	This option controls whether `git fetch` (and the underlying fetch
+	in `git pull`) will recursively fetch into populated submodules.
+	This option can be set either to a boolean value or to 'on-demand'.
 	Setting it to a boolean changes the behavior of fetch and pull to
-	unconditionally recurse into submodules when set to true or to not
-	recurse at all when set to false. When set to 'on-demand' (the default
-	value), fetch and pull will only recurse into a populated submodule
-	when its superproject retrieves a commit that updates the submodule's
+	recurse unconditionally into submodules when set to true or to not
+	recurse at all when set to false. When set to 'on-demand', fetch and
+	pull will only recurse into a populated submodule when its
+	superproject retrieves a commit that updates the submodule's
 	reference.
+	Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.
 
 fetch.fsckObjects::
 	If it is set to true, git-fetch-pack will check all fetched
diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt
index 0a7aa322a9..f5e5b38c68 100644
--- a/Documentation/config/push.txt
+++ b/Documentation/config/push.txt
@@ -112,3 +112,5 @@ push.recurseSubmodules::
 	is 'no' then default behavior of ignoring submodules when pushing
 	is retained. You may override this configuration at time of push by
 	specifying '--recurse-submodules=check|on-demand|no'.
+	If not set, 'no' is used by default, unless 'submodule.recurse' is
+	set (in which case a 'true' value means 'on-demand').
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 00d03ec8c3..833f935cd0 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -163,7 +163,8 @@ ifndef::git-pull[]
 	value. Use 'on-demand' to only recurse into a populated submodule
 	when the superproject retrieves a commit that updates the submodule's
 	reference to a commit that isn't already in the local submodule
-	clone.
+	clone. By default, 'on-demand' is used, unless
+	`fetch.recurseSubmodules` is set (see linkgit:git-config[1]).
 endif::git-pull[]
 
 -j::
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index dfb901f8b8..47bc4a7061 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -86,8 +86,7 @@ OPTIONS
 
 --[no-]recurse-submodules[=yes|on-demand|no]::
 	This option controls if new commits of all populated submodules should
-	be fetched and updated, too (see linkgit:git-config[1] and
-	linkgit:gitmodules[5]).
+	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
 +
 If the checkout is done via rebase, local submodule commits are rebased as well.
 +
-- 
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)

[PATCH v6 5/5] doc: --recurse-submodules mostly applies to active submodules

[Damien Robert]

The documentation refers to "initialized" or "populated" submodules,
to explain which submodules are affected by '--recurse-submodules', but
the real terminology here is 'active' submodules. Update the
documentation accordingly.

Some terminology:
- Active is defined in gitsubmodules(7), it only involves the
  configuration variables 'submodule.active', 'submodule.<name>.active'
  and 'submodule.<name>.url'. The function
  submodule.c::is_submodule_active checks that a submodule is active.
- Populated means that the submodule's working tree is present (and the
  gitfile correctly points to the submodule repository), i.e. either the
  superproject was cloned with ` --recurse-submodules`, or the user ran
  `git submodule update --init`, or `git submodule init [<path>]` and
  `git submodule update [<path>]` separately which populated the
  submodule working tree. This does not involve the 3 configuration
  variables above.
- Initialized (at least in the context of the man pages involved in this
  patch) means both "populated" and "active" as defined above, i.e. what
  `git submodule update --init` does.

The --recurse-submodules option mostly affects active submodules. An
exception is `git fetch` where the option affects populated submodules.
As a consequence, in `git pull --recurse-submodules` the fetch affects
populated submodules, but the resulting working tree update only affects
active submodules.

In the documentation of `git-pull`, let's distinguish between the
fetching part which affects populated submodules, and the updating of
worktrees, which only affects active submodules.

Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com>
Helped-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 Documentation/git-checkout.txt  | 2 +-
 Documentation/git-grep.txt      | 2 +-
 Documentation/git-ls-files.txt  | 2 +-
 Documentation/git-pull.txt      | 6 ++++--
 Documentation/git-read-tree.txt | 2 +-
 Documentation/git-switch.txt    | 2 +-
 6 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 140bd3eabb..5b697eee1b 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -292,7 +292,7 @@ Note that this option uses the no overlay mode by default (see also
 
 --recurse-submodules::
 --no-recurse-submodules::
-	Using `--recurse-submodules` will update the content of all initialized
+	Using `--recurse-submodules` will update the content of all active
 	submodules according to the commit recorded in the superproject. If
 	local modifications in a submodule would be overwritten the checkout
 	will fail unless `-f` is used. If nothing (or `--no-recurse-submodules`)
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index ddb6acc025..cdf8e26b47 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -93,7 +93,7 @@ OPTIONS
 	with `--no-index`.
 
 --recurse-submodules::
-	Recursively search in each submodule that has been initialized and
+	Recursively search in each submodule that is active and
 	checked out in the repository.  When used in combination with the
 	<tree> option the prefix of all submodule output will be the name of
 	the parent project's <tree> object. This option has no effect
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 8461c0e83e..3cb2ebb438 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -148,7 +148,7 @@ a space) at the start of each line:
 	top directory.
 
 --recurse-submodules::
-	Recursively calls ls-files on each submodule in the repository.
+	Recursively calls ls-files on each active submodule in the repository.
 	Currently there is only support for the --cached mode.
 
 --abbrev[=<n>]::
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 47bc4a7061..b336df00c7 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -85,8 +85,10 @@ OPTIONS
 	Pass --verbose to git-fetch and git-merge.
 
 --[no-]recurse-submodules[=yes|on-demand|no]::
-	This option controls if new commits of all populated submodules should
-	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).
+	This option controls if new commits of populated submodules should
+	be fetched, and if the working trees of active submodules should be
+	updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and
+	linkgit:gitmodules[5]).
 +
 If the checkout is done via rebase, local submodule commits are rebased as well.
 +
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 501f2ec375..5fa8bab64c 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -116,7 +116,7 @@ OPTIONS
 	located in.
 
 --[no-]recurse-submodules::
-	Using --recurse-submodules will update the content of all initialized
+	Using --recurse-submodules will update the content of all active
 	submodules according to the commit recorded in the superproject by
 	calling read-tree recursively, also setting the submodules' HEAD to be
 	detached at that commit.
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index 79dbc9624d..3759c3a265 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -181,7 +181,7 @@ name, the guessing is aborted.  You can explicitly give a name with
 --recurse-submodules::
 --no-recurse-submodules::
 	Using `--recurse-submodules` will update the content of all
-	initialized submodules according to the commit recorded in the
+	active submodules according to the commit recorded in the
 	superproject. If nothing (or `--no-recurse-submodules`) is
 	used, submodules working trees will not be updated. Just
 	like linkgit:git-submodule[1], this will detach `HEAD` of the
-- 
Patched on top of v2.26.0-106-g9fadedd637 (git version 2.26.0)

Re: [PATCH v6 0/5] doc: --recurse-submodules

[Philippe Blain]

Hi Damien,

> Le 6 avr. 2020 à 09:57, Damien Robert <damien.olivier.robert@gmail.com> a écrit :
> 
> Fix typo mentioned by Junio.
> 
> Damien Robert (5):
>  doc: list all commands affected by submodule.recurse
>  doc: document --recurse-submodules for reset and restore
>  doc: explain how to deactivate submodule.recurse completely
>  doc: be more precise on (fetch|push).recurseSubmodules
>  doc: --recurse-submodules mostly applies to active submodules

A little late to the game, but consider this series

Reviewed-by: Philippe Blain <levraiphilippeblain@gmail.com>


(It's my first review, so I don't know if I should explicitly add that to each patch?...)

Anyway, thanks a lot for putting time into this!

Philippe.