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

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

[jari.aalto]

From: Jari Aalto <jari.aalto@cante.net>


Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-commit.txt |  220 +++++++++++++++++++++---------------------
 1 files changed, 110 insertions(+), 110 deletions(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 42fb1f5..770f20b 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -59,73 +59,6 @@ OPTIONS
 	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.
-
---short::
-	When doing a dry-run, give the output in the short-format. See
-	linkgit:git-status[1] for details. Implies `--dry-run`.
-
---porcelain::
-	When doing a dry-run, give the output in a porcelain-ready
-	format. See linkgit:git-status[1] for details. Implies
-	`--dry-run`.
-
--z::
-	When showing `short` or `porcelain` status output, terminate
-	entries in the status output with NUL, instead of LF. If no
-	format is given, implies the `--porcelain` output format.
-
--F <file>::
---file=<file>::
-	Take the commit message from the given file.  Use '-' to
-	read the message from the standard input.
-
---author=<author>::
-	Override the commit author. Specify an explicit author using the
-	standard `A U Thor <author@example.com>` format. Otherwise <author>
-	is assumed to be a pattern and is used to search for an existing
-	commit by that author (i.e. rev-list --all -i --author=<author>);
-	the commit author is then copied from the first such commit found.
-
---date=<date>::
-	Override the author date used in the commit.
-
--m <msg>::
---message=<msg>::
-	Use the given <msg> as the commit message.
-
--t <file>::
---template=<file>::
-	Use the contents of the given file as the initial version
-	of the commit message. The editor is invoked and you can
-	make subsequent changes. If a message is specified using
-	the `-m` or `-F` options, this option has no effect. This
-	overrides the `commit.template` configuration variable.
-
--s::
---signoff::
-	Add Signed-off-by line by the committer at the end of the commit
-	log message.
-
--n::
---no-verify::
-	This option bypasses the pre-commit and commit-msg hooks.
-	See also linkgit:githooks[5].
-
 --allow-empty::
 	Usually recording a commit that has the exact same tree as its
 	sole parent commit is a mistake, and the command prevents you
@@ -138,23 +71,6 @@ OPTIONS
        empty commit message without using plumbing commands like
        linkgit:git-commit-tree[1].
 
---cleanup=<mode>::
-	This option sets how the commit message is cleaned up.
-	The  '<mode>' can be one of 'verbatim', 'whitespace', 'strip',
-	and 'default'. The 'default' mode will strip leading and
-	trailing empty lines and #commentary from the commit message
-	only if the message is to be edited. Otherwise only whitespace
-	removed. The 'verbatim' mode does not change message at all,
-	'whitespace' removes just leading/trailing whitespace lines
-	and 'strip' removes both whitespace and commentary.
-
--e::
---edit::
-	The message taken from file with `-F`, command line with
-	`-m`, and from file with `-C` are usually used as the
-	commit log message unmodified.  This option lets you
-	further edit the message taken from these sources.
-
 --amend::
 	Used to amend the tip of the current branch. Prepare the tree
 	object you would want to replace the latest commit as usual
@@ -180,6 +96,68 @@ You should understand the implications of rewriting history if you
 amend a commit that has already been published.  (See the "RECOVERING
 FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
 
+--author=<author>::
+	Override the commit author. Specify an explicit author using the
+	standard `A U Thor <author@example.com>` format. Otherwise <author>
+	is assumed to be a pattern and is used to search for an existing
+	commit by that author (i.e. rev-list --all -i --author=<author>);
+	the commit author is then copied from the first such commit found.
+
+-c <commit>::
+--reedit-message=<commit>::
+	Like '-C', but with '-c' the editor is invoked, so that
+	the user can further edit the commit message.
+
+-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.
+
+--cleanup=<mode>::
+	This option sets how the commit message is cleaned up.
+	The  '<mode>' can be one of 'verbatim', 'whitespace', 'strip',
+	and 'default'. The 'default' mode will strip leading and
+	trailing empty lines and #commentary from the commit message
+	only if the message is to be edited. Otherwise only whitespace
+	removed. The 'verbatim' mode does not change message at all,
+	'whitespace' removes just leading/trailing whitespace lines
+	and 'strip' removes both whitespace and commentary.
+
+--date=<date>::
+	Override the author date used in the commit.
+
+--dry-run::
+	Do not create a commit, but show a list of paths that are
+	to be committed, paths with local changes that will be left
+	uncommitted and paths that are untracked.
+
+-e::
+--edit::
+	The message taken from file with `-F`, command line with
+	`-m`, and from file with `-C` are usually used as the
+	commit log message unmodified.  This option lets you
+	further edit the message taken from these sources.
+
+-F <file>::
+--file=<file>::
+	Take the commit message from the given file.  Use '-' to
+	read the message from the standard input.
+
+-m <msg>::
+--message=<msg>::
+	Use the given <msg> as the commit message.
+
+-n::
+--no-verify::
+	This option bypasses the pre-commit and commit-msg hooks.
+	See also linkgit:githooks[5].
+
+--no-status::
+	Do not include the output of linkgit:git-status[1] in the
+	commit message template when using an editor to prepare the
+	default commit message.  See option `--status'.
+
 -i::
 --include::
 	Before making a commit out of staged contents so far,
@@ -199,6 +177,50 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
 	the last commit without committing changes that have
 	already been staged.
 
+-q::
+--quiet::
+	Suppress commit summary message.
+
+--status::
+	Include the output of linkgit:git-status[1] in the commit
+	message template when using an editor to prepare the commit
+	message.  Defaults to on, but can be used to override
+	configuration variable commit.status.  See option `--no-status'.
+
+--porcelain::
+	When doing a dry-run, give the output in a porcelain-ready
+	format. See linkgit:git-status[1] for details. Implies
+	`--dry-run`.
+
+--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.
+
+-s::
+--signoff::
+	Add Signed-off-by line by the committer at the end of the commit
+	log message.
+
+--short::
+	When doing a dry-run, give the output in the short-format. See
+	linkgit:git-status[1] for details. Implies `--dry-run`.
+
+-t <file>::
+--template=<file>::
+	Use the contents of the given file as the initial version
+	of the commit message. The editor is invoked and you can
+	make subsequent changes. If a message is specified using
+	the `-m` or `-F` options, this option has no effect. This
+	overrides the `commit.template` configuration variable.
+
+-v::
+--verbose::
+	Show unified diff between the HEAD commit and what
+	would be committed at the bottom of the commit message
+	template.  Note that this diff output doesn't have its
+	lines prefixed with '#'.
+
 -u[<mode>]::
 --untracked-files[=<mode>]::
 	Show untracked files (Default: 'all').
@@ -216,32 +238,10 @@ See linkgit:git-config[1] for configuration variable
 used to change the default for when the option is not
 specified.
 
--v::
---verbose::
-	Show unified diff between the HEAD commit and what
-	would be committed at the bottom of the commit message
-	template.  Note that this diff output doesn't have its
-	lines prefixed with '#'.
-
--q::
---quiet::
-	Suppress commit summary message.
-
---dry-run::
-	Do not create a commit, but show a list of paths that are
-	to be committed, paths with local changes that will be left
-	uncommitted and paths that are untracked.
-
---status::
-	Include the output of linkgit:git-status[1] in the commit
-	message template when using an editor to prepare the commit
-	message.  Defaults to on, but can be used to override
-	configuration variable commit.status.
-
---no-status::
-	Do not include the output of linkgit:git-status[1] in the
-	commit message template when using an editor to prepare the
-	default commit message.
+-z::
+	When showing `short` or `porcelain` status output, terminate
+	entries in the status output with NUL, instead of LF. If no
+	format is given, implies the `--porcelain` output format.
 
 \--::
 	Do not interpret any more arguments as options.
-- 
1.7.2.3

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

[Jonathan Nieder]

Hi again,

jari.aalto@cante.net wrote:

> [Subject: [PATCH] git-commit.txt: Order options alphabetically]
>
> Signed-off-by: Jari Aalto <jari.aalto@cante.net>

Here's what Documentation/SubmittingPatches has to say.

	[...] patches which plainly describe the things that
	help reviewers check the patch, and future maintainers understand
	the code, are the most beautiful patches.  Descriptions that summarise
	the point in the subject well, and describe the motivation for the
	change, the approach taken by the change, and if relevant how this
	differs substantially from the prior version, can be found on Usenet
	archives back into the late 80's.  Consider it like good Netiquette,
	but for code.

Here, you've explained what the patch does, but not why.  How are
reviewers to evaluate whether it succeeded?

If the goal is sorted option lists in all manpages, that will _have_
to be automated.  Some manpages read some and not all of their options
from an external file.  But before we deal with that: why would I want
sorted option lists in all manpages?

Sorting can sometimes be an improvement; it just seems better to
mention the particulars of the situation and why sorting rather than
some thematic grouping is appropriate in a given case.

Hope that helps,
Jonathan

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

[Jari Aalto]

2010-12-01 18:50 Jonathan Nieder <jrnieder@gmail.com>:
> If the goal is sorted option lists in all manpages, that will _have_
> to be automated.

Who is going to write that script? I'm afraid that will never happen.

It's easier and faster to edit. One page at a time. As time allows.
Nobody is going take vacation and do it once for all. Bit by bit is
better approach.

> why would I want sorted option lists in all manpages?

Does that really need an answer? You read from top to bottom, therefore
A-Z. Well, GNU uses it in manula pages. It looks good, it looks
professional, it looks clean. And it works when searching (= no
oriantation problems).

Jari

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

[Jakub Narebski]

Jari, could you please do not cull Cc list, if possible?  Thanks in
advance.

Jari Aalto <jari.aalto@cante.net> writes:
> 2010-12-01 18:50 Jonathan Nieder <jrnieder@gmail.com>:

> > If the goal is sorted option lists in all manpages, that will _have_
> > to be automated.
> 
> Who is going to write that script? I'm afraid that will never happen.
> 
> It's easier and faster to edit. One page at a time. As time allows.
> Nobody is going take vacation and do it once for all. Bit by bit is
> better approach.

But because some manpages "include" other pages (to refactor common
options), it would be impossible to sort alphabetically options in all
manpages.  So why bother with impossible?  It would only introduce
inconsistency.

> > why would I want sorted option lists in all manpages?
> 
> Does that really need an answer? You read from top to bottom, therefore
> A-Z. Well, GNU uses it in manual pages. 

What do you mean by "GNU" here?

>                                          It looks good, it looks
> professional, it looks clean. And it works when searching (= no
> orientation problems).

It works if you have separate user's documentation from reference
documentation.  GNU projects were meant to have manpages as reference,
and info pages as user's documentation.  Options sorted alphabetically
might make sense for reference documentation.  

But git manpages doesn't serve _only_ as reference documentation.  And
learning commands from manpages where options are sorted alphabetically
instead of grouped together by function *suck* big time.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

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

[Jari Aalto]

2010-12-01 19:48 Jakub Narebski <jnareb@gmail.com>:
>> 2010-12-01 18:50 Jonathan Nieder <jrnieder@gmail.com>:
>
> But because some manpages "include" other pages (to refactor common
> options), it would be impossible to sort alphabetically options in all
> manpages.  So why bother with impossible?  It would only introduce
> inconsistency.

Decresing entropy is better goal even if we cannot make it perfect. We
do what we can. And there are many pages that don't use include.

I don't mind work. You just watch and lean back.

>> professional, it looks clean. And it works when searching (= no
>> orientation problems).
>
> It works if you have separate user's documentation from reference
> documentation.  GNU projects were meant to have manpages as reference,
> and info pages as user's documentation.  Options sorted alphabetically
> might make sense for reference documentation.

It makes sense regardless. Printing literature and how people read and
search information hasn't chnage since printing was invented.

> But git manpages doesn't serve _only_ as reference documentation.  And
> learning commands from manpages where options are sorted alphabetically
> instead of grouped together by function *suck* big time.

Nope. Manual pages are not where people learn things any more. They
Google. They buy books. Teh copy from fellow worker. 

The manual pages main use it as reference material. We don't need to
fight the obvious.

Jari

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

[Junio C Hamano]

Jari Aalto <jari.aalto@cante.net> writes:

>> why would I want sorted option lists in all manpages?
>
> Does that really need an answer?

Yes.

> You read from top to bottom, therefore
> A-Z.

I used to think that back when I referred to printed documentation more
often than online, but not anymore.  Alphabetical ordering is somewhat
last century; the documentation is often more useful if the options are
grouped together by features and concepts they relate to.

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

[Kevin Ballard]

On Dec 1, 2010, at 11:30 AM, Junio C Hamano wrote:

>> You read from top to bottom, therefore
>> A-Z.
> 
> I used to think that back when I referred to printed documentation more
> often than online, but not anymore.  Alphabetical ordering is somewhat
> last century; the documentation is often more useful if the options are
> grouped together by features and concepts they relate to.

I completely agree. Alphabetical sorting is only useful when you already
know the name of the command you want, and you have no search function.
If you don't know the name of the command you want, then grouping by
functionality is far better, and if you have a search function, then there
is no real benefit at all to A-Z sorting. Trying to make the manpage look
"nice" at the expense of removing functional grouping is misguided.

-Kevin Ballard

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

[Jari Aalto]

2010-12-01 21:30 Junio C Hamano <gitster@pobox.com>:
>
> Alphabetical ordering is somewhat last century

Tell me aftter many more decades and I may believe it. When computer
screen is no more alike print media.

> the documentation is often more useful if the options are
> grouped together by features and concepts they relate to.

Where do you see grouping all the sudden? Manaula pages are not
primarily used to learn things, they are used as reference. Just like
Book indexes.

I haven't seed anyone for 10's of years who would have read full manaul
page from top to botton; every single line at one stop.

They come and go, come and go to read it. Learn bit by bit. And there is
the strenght od proper indexing, the alphabetical.

Jari

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

[Jari Aalto]

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

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

[Kevin Ballard]

You may want to invest in a spell-checker.

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

>> the documentation is often more useful if the options are
>> grouped together by features and concepts they relate to.
> 
> Where do you see grouping all the sudden? Manaula pages are not
> primarily used to learn things, they are used as reference. Just like
> Book indexes.

Most certainly they are used to learn things. Especially with tools like git.
Don't know what options you can give to git-diff? Read the manpage!

> I haven't seed anyone for 10's of years who would have read full manaul
> page from top to botton; every single line at one stop.
> 
> They come and go, come and go to read it. Learn bit by bit. And there is
> the strenght od proper indexing, the alphabetical.

Indexing, sure, but the actual manpage is not an index. A-Z ordering makes
no sense for the manpage. When people read, chunk by chunk, they expect
related functionality. It especially helps with discoverability. For example,
I know of the -w flag to git-diff that tells it to ignore whitespace. I'm not
certain this does exactly what I want, so I pop open the manpage, search for
-w, and read it. And I'm right, it doesn't do what I want. But right next to
it is the flag -b, and that _does_ do precisely what I want. If the manpage
was ordered alphabetically, I'd likely have never found the -b flag. As it is,
all 3 whitespace-related flags to git-diff are grouped together, and it helps
not only with reading the manpage for the first time (as I learn all related
concepts at the same time), but with discovering the related flags when I go
back to read documentation on the flags I already know.

-Kevin Ballard

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

[Kevin Ballard]

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

> 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

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

[Jari Aalto]

2010-12-02 00:52 Kevin Ballard <kevin@sb.org>:
> On Dec 1, 2010, at 2:45 PM, Jari Aalto wrote:
>> What is the reason --reset-author is in that position? What
>
> It's entirely possible...

The reader have to guess "imagined groups"? Hm, that's interesting.

>> To me the git-pages do not look that professional...
>
> You seem overly concerned with the visual aesthetics and not at all with the
> actual content.

Humans read visually. It's built in. Distractions slow down. Try writing

    abcdef = 1
    x123.213.123..123. = 4
    sdaölkasd = 1

vs.

    abcdef              = 1
    x123.213.123..123.  = 4
    sdaölkasd           = 1

There is a reason why people like Excel cells. Not my invention.

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

I take it you have written loads of software. The reasons come from
standard Software Development and Quality auditions. Git's command line
is inconsistent in many places and there is room for improvement.
Documentation is one way to spot those.

And ther eis perfect reasons to, again, expect consistency on some level
of command options to mean same thing

Like why some commands need number in:

    -n NUMBER

Whereas other's use:

    -NUMBER

Examples like that.

Jari

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

[Jari Aalto]

2010-12-02 00:49 Kevin Ballard <kevin@sb.org>:
> You may want to invest in a spell-checker.
>  ... Manaula pages are not primarily used to learn things, they are
>  used as reference.
>
> Most certainly they are used to learn things. Especially with tools like git.
> Don't know what options you can give to git-diff? Read the manpage!

That little word "primarily." You don't find anyone who learnt from
manual page first is person is on his 20's. Google is full of Git
videos. Guess which won the sexiest contest.

I'm addressing the current audience, this generation, not old farts like
me. Linus, Hamano et all, when computers were Golden age and Z-something.

Jari

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

[Kevin Ballard]

On Dec 1, 2010, at 3:05 PM, Jari Aalto wrote:

> 2010-12-02 00:49 Kevin Ballard <kevin@sb.org>:
>> You may want to invest in a spell-checker.
>> ... Manaula pages are not primarily used to learn things, they are
>> used as reference.
>> 
>> Most certainly they are used to learn things. Especially with tools like git.
>> Don't know what options you can give to git-diff? Read the manpage!
> 
> That little word "primarily." You don't find anyone who learnt from
> manual page first is person is on his 20's. Google is full of Git
> videos. Guess which won the sexiest contest.

How about me? I'm 25, I've been using git for a couple of years, and the manpages
have always been my primary documentation.

The videos are great at convincing people to use git. But people always turn to
the manpages in order to learn the details.

-Kevin Ballard

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

[Jari Aalto]

2010-12-02 01:40 Kevin Ballard <kevin@sb.org>:
> On Dec 1, 2010, at 3:05 PM, Jari Aalto wrote:
>> That little word "primarily." You don't find anyone who learnt from
>> manual page first is person is on his 20's. Google is full of Git
>> videos. Guess which won the sexiest contest.
>
> How about me? I'm 25, I've been using git for a couple of years, and
> the manpages have always been my primary documentation.

And your background before that (those 5 years?). Can you say that
you're an average, to fit a imagned genralized 20's audience? I'm sure
you have heard how hard it is nowadays to teach programming or Software
Engineering in Universities.

> The videos are great at convincing people to use git. But people
> always turn to the manpages in order to learn the details.

"Details". You said it. They are consulted.

Not to learn as a primary method per se. The manual pages are too
technical; not really their fault, they are supposed to be. As "manuals"
are.

The progression goes:

    - Google, more Google, and yet more Google (or the next line swapped)
    - Videos, and Google blogs
    - Co-worker, Co-student, Co-<whatever>
    - Git Book, The Pro Book etc. (when there is time, free of other duties).
    - And more Google.
    ... man pages at the bottom after you have used Git for some time.

To add perspective: there is no manual pages in Windows. What you have
is a browser that is one click away from information.

Jari

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

[Jan Krüger]

[Cc un-culled]

--- Jari Aalto <jari.aalto@cante.net> wrote:

> The reader have to guess "imagined groups"? Hm, that's interesting.

Perhaps a more desirable (and agreeable) patch would introduce group
subheadings, then? I agree with the majority of people who chimed in
here that functional grouping is a good thing. Perhaps we should
actually commit to that by having explicit groups.

In rev-list-related options we already have a couple of explicit
groups. I think I'd go insane if I ever had to find anything in there
without those groups.

> [...] Git's command
> line is inconsistent in many places and there is room for improvement.
> Documentation is one way to spot those.

That seems to be the only reason you've brought forward for alphabetic
sorting, except the claim that "people read from top to
bottom" (which is essentially true, but I don't think anybody would
read, say, a printed dictionary all the way through; the alphabetic
ordering there is for being able to index/search the content in the
absence of another way to index/search).

In any case, the end user will probably be more often interested in
appropriately grouped options than in being able to easily find
inconsistencies between various commands.

-Jan

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

[Jari Aalto]

2010-12-02 10:53 Jan Krüger <jk@jk.gs>:
> [Cc un-culled]
>
> --- Jari Aalto <jari.aalto@cante.net> wrote:
>
>> The reader have to guess "imagined groups"? Hm, that's interesting.
>
> Perhaps a more desirable (and agreeable) patch would introduce group
> subheadings, then?

Yes, that's the standard way of doing groups. Just like it's being done
in other manual pages that are huge. But it is not being done in small
manual pages. GNU project certainly doesn't in general.

I agree tat doing "groups" makes only sense on pages that have large
number of options. For a screenful, it's more distracting than worth.

> In rev-list-related options we already have a couple of explicit
> groups.

I can't find that manual page or file under Documentation/, could you
help here?

>> [...] Git's command
>> line is inconsistent in many places and there is room for improvement.
>> Documentation is one way to spot those.
>
> That seems to be the only reason you've brought forward for alphabetic
> sorting
>
> In any case, the end user will probably be more often interested in
> appropriately grouped options than in being able to easily find
> inconsistencies between various commands.

Well. In my experience (having watched others to learn) the manual pages
are not the source used for learning.

    - They are technical documentation
    - They are reference documentation
    - They are visited, then discarded, visited and discarded.

People primarily learn outside of manaula pages. No wonder Books are
being written. Compare:

    - Have you seen the Web SVN book?
    - Have you seen the Web HG Book?

People go to the manual pages once they have a specific need for
infomation and details. I could sketch these uses of manual pages:

    - Someone throws up a git command (IRC #git, Blogs, Web page). What
      do all those unreadable one letter options mean? Gosh they don't
      even mean the save accross different git* programs.

      > He searches manual pages A-Z, easy to spot all options. Not
      > interested in related things. He tries to understand the
      > command, script etc.

    - Someone is learning Git.

      > He certainly does not start from manual pages. Other soources of
      > information are more in to him. Besides  Windows does not have those.
      > We might guess what MySGIt as other do: they reach Google button.

      This person just wants to solve a problem, get things done, the
      faster the better. The easier the better, the less thinking the
      better.

    - Geek. He wants to learn inside out.

      > He digestestes all. Related options, related pages, flipping
      > form man to man as he knows all the glory details is just there.

It all depends if it is desireable to make pages more approachable to
the average group, or are they kept to serve only small core audience.

There are 100+ manual pages in the git distribution. You get even
disoriented in shere numbers of them. And you have to throw dice to
figure out in what page that information might be you are currently in
need.

It's classical case of how to arrange information for easy retrieval.
Think Libraries as model.

Jari

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

[Jakub Narebski]

Please do not cull Cc-list, i.e. respond replying to all people who
participate in given (sub)thread.  (If it is not possible, tell why).

Jari Aalto <jari.aalto@cante.net> writes:
> 2010-12-02 10:53 Jan Krüger <jk@jk.gs>:
> > [Cc un-culled]
> >
> > --- Jari Aalto <jari.aalto@cante.net> wrote:
> >
> > > The reader have to guess "imagined groups"? Hm, that's interesting.
> >
> > Perhaps a more desirable (and agreeable) patch would introduce group
> > subheadings, then?
> 
> Yes, that's the standard way of doing groups. Just like it's being done
> in other manual pages that are huge. But it is not being done in small
> manual pages. GNU project certainly doesn't in general.

Note that GNU project produced many more or less stupid/smart
conventions.  It doesn't mean that we should follow them blindly
(alphabetical sorting of options in manpages, GNU ChangeLog format,
GNU indent style for C).

> 
> I agree that doing "groups" makes only sense on pages that have large
> number of options. For a screenful, it's more distracting than worth.

The other side of the fact that creating subsections grouping types of
options makes only sense for pages/groups that have large number of
options is that we need sorting by function, grouping related options
together.  See also use case below.

> > In rev-list-related options we already have a couple of explicit
> > groups.
> 
> I can't find that manual page or file under Documentation/, could you
> help here?

"man git-rev-list", Documentation/rev-list-options.txt
 
[...]
> Well. In my experience (having watched others to learn) the manual pages
> are not the source used for learning.

Counterexample: Perl.

> People go to the manual pages once they have a specific need for
> infomation and details. I could sketch these uses of manual pages:
> 
>     - Someone throws up a git command (IRC #git, Blogs, Web page). What
>       do all those unreadable one letter options mean? Gosh they don't
>       even mean the same accross different git* programs.
> 
>       > He searches manual pages A-Z, easy to spot all options. Not
>       > interested in related things. He tries to understand the
>       > command, script etc.

Contrived use case.  Disregarded.

> 
>     - Someone is learning Git.
> 
>       > He certainly does not start from manual pages. Other soources of
>       > information are more in to him. Besides  Windows does not have those.

Did you check that 'man git-<cmd>' doesn't work on git on MS Windows
(msysGit, git from Cygwin)?

You can always use 'git --help <cmd>'.

>       > We might guess what MySGIt as other do: they reach Google button.
> 
>       This person just wants to solve a problem, get things done, the
>       faster the better. The easier the better, the less thinking the
>       better.

They read "Git User's Manual", or "Pro Git", or perhaps "Git Community Book"
(the first included with git, the second and third available on-line).

> 
>     - Geek. He wants to learn inside out.
> 
>       > He digests all. Related options, related pages, flipping
>       > form man to man as he knows all the glory details is just there.

And for geek grouping related options/config variables together is
helpful.


You omitted very important use case, something that was mentioned more
than once in this and related threads:

      - Someone wants to know/remember how to do something in Git.
        Assume that this someone knows git quite well, but not by heart.

      Here there is example that was give to you in this thread (or
      related subthread), namely someone checking the name of option that
      ignores whitespace, and because related options are grouped together
      the he/she realizes that he/she wants different but related option
      (-b/--ignore-space-change vs -w/--ignore-all-space).

      Another example could be someone searching for config options that
      affect git (re)packing performance.  Currently those config options
      are grouped together.

      If options are sorted alphabetically this task is made much harder.
      Note that he/she know how to use searching in pager or web browser.

> It all depends if it is desireable to make pages more approachable to
> the average group, or are they kept to serve only small core audience.
> 
> There are 100+ manual pages in the git distribution. You get even
> disoriented in sheer numbers of them. And you have to throw dice to
> figure out in what page that information might be you are currently in
> need.
> 
> It's classical case of how to arrange information for easy retrieval.
> Think Libraries as model.

Computerized index, or manual?  Perhaps it is classical case, but it is
outdated: modern solutions use folksonomies / labels / tagging rather than
Trove / Dewey classification or alphabetical sorting.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

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

[Jakub Narebski]

Jari Aalto <jari.aalto@cante.net> writes:
> 2010-12-01 19:48 Jakub Narebski <jnareb@gmail.com>:
> > > 2010-12-01 18:50 Jonathan Nieder <jrnieder@gmail.com>:
> >
> > But because some manpages "include" other pages (to refactor common
> > options), it would be impossible to sort alphabetically options in all
> > manpages.  So why bother with impossible?  It would only introduce
> > inconsistency.
> 
> Decreasing entropy is better goal even if we cannot make it perfect. We
> do what we can. And there are many pages that don't use include.

Increasing inconsistency is not good, and that would be the final side
effect.
 
> I don't mind work. You just watch and lean back.

But we do mind unnecessary code churn (well, in this case documentation
churn).  Unless you regard it as "academical" exercise.
 
The final decision on merging in (accepting) changes lies at git
maintainer.

> > > professional, it looks clean. And it works when searching (= no
> > > orientation problems).
> >
> > It works if you have separate user's documentation from reference
> > documentation.  GNU projects were meant to have manpages as reference,
> > and info pages as user's documentation.  Options sorted alphabetically
> > might make sense for reference documentation.
> 
> It makes sense regardless. Printing literature and how people read and
> search information hasn't changed since printing was invented.

How people search information *has* changed since printing was invented.

> > But git manpages doesn't serve _only_ as reference documentation.  And
> > learning commands from manpages where options are sorted alphabetically
> > instead of grouped together by function *suck* big time.
> 
> Nope. Manual pages are not where people learn things any more. They
> Google. They buy books. They copy from fellow worker.
> 
> The manual pages main use it as reference material. We don't need to
> fight the obvious.

Counterexample: Perl manpages.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

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

[Jan Krüger]

[Cc unculled again; I will ignore all further posts from you until you
stop culling or explain why you are ignoring all requests to stop
culling.]

--- Jari Aalto <jari.aalto@cante.net> wrote:

> Yes, that's the standard way of doing groups. Just like it's being
> done in other manual pages that are huge. But it is not being done in
> small manual pages. GNU project certainly doesn't in general.

What makes the GNU project the gold standard? They've got some pretty
weird conventions, such as their coding style.

> I agree tat doing "groups" makes only sense on pages that have large
> number of options. For a screenful, it's more distracting than worth.

You are "agreeing with" something I didn't say. That's not very helpful.

> Well. In my experience (having watched others to learn) the manual
> pages are not the source used for learning.

They were for me.

>     - They are technical documentation

I want related things in technical documentation to be grouped.

>     - They are reference documentation

I want related things in reference documentation to be grouped.

>     - They are visited, then discarded, visited and discarded.

Correct. Especially for that reason, I want related things to be
grouped. I don't want to scroll through the entire list of options just
to find everything related to what I want to do.

>     - Someone throws up a git command (IRC #git, Blogs, Web page).
> What do all those unreadable one letter options mean? Gosh they don't
>       even mean the save accross different git* programs.

The only realistic way around that is to stop using 

>       > He searches manual pages A-Z, easy to spot all options. Not
>       > interested in related things. He tries to understand the
>       > command, script etc.

Because everyone always knows whether the desired option is called
--skip-foo, --no-use-foo, --disable-foo, --no-foo, --antifoo or --bar?

In virtually all cases, I know what I want but not the name of the
option. It rarely happens that I know the name of the option but not
what it does.

>       This person just wants to solve a problem, get things done, the
>       faster the better. The easier the better, the less thinking the
>       better.

As mentioned, I believe that alphabetic ordering makes it harder and
take longer.

>       > He digestestes all. Related options, related pages, flipping
>       > form man to man as he knows all the glory details is just
>       > there.

Even then, learning works better if you learn things grouped by
similarities. Alphabetic ordering of the material just makes it harder.
You don't see the English teachers hand out vocabulary lessons in
alphabetic order, do you?

> There are 100+ manual pages in the git distribution. You get even
> disoriented in shere numbers of them. And you have to throw dice to
> figure out in what page that information might be you are currently in
> need.

That is correct, but none of your patches change anything about that.

> It's classical case of how to arrange information for easy retrieval.
> Think Libraries as model.

Have you ever been inside a library? The bookshelves are not ordered
alphabetically. There is a section for physics and a section for
zoology and a section for architecture. That makes it easier to find.

In fact, even before the advent of computers, the catalogs of libraries
were available in two forms: alphabetically ordered (which only helps
if you know the exact name of what you are looking for) and ordered by
category (which is pretty much the only way to find something if you
don't know exactly what you want, unless you want to read the whole
catalog back to front).



In any case, we can go around in circles forever on this. Our opinions
are different, and if we don't accept each others' arguments, nothing
will ever come of this. The next stage in a productive discussion is to
either stop bothering or to produce evidence. If you have any
scientific evidence that alphabetically ordered lists make it easier to
find things the names of which you don't know, I'll be happy to look at
it.

-Jan

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

[Erik Faye-Lund]

On Thu, Dec 2, 2010 at 12:05 AM, Jari Aalto <jari.aalto@cante.net> wrote:
> 2010-12-02 00:49 Kevin Ballard <kevin@sb.org>:
>> You may want to invest in a spell-checker.
>>  ... Manaula pages are not primarily used to learn things, they are
>>  used as reference.
>>
>> Most certainly they are used to learn things. Especially with tools like git.
>> Don't know what options you can give to git-diff? Read the manpage!
>
> That little word "primarily." You don't find anyone who learnt from
> manual page first is person is on his 20's.

Stop making things up. I'm in my 20's and learned Git primarily by
reading the manual pages.

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

[Nguyen Thai Ngoc Duy]

I think you can start a fork now, with everything sorted
alphabetically. Massive changes do not fit well in git development
model. It causes lots of conflicts.

I would like to hear any user feedback from such a fork. If it proves
actually helpful for  end users, it would be merged eventually.
-- 
Duy

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

[jari.aalto]

From: Jari Aalto <jari.aalto@cante.net>


Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-commit.txt |  220 +++++++++++++++++++++---------------------
 1 files changed, 110 insertions(+), 110 deletions(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 42fb1f5..db9ed7e 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -59,73 +59,6 @@ OPTIONS
 	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.
-
---short::
-	When doing a dry-run, give the output in the short-format. See
-	linkgit:git-status[1] for details. Implies `--dry-run`.
-
---porcelain::
-	When doing a dry-run, give the output in a porcelain-ready
-	format. See linkgit:git-status[1] for details. Implies
-	`--dry-run`.
-
--z::
-	When showing `short` or `porcelain` status output, terminate
-	entries in the status output with NUL, instead of LF. If no
-	format is given, implies the `--porcelain` output format.
-
--F <file>::
---file=<file>::
-	Take the commit message from the given file.  Use '-' to
-	read the message from the standard input.
-
---author=<author>::
-	Override the commit author. Specify an explicit author using the
-	standard `A U Thor <author@example.com>` format. Otherwise <author>
-	is assumed to be a pattern and is used to search for an existing
-	commit by that author (i.e. rev-list --all -i --author=<author>);
-	the commit author is then copied from the first such commit found.
-
---date=<date>::
-	Override the author date used in the commit.
-
--m <msg>::
---message=<msg>::
-	Use the given <msg> as the commit message.
-
--t <file>::
---template=<file>::
-	Use the contents of the given file as the initial version
-	of the commit message. The editor is invoked and you can
-	make subsequent changes. If a message is specified using
-	the `-m` or `-F` options, this option has no effect. This
-	overrides the `commit.template` configuration variable.
-
--s::
---signoff::
-	Add Signed-off-by line by the committer at the end of the commit
-	log message.
-
--n::
---no-verify::
-	This option bypasses the pre-commit and commit-msg hooks.
-	See also linkgit:githooks[5].
-
 --allow-empty::
 	Usually recording a commit that has the exact same tree as its
 	sole parent commit is a mistake, and the command prevents you
@@ -138,23 +71,6 @@ OPTIONS
        empty commit message without using plumbing commands like
        linkgit:git-commit-tree[1].
 
---cleanup=<mode>::
-	This option sets how the commit message is cleaned up.
-	The  '<mode>' can be one of 'verbatim', 'whitespace', 'strip',
-	and 'default'. The 'default' mode will strip leading and
-	trailing empty lines and #commentary from the commit message
-	only if the message is to be edited. Otherwise only whitespace
-	removed. The 'verbatim' mode does not change message at all,
-	'whitespace' removes just leading/trailing whitespace lines
-	and 'strip' removes both whitespace and commentary.
-
--e::
---edit::
-	The message taken from file with `-F`, command line with
-	`-m`, and from file with `-C` are usually used as the
-	commit log message unmodified.  This option lets you
-	further edit the message taken from these sources.
-
 --amend::
 	Used to amend the tip of the current branch. Prepare the tree
 	object you would want to replace the latest commit as usual
@@ -180,6 +96,68 @@ You should understand the implications of rewriting history if you
 amend a commit that has already been published.  (See the "RECOVERING
 FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
 
+--author=<author>::
+	Override the commit author. Specify an explicit author using the
+	standard `A U Thor <author@example.com>` format. Otherwise <author>
+	is assumed to be a pattern and is used to search for an existing
+	commit by that author (i.e. rev-list --all -i --author=<author>);
+	the commit author is then copied from the first such commit found.
+
+-c <commit>::
+--reedit-message=<commit>::
+	Like '-C', but with '-c' the editor is invoked, so that
+	the user can further edit the commit message.
+
+-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.
+
+--cleanup=<mode>::
+	This option sets how the commit message is cleaned up.
+	The  '<mode>' can be one of 'verbatim', 'whitespace', 'strip',
+	and 'default'. The 'default' mode will strip leading and
+	trailing empty lines and #commentary from the commit message
+	only if the message is to be edited. Otherwise only whitespace
+	removed. The 'verbatim' mode does not change message at all,
+	'whitespace' removes just leading/trailing whitespace lines
+	and 'strip' removes both whitespace and commentary.
+
+--date=<date>::
+	Override the author date used in the commit.
+
+--dry-run::
+	Do not create a commit, but show a list of paths that are
+	to be committed, paths with local changes that will be left
+	uncommitted and paths that are untracked.
+
+-e::
+--edit::
+	The message taken from file with `-F`, command line with
+	`-m`, and from file with `-C` are usually used as the
+	commit log message unmodified.  This option lets you
+	further edit the message taken from these sources.
+
+-F <file>::
+--file=<file>::
+	Take the commit message from the given file.  Use '-' to
+	read the message from the standard input.
+
+-m <msg>::
+--message=<msg>::
+	Use the given <msg> as the commit message.
+
+-n::
+--no-verify::
+	This option bypasses the pre-commit and commit-msg hooks.
+	See also linkgit:githooks[5].
+
+--no-status::
+	Do not include the output of linkgit:git-status[1] in the
+	commit message template when using an editor to prepare the
+	default commit message.  See option `--status'.
+
 -i::
 --include::
 	Before making a commit out of staged contents so far,
@@ -199,6 +177,50 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
 	the last commit without committing changes that have
 	already been staged.
 
+--porcelain::
+	When doing a dry-run, give the output in a porcelain-ready
+	format. See linkgit:git-status[1] for details. Implies
+	`--dry-run`.
+
+-q::
+--quiet::
+	Suppress commit summary message.
+
+--status::
+	Include the output of linkgit:git-status[1] in the commit
+	message template when using an editor to prepare the commit
+	message.  Defaults to on, but can be used to override
+	configuration variable commit.status.  See option `--no-status'.
+
+--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.
+
+-s::
+--signoff::
+	Add Signed-off-by line by the committer at the end of the commit
+	log message.
+
+--short::
+	When doing a dry-run, give the output in the short-format. See
+	linkgit:git-status[1] for details. Implies `--dry-run`.
+
+-t <file>::
+--template=<file>::
+	Use the contents of the given file as the initial version
+	of the commit message. The editor is invoked and you can
+	make subsequent changes. If a message is specified using
+	the `-m` or `-F` options, this option has no effect. This
+	overrides the `commit.template` configuration variable.
+
+-v::
+--verbose::
+	Show unified diff between the HEAD commit and what
+	would be committed at the bottom of the commit message
+	template.  Note that this diff output doesn't have its
+	lines prefixed with '#'.
+
 -u[<mode>]::
 --untracked-files[=<mode>]::
 	Show untracked files (Default: 'all').
@@ -216,32 +238,10 @@ See linkgit:git-config[1] for configuration variable
 used to change the default for when the option is not
 specified.
 
--v::
---verbose::
-	Show unified diff between the HEAD commit and what
-	would be committed at the bottom of the commit message
-	template.  Note that this diff output doesn't have its
-	lines prefixed with '#'.
-
--q::
---quiet::
-	Suppress commit summary message.
-
---dry-run::
-	Do not create a commit, but show a list of paths that are
-	to be committed, paths with local changes that will be left
-	uncommitted and paths that are untracked.
-
---status::
-	Include the output of linkgit:git-status[1] in the commit
-	message template when using an editor to prepare the commit
-	message.  Defaults to on, but can be used to override
-	configuration variable commit.status.
-
---no-status::
-	Do not include the output of linkgit:git-status[1] in the
-	commit message template when using an editor to prepare the
-	default commit message.
+-z::
+	When showing `short` or `porcelain` status output, terminate
+	entries in the status output with NUL, instead of LF. If no
+	format is given, implies the `--porcelain` output format.
 
 \--::
 	Do not interpret any more arguments as options.
-- 
1.7.2.3