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

[Philippe Blain <levraiphilippeblain@gmail.com>]

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