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