Re: [PATCH 1/5] doc: git-add: remove options from SYNOPSIS

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Tuesday, 12 August 2025 22:07:25 CEST Julia Evans via GitGitGadget wrote:
> From: Julia Evans <julia@jvns.ca>
> 
> Motivations for this change:
> 
> 1. Listing a huge number of options is visually overwhelming when
>    opening a man page for an unfamiliar command. It makes it harder
>    to understand the command's core syntax, like `git add <filename>`
> 2. For options which can be passed independently of any other options,
>    including them in the SYNOPSIS does not add any information which you
>    can't already get from reading the OPTIONS section. `git add` has
>    some mutually exclusive options, namely:
>    [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]]
>    but personally I already find that line so hard to parse that
>    removing it doesn't remove a lot of information
> 3. Some man pages already take this approach, like `git rebase` and
>    `git status`
> 
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-add.adoc | 6 +-----
>  1 file changed, 1 insertion(+), 5 deletions(-)
> 
> diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
> index b7a735824d6c..12afeead6637 100644
> --- a/Documentation/git-add.adoc
> +++ b/Documentation/git-add.adoc
> @@ -8,11 +8,7 @@ git-add - Add file contents to the index
>  SYNOPSIS
>  --------
>  [synopsis]
> -git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -
i]
> [--patch | -p] -	[--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>...]
> +git add [<options>] [--] [<pathspec>...]
> 
>  DESCRIPTION
>  -----------


Hello,

I'm not crazy about this change. In its new form, it is almost useless and 
formally wrong: according to it, `git add` is a valid invocation. The question 
is about how this synopsis section is supposed to be used. For me, this is a 
quick refresher of the available options, their exact name and how they can be 
combined, a kind of compact overview.

I'm not saying that the current form is good. For instance, I would expect to 
see alternative forms such as `git add -u` appear on their own line whereas 
other forms require <pathspec>. There are common options that could be hidden 
into the [<options>] stuff, even if it kills a bit the "compact summary" 
feature of the synopsis, but as you said, these are independent and can be 
found under the 'OPTIONS' section.

The design of the man pages predates some more modern approaches to organizing 
technical documentation e.g. https://diataxis.fr/ and https://help.adobe.com/
en_US/framemaker/2019/using/using-framemaker-2019/user-guide/
frm_structauthdita_sd_dita-topics.html. Thus they are mixing different aims/
approaches in a single document. Anyway, we can agree to classify some of the 
manual page sections into the more modern typing. For instance, I think 
SYNOPSIS falls under the "reference" type, and as such should be as 
comprehensive as possible.

Jean-Noël