Bug | Documentation | git add -all | Synopsis has minor mistake

Bug | Documentation | git add -all | Synopsis has minor mistake

[Benjamin Lehmann]

Hey.

The mistake can be found in the synopsis here:
https://git-scm.com/docs/git-add#Documentation/git-add.txt--A

In the synopsys, the options -all currently reads:

[--[no-]all | --[no-]ignore-removal |

You can see that there is no mention of -A, which is the main way that
people would use -all perhaps, so it really ought to be included
correctly in the synopsis. In addition, the closing square-bracket is
missing.

Hope this was the right place to report this - seemed to be the only option.

Ben

[PATCH] git-add.txt: add missing short option -A to synopsis

[Eric Sunshine]

From: Eric Sunshine <sunshine@sunshineco.com>

With one exception, the synopsis for `git add` consistently lists the
short counterpart alongside the long-form of each option (for instance,
"[--edit | -e]"). The exception is that -A is not mentioned alongside
--all. Fix this inconsistency

Reported-by: Benjamin Lehmann <ben.lehmann@gmail.com>
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---

An alternative would be to collapse the synopsis to:

    'git add' <options> [--] [<pathspec>...]

as has been done for other command documentation, however doing so would
throw away at-a-glance clues about which options are mutually exclusive,
so adding the missing -A to the synopsis seems preferable (for now, at
least).

 Documentation/git-add.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index ed44c1cb31..3d2e670716 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -9,7 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
-	  [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] [--sparse]
+	  [--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]
 	  [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
 	  [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]]
 	  [--] [<pathspec>...]
-- 
2.43.0

Re: Bug | Documentation | git add -all | Synopsis has minor mistake

[Eric Sunshine]

On Fri, Dec 15, 2023 at 7:38 AM Benjamin Lehmann <ben.lehmann@gmail.com> wrote:
> The mistake can be found in the synopsis here:
> https://git-scm.com/docs/git-add#Documentation/git-add.txt--A
>
> In the synopsys, the options -all currently reads:
>
> [--[no-]all | --[no-]ignore-removal |
>
> You can see that there is no mention of -A, which is the main way that
> people would use -all perhaps, so it really ought to be included
> correctly in the synopsis.

This seems to be a simple oversight when the --all option was added by
da98053aa6 (git-add --all: documentation, 2008-07-19).

> In addition, the closing square-bracket is missing.

I think this is inaccurate. If you look closely, you will find the
closing bracket after the -u option:

    [--[no-]all | --[no-]ignore-removal | [--update | -u]]

meaning that --all, --ignore-removal, and --update are mutually exclusive.

> Hope this was the right place to report this - seemed to be the only option.

This is the correct place. I posted a patch[1] addressing the issue.

[1]: https://lore.kernel.org/git/20231215204333.1253-1-ericsunshine@charter.net/

Re: [PATCH] git-add.txt: add missing short option -A to synopsis

[Junio C Hamano]

Eric Sunshine <ericsunshine@charter.net> writes:

> From: Eric Sunshine <sunshine@sunshineco.com>
>
> With one exception, the synopsis for `git add` consistently lists the
> short counterpart alongside the long-form of each option (for instance,
> "[--edit | -e]"). The exception is that -A is not mentioned alongside
> --all. Fix this inconsistency
>
> Reported-by: Benjamin Lehmann <ben.lehmann@gmail.com>
> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
> ---

Thanks.

I dug the history just in case we deliberately wanted to leave this
out of the synopsis section, but the side branch leading to the
merge at 378335b3 (Merge branch 'jc/add-addremove', 2008-07-20) does
not say we wanted to discourage "-A" (and encourage "--all").  This
would be a welcome change.

Will queue.

Re: [PATCH] git-add.txt: add missing short option -A to synopsis

[Eric Sunshine]

On Fri, Dec 15, 2023 at 4:01 PM Junio C Hamano <gitster@pobox.com> wrote:
> Eric Sunshine <ericsunshine@charter.net> writes:
> > With one exception, the synopsis for `git add` consistently lists the
> > short counterpart alongside the long-form of each option (for instance,
> > "[--edit | -e]"). The exception is that -A is not mentioned alongside
> > --all. Fix this inconsistency
>
> I dug the history just in case we deliberately wanted to leave this
> out of the synopsis section, but the side branch leading to the
> merge at 378335b3 (Merge branch 'jc/add-addremove', 2008-07-20) does
> not say we wanted to discourage "-A" (and encourage "--all").  This
> would be a welcome change.

I also dug through the history for the same reason and, like you, did
not find any indication that -A was omitted from the synopsis
deliberately. I probably should have stated as much in the patch
commentary.