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

From: Jari Aalto <jari.aalto@cante.net>
Date: Dec 1, 2010, 22:45 UTC
Message-ID: <87mxopt8my.fsf@picasso.cante.net>
In-Reply-To: <295D1E95-1C61-4960-8C9C-BDB0BD4A1A50@sb.org>

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.

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).

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.

Jari