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

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Aug 13, 2025, 20:47 UTC
Message-ID: <2319022.iZASKD2KPV@cayenne>
In-Reply-To: <3a2cc38b72fb0f6ccc0ec9cbefadb7576cd8b934.1755029249.git.gitgitgadget@gmail.com>

On Tuesday, 12 August 2025 22:07:25 CEST Julia Evans via GitGitGadget wrote:

Show 31 quoted lines

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

Show 6 quoted lines

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