Unbalanced closing paren in help of git commit

Unbalanced closing paren in help of git commit

[Tomas Nordin]

Hello List

The second line of the help message for git commit looks like this:

    [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]

See for example https://gitirc.eu/git-commit.html. It has two opening
parens and three closing parens. <commit> ends with a closing paren
before the closing bracket. Me and gsish (on IRC) suspect this is a
misstake.

What do you think?

Please reply all, not suscribed to the list.

Best regards
--
Tomas

Re: Unbalanced closing paren in help of git commit

[Jeff King]

On Sun, Jul 07, 2024 at 12:33:21PM +0000, Tomas Nordin wrote:

> The second line of the help message for git commit looks like this:
> 
>     [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]
> 
> See for example https://gitirc.eu/git-commit.html. It has two opening
> parens and three closing parens. <commit> ends with a closing paren
> before the closing bracket. Me and gsish (on IRC) suspect this is a
> misstake.
> 
> What do you think?

Yep, looks like a typo introduced by 00ea64ed7a (doc/git-commit: add
documentation for fixup=[amend|reword] options, 2021-03-15).

Want to try your hand at producing a patch? (It's OK if the answer is
no; it just seems like a good opportunity for somebody to get their feet
wet on contributing).

-Peff

Re: Unbalanced closing paren in help of git commit

[Tomas Nordin]

Jeff King <peff@peff.net> writes:

> On Sun, Jul 07, 2024 at 12:33:21PM +0000, Tomas Nordin wrote:
>
>> The second line of the help message for git commit looks like this:
>> 
>>     [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]
>> 
>> See for example https://gitirc.eu/git-commit.html. It has two opening
>> parens and three closing parens. <commit> ends with a closing paren
>> before the closing bracket. Me and gsish (on IRC) suspect this is a
>> misstake.
>> 
>> What do you think?
>
> Yep, looks like a typo introduced by 00ea64ed7a (doc/git-commit: add
> documentation for fixup=[amend|reword] options, 2021-03-15).

I stumbled upon it while working on a synopsis parsing tool, similar to
the Python docopt if familiar.

> Want to try your hand at producing a patch? (It's OK if the answer is
> no; it just seems like a good opportunity for somebody to get their feet
> wet on contributing).

I can try, why not? Should I hang it up on this thread so to say. Is
this a bug report?

Re: Unbalanced closing paren in help of git commit

[Jeff King]

On Mon, Jul 08, 2024 at 07:35:03PM +0000, Tomas Nordin wrote:

> > Want to try your hand at producing a patch? (It's OK if the answer is
> > no; it just seems like a good opportunity for somebody to get their feet
> > wet on contributing).
> 
> I can try, why not? Should I hang it up on this thread so to say. Is
> this a bug report?

You can do it as a reply to this thread, or you can start a new thread.
If there is a lot of discussion in the bug report thread, it is
sometimes helpful to reference it in your commit message or cover
letter. E.g. as:

  https://lore.kernel.org/git/87o7792xgu.fsf@posteo.net/

but in this case the issue is simple enough that you can just describe
the problem fully in the commit message.

-Peff

Re: Unbalanced closing paren in help of git commit

[Junio C Hamano]

Tomas Nordin <tomasn@posteo.net> writes:

> Hello List
>
> The second line of the help message for git commit looks like this:

This seems to have come from 00ea64ed (doc/git-commit: add
documentation for fixup=[amend|reword] options, 2021-03-15),
if "git blame" is to be trusted.

>     [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]

We can have --dry-run but we do not have to, we can have only one of

    "-c <commit>"
    "-C <commit>",
    "--squash <commit>",
    "--fixup amend:<commit>"
    "--fixup reword:<commit>", or
    "--fixup <commit>"

as they are mutually exclusive, but it is OK if we have none of
them.

The last closing parenthesis after <commit> but before the closing
square bracket is unwanted, I think, as you pointed out.

Re: Unbalanced closing paren in help of git commit

[Tomas Nordin]

[-- Attachment #1: Type: text/plain, Size: 1042 bytes --]

Junio C Hamano <gitster@pobox.com> writes:

> Tomas Nordin <tomasn@posteo.net> writes:
>
>> Hello List
>>
>> The second line of the help message for git commit looks like this:
>
> This seems to have come from 00ea64ed (doc/git-commit: add
> documentation for fixup=[amend|reword] options, 2021-03-15),
> if "git blame" is to be trusted.
>
>>     [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]
>
> We can have --dry-run but we do not have to, we can have only one of
>
>     "-c <commit>"
>     "-C <commit>",
>     "--squash <commit>",
>     "--fixup amend:<commit>"
>     "--fixup reword:<commit>", or
>     "--fixup <commit>"
>
> as they are mutually exclusive, but it is OK if we have none of
> them.
>
> The last closing parenthesis after <commit> but before the closing
> square bracket is unwanted, I think, as you pointed out.

So then I make an attempt to provide a patch to remove that closing
parenthesis. Please tell if it should be done differently somehow. The
patch was done on top of maint.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-remove-dangling-closing-parenthesis.patch --]
[-- Type: text/x-diff, Size: 1210 bytes --]

From 5da052f43b119949c0ac0c7c3047542bc7474c17 Mon Sep 17 00:00:00 2001
From: Tomas Nordin <tomasn@posteo.net>
Date: Sun, 21 Jul 2024 13:16:50 +0200
Subject: [PATCH] doc: remove dangling closing parenthesis

* Documentation/git-commit.txt:
  The second line of the synopsis, starting with [--dry-run] has a
  dangling closing paren in the second optional group. Probably added by
  misstake, so remove it.

Signed-off-by: Tomas Nordin <tomasn@posteo.net>
---
 Documentation/git-commit.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 89ecfc63a8..c822113c11 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -9,7 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
-	   [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]
+	   [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>]
 	   [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
 	   [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
 	   [--date=<date>] [--cleanup=<mode>] [--[no-]status]
-- 
2.39.2

Re: Unbalanced closing paren in help of git commit

[Junio C Hamano]

Tomas Nordin <tomasn@posteo.net> writes:

> So then I make an attempt to provide a patch to remove that closing
> parenthesis. Please tell if it should be done differently somehow. The
> patch was done on top of maint.
>
> From 5da052f43b119949c0ac0c7c3047542bc7474c17 Mon Sep 17 00:00:00 2001
> From: Tomas Nordin <tomasn@posteo.net>
> Date: Sun, 21 Jul 2024 13:16:50 +0200
> Subject: [PATCH] doc: remove dangling closing parenthesis

We do not "attach" patches to an e-mail, like this.  Please visit 
https://lore.kernel.org/git/ and check patch messages from others.

An example:
  https://lore.kernel.org/git/e048ef54-5824-452d-ab1f-233581711f4e@web.de/

Your Subject: looks good.  It shows that the author read (at least
some parts of) Documentation/SubmittingPatches.

> * Documentation/git-commit.txt:
>   The second line of the synopsis, starting with [--dry-run] has a
>   dangling closing paren in the second optional group. Probably added by
>   misstake, so remove it.

We do not work file-by-file.  If any reader wants to know which
paths were affected, they can see the diffstat before the patch.

I think what you wrote is just fine otherwise; just drop the "*
Documentation/git-commit" line, dedent the body of the paragraph,
and typofix the "misstake".

Thanks.


> Signed-off-by: Tomas Nordin <tomasn@posteo.net>
> ---
>  Documentation/git-commit.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index 89ecfc63a8..c822113c11 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -9,7 +9,7 @@ SYNOPSIS
>  --------
>  [verse]
>  'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
> -	   [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]
> +	   [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>]
>  	   [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
>  	   [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
>  	   [--date=<date>] [--cleanup=<mode>] [--[no-]status]

Re: Unbalanced closing paren in help of git commit

[Tomas Nordin]

Junio C Hamano <gitster@pobox.com> writes:

> We do not "attach" patches to an e-mail, like this.  Please visit 
> https://lore.kernel.org/git/ and check patch messages from others.

I tried to send the format-patch file using git send-email now. That
will be in a thread other than this.

> We do not work file-by-file.  If any reader wants to know which
> paths were affected, they can see the diffstat before the patch.
>
> I think what you wrote is just fine otherwise; just drop the "*
> Documentation/git-commit" line, dedent the body of the paragraph,
> and typofix the "misstake".

I made those amendments, lets see if its OK.