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

From: Junio C Hamano <[email-masked]>
Date: Mon, 21 Sep 2020 22:27:49 -0700

"Phillip Wood via GitGitGadget" <[email-masked]> writes:

> From: Phillip Wood <[email-masked]>
>
> Rearrange the synopsis for `git commit` to try and put options that
> are used more often nearer the beginning.

Which option is used "more often" depends heavily on the workflow,
and it is a bit unfriendly to those who are affected by this change
not to list the ones you are demoting, with rationale for each,
something like:

 - "--dry-run" may or may not be used often, but it is orthogonal to
   the regular options that affect how the command behaves, and it
   is much less important and interesting than the other options.

Among the ones you are demoting without explanation

 - "-s" is no longer even mentioned, which I do not think is a well
   thought out change.

 - "-v" is to make the command do the same thing as it does without
   it, but just more loudly, so it is less interesting than the
   other options.

 - "-u<mode>" affects what is shown in the editor to prepare the log
   message, which is of less importance than other options that
   affect the outcome of the command.  When --no-status is in
   effect, -u<mode> would not even have any effect, so it probably
   makes sense to move this next to "--[no-]status".

 - "--reset-author" can be used not just to take ownership of the
   commit from somebody else, but also be used to update the author
   date of your own change.  It probably belongs to the same group
   as -c/-C/-F/-m that affects the metadata of the resulting commit
   and should stay at the original location in the list.  If you
   want to change anything around this area, I'd suggest moving
   --date=<date> close to this "options that affect commit's
   metadata" group.

> Signed-off-by: Phillip Wood <[email-masked]>
> ---
>  Documentation/git-commit.txt | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index a1d1d1246f..9de4dc5d66 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -8,11 +8,11 @@ git-commit - Record changes to the repository
>  SYNOPSIS
>  --------
>  [verse]
> -'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]
> +'git commit' [-a | --interactive | --patch] [--amend]
> +	   [(-c | -C | --fixup | --squash) <commit>] [-F <file> | -m <msg>]
> +	   [--allow-empty] [--allow-empty-message] [--no-verify] [-e]
> +	   [--reset-author] [--author=<author>] [--date=<date>]
> +	   [--cleanup=<mode>] [-v] [-u<mode>] [--dry-run] [--[no-]status]
>  	   [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]]
>  	   [-S[<keyid>]] [--] [<pathspec>...]