jaydeepjd.8914@xxxxxxxxx writes: > Here is an example. The synopsis of command `send-email` vs synopsis of `commit`: > > ``` > git send-email [<options>] <file|directory>… > git send-email [<options>] <format-patch options> > git send-email --dump-aliases > ``` > > ``` > git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend] > [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)] > [-F <file> | -m <msg>] [--reset-author] [--allow-empty] > [--allow-empty-message] [--no-verify] [-e] [--author=<author>] > [--date=<date>] [--cleanup=<mode>] [--[no-]status] > [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]] > [(--trailer <token>[(=|:)<value>])…] [-S[<keyid>]] > [--] [<pathspec>…] > ``` > > The `commit` synopsis has a more verbose overview of all the options available compared to `send-email` synopsis. I think the former is more modern style that leaves the description of options to the main text. It also allows the synopsis section to make it stand out very different operating modes instead of having the alternative listed with [ A | B | C ] and having the readers guess if all combinations of alternatives are valid (they are often not). The former style takes more thought to write well, when a command is multi-purpose and has different operating modes (cf. "git checkout"). For "git commit", even though conceptually creating a totally new commit and amending the current one are two quite distinct opeating modes, they pretty much take the same set of options, so I suspect we can do with just one git commit [<options>] [--] [<pathspec>...] in the modern style, but I dunno (that is why I said "it takes more thought" and I cannot afford much time to think it through just for illustration purposes). Thanks.
