Re: [PATCH 2/3] commit: reorder synopsis
- From
- Phillip Wood <phillip.wood123@gmail.com>
- Date
- Sep 22, 2020, 13:27 UTC
- Message-ID
- <2a14d3d2-743c-215e-aa69-de75a576f685@gmail.com>
- In-Reply-To
- <xmqqft7acre2.fsf@gitster.c.googlers.com>
On 22/09/2020 06:27, Junio C Hamano wrote:
Show 11 quoted lines
> "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:
I agree the changes are a bit subjective, I thought --dry-run -u<mode> and -v were probably not as important enough to justify their position on the first line and it sounds like you basically agree with that.
Show 8 quoted lines
> - "--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.
That's a mistake I did not intend to remove it, thanks for spotting that
Show 18 quoted lines
> - "-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.
I was trying to group the author/date related option together - they all affect the metadata of the resulting commit
What do you think to
-'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>...]
--dry-run and -v are demoted. -u<mode> is moved next to --[no-]status as they are related. -s is restored but moved and the author/date related options are moved up to join the other options that affect the commit metadata. The downside is that --allow-empty and friends end up being moved down a line as a consequence of keeping all the commit metadata related options together.
If you are happy I'll redo the commit message based on your suggestions above
Thanks
Phillip
Show 27 quoted lines
> > >> 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>...]