Subject: Re: [PATCH] t/t0015-hash.sh: removed unnecessary '\' at line end

From: Junio C Hamano <[email-masked]>
Date: Thu, 10 Feb 2022 09:20:02 -0800

[email-masked] 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.