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

From: Julia Evans <julia@jvns.ca>
Date: Aug 13, 2025, 16:58 UTC
Message-ID: <d027b0cc-a2b0-4b73-b7e0-410fc559fd51@app.fastmail.com>
In-Reply-To: <xmqqms84s276.fsf@gitster.g>

Thanks for the comments. I think for now I'll just remove this patch from the series since I don't see a clear way forward and I think it'll make it easier to focus on the other changes.

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

I've been thinking about that as well: I have some ideas I've been working on for how to clarify the usage of different "modes" of a command by giving the modes names, will share those when I get to a command with modes.

> 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?")

That's fair. Something that I hadn't considered is that how easy the OPTIONS section is to scan depends on how the man page is formatted: some man page viewers will bold the options (which I think makes them easier to scan), but some won't.

Show 6 quoted lines

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

Hmm, here's what it looks like with the long options removed. To me it doesn't feel like a big enough improvement, and it's harder to tell what some of the short options (like `-n`) mean.

git add [-p] [-v] [-n] [-f] [-i] [-e] [-A | --no-all | -u]
	[--sparse] [--intent-to-add | -N] [--refresh] [--ignore-errors]
	[--ignore-missing] [--renormalize] [--chmod=(+|-)x]
	[--pathspec-from-file=<file> [--pathspec-file-nul]]
	[--] [<pathspec>...]