Subject: Re: [PATCH] submodule: Fix documentation of update subcommand

From: Jens Lehmann <[email-masked]>
Date: Mon, 03 Nov 2014 21:58:41 +0100

Am 03.11.2014 um 21:53 schrieb Junio C Hamano:
> I did a bit more digging of the history, and came up with this,
> which would be with a clearer and fairer description.  Also to
> clarify, I spelled what Michal's "This" meant to refer to.
>
> -- >8 --
> From: Michal Sojka <[email-masked]>
> Date: Mon, 3 Nov 2014 11:09:51 +0100
> Subject: [PATCH] submodule: clarify documentation for update subcommand
>
> e6a1c43a (document submdule.$name.update=none option for gitmodules,
> 2012-05-10) meant to say "Unlike the case where your .update
> configuration is set to either 'rebase' or 'merge', when it is set
> to 'none', the tip of the submodule would never move.  You can use
> the --checkout option if you want the contents of the submodule to
> be updated to some other commit."
>
> But the resulting text made it sound as if using "--checkout" would
> have no effect when .update configuration is set to 'rebase' or
> 'merge', which was misleading.  In fact, with the "--checkout"
> option, the tip of the submodule moves to the exact commit that is
> recorded in the superproject tree, regardless of .update
> configuration.
>
> Signed-off-by: Michal Sojka <[email-masked]>
> Signed-off-by: Junio C Hamano <[email-masked]>
> ---
>   Documentation/git-submodule.txt | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index 8e6af65..648323f 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -158,7 +158,7 @@ update::
>   	checkout the commit specified in the index of the containing repository.
>   	This will make the submodules HEAD be detached unless `--rebase` or
>   	`--merge` is specified or the key `submodule.$name.update` is set to
> -	`rebase`, `merge` or `none`. `none` can be overridden by specifying
> +	`rebase`, `merge` or `none`. The configuration can be overridden by specifying
>   	`--checkout`. Setting the key `submodule.$name.update` to `!command`
>   	will cause `command` to be run. `command` can be any arbitrary shell
>   	command that takes a single argument, namely the sha1 to update to.

Yup, but we should also mention '--merge' and '--rebase' here.