Re: [PATCH] git-commit.txt: Order options alphabetically

From: Kevin Ballard <kevin@sb.org>
Date: Dec 1, 2010, 22:52 UTC
Message-ID: <E02740CE-37EE-4701-BB2D-18AD493D1C05@sb.org>
In-Reply-To: <87mxopt8my.fsf@picasso.cante.net>

On Dec 1, 2010, at 2:45 PM, Jari Aalto wrote:

Show 33 quoted lines

> 2010-12-01 23:58 Kevin Ballard <kevin@sb.org>:
>> On Dec 1, 2010, at 11:30 AM, Junio C Hamano wrote:
>> 
>> Trying to make the manpage look "nice" at the expense of removing
>> functional grouping is misguided.
> 
> Please explain where is the removed functionality in here:
> 
> GIT-COMMIT(1)                      Git Manual                     GIT-COMMIT(1)
> 
> OPTIONS
>       -a, --all
>           Tell the command to automatically stage files that have been
>           modified and deleted, but new files you have not told git about are
>           not affected.
> 
>       -C <commit>, --reuse-message=<commit>
>           Take an existing commit object, and reuse the log message and the
>           authorship information (including the timestamp) when creating the
>           commit.
> 
>       -c <commit>, --reedit-message=<commit>
>           Like -C, but with -c the editor is invoked, so that the user can
>           further edit the commit message.
> 
>       --reset-author
>           When used with -C/-c/--amend options, declare that the authorship of
>           the resulting commit now belongs of the committer. This also renews
>           the author timestamp.
> 
> What is the reason --reset-author is in that position? What
> functionality is serves? There are loads of similar ones. I don't see
> any group. Neither probably Joe Average.

It's entirely possible that this isn't ordered well, but from your quoted text I would assume --reset-author is there because it's related to the -C and -c flags (which directly precede it). In fact, if it wasn't for the current ordering, I never would have even known about that flag.

> To me the git-pages do not look that professional when options are
> whereever. Take 10 manual pages side by side in terminals and the
> options are chaos (try locating some option, say "-v", on every command
> and try to figure if it serves same purpose in every command or not).

You seem overly concerned with the visual aesthetics and not at all with the actual content.

> When the pages list options in alphabetical order, it doesn't take long
> to compare commands: similarities and differences in options, or missing
> options, or inconsistencies for that matter.

Why would you compare commands like that? There's really no reason at all to believe that the -c flag for one command is even related to the -c flag for another command.

-Kevin Ballard