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

[Philippe Blain <levraiphilippeblain@gmail.com>]

> 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)
>