threads / bug / 60618
Subject: Bug | Documentation | git add -all | Synopsis has minor mistake
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
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
Junio C HamanoRe: [PATCH] git-add.txt: add missing short option -A to synopsis
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 SunshineRe: [PATCH] git-add.txt: add missing short option -A to synopsis
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.
Eric SunshineRe: Bug | Documentation | git add -all | Synopsis has minor mistake
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/