From: Junio C Hamano <gitster@pobox.com>
To: "Phillip Wood via GitGitGadget" <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, Phillip Wood <phillip.wood@dunelm.org.uk>
Subject: Re: [PATCH 2/3] commit: reorder synopsis
Date: Mon, 21 Sep 2020 22:27:49 -0700 [thread overview]
Message-ID: <xmqqft7acre2.fsf@gitster.c.googlers.com> (raw)
In-Reply-To: <80a69318b57348c59e45c0f8df1c342ef84388d4.1600695050.git.gitgitgadget@gmail.com> (Phillip Wood via GitGitGadget's message of "Mon, 21 Sep 2020 13:30:49 +0000")
"Phillip Wood via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>
> 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 <phillip.wood@dunelm.org.uk>
> ---
> 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>...]
next prev parent reply other threads:[~2020-09-22 5:28 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-21 13:30 [PATCH 0/3] commit: add an option to reword the last commit Phillip Wood via GitGitGadget
2020-09-21 13:30 ` [PATCH 1/3] commit docs: use backquotes when quoting options Phillip Wood via GitGitGadget
2020-09-21 13:30 ` [PATCH 2/3] commit: reorder synopsis Phillip Wood via GitGitGadget
2020-09-22 5:27 ` Junio C Hamano [this message]
2020-09-22 13:27 ` Phillip Wood
2020-09-22 16:16 ` Junio C Hamano
2020-09-21 13:30 ` [PATCH 3/3] commit: add an option the reword HEAD Phillip Wood via GitGitGadget
2020-09-21 15:43 ` Eric Sunshine
2020-09-21 18:05 ` Phillip Wood
2020-09-21 18:12 ` Eric Sunshine
2020-09-21 19:27 ` Junio C Hamano
2020-09-22 13:38 ` Phillip Wood
2020-09-22 16:54 ` Junio C Hamano
2020-09-21 17:04 ` Christian Couder
2020-09-21 18:01 ` Phillip Wood
2020-09-23 10:22 ` Johannes Schindelin
2020-09-23 18:23 ` Phillip Wood
2020-09-23 20:42 ` Johannes Schindelin
2020-09-24 9:58 ` Phillip Wood
2020-09-24 16:58 ` Junio C Hamano
2020-09-21 16:15 ` [PATCH 0/3] commit: add an option to reword the last commit Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqft7acre2.fsf@gitster.c.googlers.com \
--to=gitster@pobox.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=phillip.wood@dunelm.org.uk \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).