Re: [PATCH] docs: remove stray bracket from git-clone synopsis

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 31, 2025, 19:07 UTC
Message-ID: <xmqqh5ysqivy.fsf@gitster.g>
In-Reply-To: <pull.2023.git.git.1753973177262.gitgitgadget@gmail.com>

"Knut Harald Ryager via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: E-K-n <e-k-nut@hotmail.com>

This should be updated to match the name you use on your sign-off below.

> The git-clone documentation contained an extra ‘]’ after
> `--also-filter-submodules]`.

It is correct to point out that the brackets are not matching, but I think the one that you are removing a wrong one.

When f05da2b4 (clone, submodule: pass partial clone filters to submodules, 2022-02-04) added an option --also-filter-submodules to the command, it wanted to express that the option is only valid when the "--filter=<filter-spec>" option is also given. And it did its update correctly:

-         [--filter=<filter>] [--] <repository>
+         [--filter=<filter> [--also-filter-submodules]] [--] <repository>
 
Later, 76880f05 (doc: git-clone: apply new documentation formatting
guidelines, 2024-03-29) introduced the extra closing bracket after
"--filter=<filter>" to make these two look as if they are unrelated
and independent, i.e.

    [--filter=<filter>] [--also-filter-submodules]]

So, I think the one immediately after "--filter=<filter>" is what you want to remove, not the one after "--also-filter-submodules".

Show 7 quoted lines

> This patch removes the duplicate ‘]’ so that the line reads:
>
>     [--also-filter-submodules] [--] <repository>
>
> instead of:
>
>     [--also-filter-submodules]] [--] <repository>

We do not say "this patch does X" in our proposed log message. Instead, you tell somebody sitting on the keyboard to "Do X".

IOW, something like

    Remove the extra and incorrect closing bracket, so that the line
    reads:

        [--filter=<filter> [--also-filter-submodules]]

    instead of

        [--filter=<filter>] [--also-filter-submodules]]

is how we write this.

Show 26 quoted lines

> Signed-off-by: Knut Harald Ryager <e-k-nut@hotmail.com>
> ---
>     Remove excess right bracket from git-clone docs
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2023%2FKnutRyager%2Fmaster-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2023/KnutRyager/master-v1
> Pull-Request: https://github.com/git/git/pull/2023
>
>  Documentation/git-clone.adoc | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-clone.adoc b/Documentation/git-clone.adoc
> index 222d558290e..851502552f2 100644
> --- a/Documentation/git-clone.adoc
> +++ b/Documentation/git-clone.adoc
> @@ -16,7 +16,7 @@ git clone [--template=<template-directory>]
>  	  [--depth <depth>] [--[no-]single-branch] [--[no-]tags]
>  	  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
>  	  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
> -	  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
> +	  [--filter=<filter-spec>] [--also-filter-submodules] [--] <repository>
>  	  [<directory>]
>  
>  DESCRIPTION
>
> base-commit: e813a0200a7121b97fec535f0d0b460b0a33356c