Re: [PATCH 1/5] doc: git-add: remove options from SYNOPSIS
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Aug 12, 2025, 20:41 UTC
- Message-ID
- <xmqqms84s276.fsf@gitster.g>
- In-Reply-To
- <3a2cc38b72fb0f6ccc0ec9cbefadb7576cd8b934.1755029249.git.gitgitgadget@gmail.com>
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 7 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>`
For "git add", which has only one mode of operation, this may be good.
Note that in general this is not necessarily a good idea, when a command works in different modes (like "git branch" that can list/enumerate or create/delete/manipulate), as not all the options can be used in all the modes the command supports. The "usage" part of the output from "git branch -h" hits a good balance, and may want to use as a model.
There is t0450 that aspires to ensure the short usage "git <cmd> -h" matches the synopsis section of "git help <cmd>" for all <cmd>; right now we have too many exceptions, and we should move towards making these exceptions smaller.
> 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.
Except that you have to scan a lot of text, which is quite inefficient when you *know* the general idea behind the option you want to use, and are only looking for the exact spelling of it (e.g. "was it spelled --ignore-removed?")
Show 5 quoted lines
> `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
It is a very good point why we may want to have these cues to express "these go together" (my earlier example of "branch") and "only one of these is used". I tend to agree with you that these are not necessarily very easy to read.
While it is important to make it easier for new readers to learn, we should also keep in mind that nobody remains to be a newbie forever.
Show 6 quoted lines
> [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>...]
This being a long single line and with redundant "--long|-s" may be making it unnecessarily ugly. Have you considered folding lines and simplifying "[--long | -s]" into "[-s]" and see if it makes easier to follow? Documentation/git-commit.adoc may serve as a better model.
> +git add [<options>] [--] [<pathspec>...] > > DESCRIPTION > -----------