Re: [PATCH] doc: mention that 'git submodule update' fetches missing commits

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 20, 2019, 18:09 UTC
Message-ID: <xmqqsgs4nn6k.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <0102016b72a55a7d-fb4ecdb7-9f2b-4204-b888-0000f209c3ff-000000@eu-west-1.amazonses.com>

Philippe Blain <levraiphilippeblain@gmail.com> writes:

Show 23 quoted lines

> 'git submodule update' will fetch new commits from the submodule remote
> if the SHA-1 recorded in the superproject is not found. This was not
> mentioned in the documentation.
>
> Signed-off-by: Philippe Blain <levraiphilippeblain@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 2794e2978021c..930bfcee50e4c 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -132,7 +132,8 @@ update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--forc
>  +
>  --
>  Update the registered submodules to match what the superproject
> -expects by cloning missing submodules and updating the working tree of
> +expects by cloning missing submodules, fetching missing submodule commits
> +and updating the working tree of
>  the submodules. The "updating" can be done in several ways depending
>  on command line options and the value of `submodule.<name>.update`
>  configuration variable. The command line option takes precedence over

The additional text may not be wrong per-se, but isn't it fairly obvious that there is no other way than to fetch, in order to "update the registered submodules to match what the superproject expects", aka "if the commit object name recorded in the superproject is not found". How else would the subcommand come up with the missing commit out of thin air?

IOW, I have to wonder if this is worth saying, or if these new words are just adding more things the readers need to scan on the page without adding that much information.