| Message ID | 80a69318b57348c59e45c0f8df1c342ef84388d4.1600695050.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | commit: add an option to reword the last commit | expand |
"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>...]
On 22/09/2020 06:27, Junio C Hamano wrote: > "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. > - "--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 > - "-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 > > >> 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>...]
Phillip Wood <phillip.wood123@gmail.com> writes: > -'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.
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>...]