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

From: Junio C Hamano <[email-masked]>
Date: Thu, 31 Jul 2025 12:07:13 -0700

"Knut Harald Ryager via GitGitGadget" <[email-masked]>
writes:

> From: E-K-n <[email-masked]>

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".

> 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.

> Signed-off-by: Knut Harald Ryager <[email-masked]>
> ---
>     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