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

Commit Message

Eric Sunshine Dec. 15, 2023, 8:43 p.m. UTC

From: Eric Sunshine <[e-mail]>

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 <[e-mail]>
Signed-off-by: Eric Sunshine <[e-mail]>
---

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(-)

Comments

Junio C Hamano Dec. 15, 2023, 9:01 p.m. UTC | #1

Eric Sunshine <[e-mail]> writes:

> From: Eric Sunshine <[e-mail]>
>
> 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 <[e-mail]>
> Signed-off-by: Eric Sunshine <[e-mail]>
> ---

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 Dec. 15, 2023, 9:04 p.m. UTC | #2

On Fri, Dec 15, 2023 at 4:01 PM Junio C Hamano <[e-mail]> wrote:
> Eric Sunshine <[e-mail]> 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.

Patch

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