Re: [PATCH 1/3] git-submodule.txt: document default behavior without --branch

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 6, 2019, 18:46 UTC
Message-ID: <xmqqftt0rc0g.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <cf6e0d16ac0c0d521da98f5d9a53532b923a621c.1549450636.git.liu.denton@gmail.com>

Denton Liu <liu.denton@gmail.com> writes:

Show 20 quoted lines

> This behavior is mentioned in gitmodules.txt but not in
> git-submodule.txt so we copy the information over so that it is not
> missed.
>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
>  Documentation/git-submodule.txt | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index ba3c4df550..9951c68744 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -261,7 +261,8 @@ OPTIONS
>  	The name of the branch is recorded as `submodule.<name>.branch` in
>  	`.gitmodules` for `update --remote`.  A special value of `.` is used to
>  	indicate that the name of the branch in the submodule should be the
> -	same name as the current branch in the current repository.
> +	same name as the current branch in the current repository.  If the
> +	option is not specified, it defaults to 'master'.

OK.  Thanks.

I read the whole page and there are a few other things I noticed, which I'll write down here so that somebody else can think about them (and that somebody else does not have to be you) as a tangent.

1. The description of "--branch <branch>" option here is missing the
   "<branch>", a mandatory argument to the option.  Options in the
   OPTIONS list like "--jobs <n>", "--repository <repo>" do show the
   argument, and the description for this option should be updated
   to match.

2. Some options are mentioned in the description of each subcommand
   it can appear (e.g. "sync --recursive"), while many others are
   not and shown only in the OPTIONS section (e.g. "--remote" which
   can be used only with "update" subcommand).

These may want to be cleaned up. Actually it may not be a bad idea to do #1 as part of this change (i.e. retitle it to "git-submodule: "--branch <branch>" option defaults to 'master'" or something).