Re: [PATCH 2/3] commit: reorder synopsis

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 22, 2020, 16:16 UTC
Message-ID: <xmqqeemtlrc9.fsf@gitster.c.googlers.com>
In-Reply-To: <2a14d3d2-743c-215e-aa69-de75a576f685@gmail.com>

Phillip Wood <phillip.wood123@gmail.com> writes:

Show 14 quoted lines

> -'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
> -	   [--dry-run] [(-c | -C | --fixup | --squash) <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]]
> 	   [-S[<keyid>]] [--] [<pathspec>...]
> +'git commit' [-a | --interactive | --patch] [--amend]
> +	   [(-c | -C | --fixup | --squash) <commit>] [-F <file> | -m <msg>]
> +	   [--reset-author] [--author=<author>] [--date=<date>] [-s] [-e]
> +	   [--allow-empty] [--allow-empty-message] [--no-verify]
> +	   [--cleanup=<mode>] [-u<mode>] [--[no-]status]  [-v] [--dry-run]
> 	   [-i | -o | -p] [--pathspec-from-file=<file> [--pathspec-file-nul]]
>   	   [-S[<keyid>]] [--] [<pathspec>...]

This seems to group them better than the original, including "--allow-empty" and its two friends that are about sanity checking.

I would actually kick "-a" out of the "--interactive | --patch" group [*1*]. Unlike the two, it is not about a different operation mode. It is closer to how paths whose contents will participate in the resulting commit are chosen, so it is much closer to the "-i" and "-o" family, I would think.

What is "git commit -p" you have next to "-i" and "-o"? I do not think it belongs there---isn't it a short form of --patch?

Thanks.

[Footnote]

*1* It was originally made that way because the "add--interactive" based operation mode was incompatible with "-a", I think. But the thing is, the interactive one is incompatible with other things like "-i" and "-o". Use of the '|' alternative notation to express things are mutually incompatible inherently does not play well with the idea of showing common things early. It would allow us to group conceptually similar things together, though.

Do we want to say "[-a | -i | -o | --interactive | --patch]" in the same [] group and show them as alternatives? That may logically make some sense, and if we were to go that route, it belongs near the end of the list, close to where we show pathspec. I dunno.