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

[Philippe Blain <levraiphilippeblain@gmail.com>]

> 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".