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

5 messages from 2023-12-15 to 2023-12-15. Participants: Benjamin Lehmann, Eric Sunshine, Junio C Hamano.
Thread: https://gitlist.dev/t/60618

## Benjamin Lehmann, 2023-12-15 12:38

Subject: Bug | Documentation | git add -all | Synopsis has minor mistake
Message-ID: <CAM=w4Pn46nTcWA1e=n4Rms76gCx7iqbRmOWf3=vRmKgtbhqQmA@mail.gmail.com>
URL: https://gitlist.dev/e/CAM%3Dw4Pn46nTcWA1e%3Dn4Rms76gCx7iqbRmOWf3%3DvRmKgtbhqQmA%40mail.gmail.com

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

```

## Eric Sunshine, 2023-12-15 20:43

Subject: [PATCH] git-add.txt: add missing short option -A to synopsis
Message-ID: <20231215204333.1253-1-ericsunshine@charter.net>
URL: https://gitlist.dev/e/20231215204333.1253-1-ericsunshine%40charter.net
In-Reply-To: <CAM=w4Pn46nTcWA1e=n4Rms76gCx7iqbRmOWf3=vRmKgtbhqQmA@mail.gmail.com>

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


```

## Eric Sunshine, 2023-12-15 20:49

Subject: Re: Bug | Documentation | git add -all | Synopsis has minor mistake
Message-ID: <CAPig+cSkzJpufEG_XhFdSho89itLOuvCwMaTkXXAjryNnWteQQ@mail.gmail.com>
URL: https://gitlist.dev/e/CAPig%2BcSkzJpufEG_XhFdSho89itLOuvCwMaTkXXAjryNnWteQQ%40mail.gmail.com
In-Reply-To: <CAM=w4Pn46nTcWA1e=n4Rms76gCx7iqbRmOWf3=vRmKgtbhqQmA@mail.gmail.com>

```
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/

```

## Junio C Hamano, 2023-12-15 21:01

Subject: Re: [PATCH] git-add.txt: add missing short option -A to synopsis
Message-ID: <xmqqjzpfkwnr.fsf@gitster.g>
URL: https://gitlist.dev/e/xmqqjzpfkwnr.fsf%40gitster.g
In-Reply-To: <20231215204333.1253-1-ericsunshine@charter.net>

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

```

## Eric Sunshine, 2023-12-15 21:04

Subject: Re: [PATCH] git-add.txt: add missing short option -A to synopsis
Message-ID: <CAPig+cS3Yb2n4e7ZxmSFFxYbHWn7wcMBXG=nCigCKst-GzGLLQ@mail.gmail.com>
URL: https://gitlist.dev/e/CAPig%2BcS3Yb2n4e7ZxmSFFxYbHWn7wcMBXG%3DnCigCKst-GzGLLQ%40mail.gmail.com
In-Reply-To: <xmqqjzpfkwnr.fsf@gitster.g>

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

```