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

[Philippe Blain <levraiphilippeblain@gmail.com>]

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