From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 28 Feb 2014 21:39:32 GMT
Subject: Re: [PATCH] submodule update: document the '--checkout' option
Message-ID: <xmqqbnxqudbf.fsf@gitster.dls.corp.google.com>
In-Reply-To: <530FB5C4.8080400@web.de>

Jens Lehmann <Jens.Lehmann@web.de> writes:

> Good point. What about this?
>
>
>  Documentation/git-submodule.txt | 13 +++++++++++--
>  git-submodule.sh                |  2 +-
>  2 files changed, 12 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index bfef8a0..9054217 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -15,8 +15,8 @@ SYNOPSIS
>  'git submodule' [--quiet] init [--] [<path>...]
>  'git submodule' [--quiet] deinit [-f|--force] [--] <path>...
>  'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
> -	      [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>]
> -	      [--merge] [--recursive] [--] [<path>...]
> +	      [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>]
> +	      [--depth <depth>] [--recursive] [--] [<path>...]

This has already been done by 23d25e48 (submodule: explicit local
branch creation in module_clone, 2014-01-26).  That commit also adds
some text to the description of 'update' subcommand, but not a
separate entry for '--checkout' mode.

Does the result of applying this patch except for this particular
hunk still make sense as a whole?  It appears to me that it does,
but just to double check...

Thanks.

>  'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
>  	      [commit] [--] [<path>...]
>  'git submodule' [--quiet] foreach [--recursive] <command>
> @@ -287,6 +287,15 @@ SHA-1.  If you don't want to fetch, you should use `submodule update
>  	This option is only valid for the update command.
>  	Don't fetch new objects from the remote site.
>
> +--checkout::
> +	This option is only valid for the update command.
> +	Checkout the commit recorded in the superproject on a detached HEAD
> +	in the submodule. This is the default behavior, the main use of
> +	this option is to override `submodule.$name.update` when set to
> +	`merge`, `rebase` or `none`.
> +	If the key `submodule.$name.update` is either not explicitly set or
> +	set to `checkout`, this option is implicit.
> +
>  --merge::
>  	This option is only valid for the update command.
>  	Merge the commit recorded in the superproject into the current branch
> diff --git a/git-submodule.sh b/git-submodule.sh
> index 4a30087..65cf963 100755
> --- a/git-submodule.sh
> +++ b/git-submodule.sh
> @@ -9,7 +9,7 @@ USAGE="[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <re
>     or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...]
>     or: $dashless [--quiet] init [--] [<path>...]
>     or: $dashless [--quiet] deinit [-f|--force] [--] <path>...
> -   or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<path>...]
> +   or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>] [--recursive] [--] [<path>...]
>     or: $dashless [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...]
>     or: $dashless [--quiet] foreach [--recursive] <command>
>     or: $dashless [--quiet] sync [--recursive] [--] [<path>...]"