Subject: Re: [PATCH] Invert numbers and names in the git-shortlog summary mode.

From: Ingo Molnar <[email-masked]>
Date: Tue, 11 Dec 2007 16:48:41 +0100

* Pierre Habouzit <[email-masked]> wrote:

> > which is quite a bit confusing to someone who'd like to keep as few 
> > details of command line arguments in his head as possible :-)
> 
> Because git-shortlog insists on you passing a reference first, HEAD is 
> not implicit if you pass something that looks like a path first. This 
> is arguably wrong. What you meant here is:
> 
> $ git-shortlog -n -s HEAD kernel/
> 
> The reason IIRC is that git-shortlog once only read things on stdin, 
> and this keeps backward compatbility to `git-shortlog` without any 
> arguments.
> 
> Sometimes history hurts :) I don't think there is much we can do on a 
> short timescale. Maybe the old way can be slowly deprecated, and then 
> git-shortlog will be able to act like git-log.

if we are growing legacies in git this fast it will turn itself into CVS 
very quickly, give or take 20 years ;-) I think a straightforward usage 
model is paramount, so phasing out such inconsistencies as early as 
possible in the project's lifetime should be a priority IMHO. Git has a 
very, very 'refreshing' approach to information management, and that 
should permeate it all across. It's easy to be "fresh" in the beginning 
of a project - maintaining freshness for years is a lot harder. (i dont 
suggest to break compatibility, but to be aware of such inconsitencies 
and make it a priority to get rid of them. It does not help that such 
inconsistencies are only apparent to git newbies.)

another thing i noticed that bites git newbies is that there are 
commands that do not do the "obvious" thing (to a newbie) and there are 
commands that just dont tell what they are doing. It would be very 
helpful if git was just a little bit more verbose about what it does. 
I.e. use the standard output for ... actual output, and there will be an 
instant and pleasant feedback loop between newbie and tool.

It should basically "teach" the user along the way about what is being 
done, so that it quickly becomes an automatism. Especially where 
concepts differ from legacy SCMs. When is the index updated, when do 
files get modified, how branching works, etc.

for example, if i type "git-checkout" in a Linux kernel tree, it just 
sits there for up to a minute, and "does nothing". That is totally 
wrong, human-interaction wise. Then after a minute it just returns. What 
happened? Why? Where? A newbie would then try "git-checkout -v", using 
the well-established "verbose" flag, but that gives:

 Usage: /usr/bin/git-checkout [-q] [-f] [-b <new_branch>] [-m] [<branch>] [<paths>...]

That's what a newbie asks. We are trying to turn the world of SCM's 
upside down with git, and we should do that by teaching things gradually 
and by being very explicit what happens and why, when a command is typed 
;-)

i could go on and on with other examples. (should I ? ;-)

It's small, little details like that and if we fix a few dozen of them 
it will do _wonders_ to user education, really. The best tools are the 
ones that emit just about information to essentially give a tutorial to 
the newbie about the philosophy and workings of the tool - without being 
annoying to advanced users. It flattens the learning curve and increases 
adoption rate enormously. It also helps people learn their way out of 
the mental deformations that CVS causes ;-)

And we could do this by adding a -q "quiet" flag, to restore the current 
'silent' behavior of git. I could then do this in my .bashrc:

   alias git='git -q'

to get the old, quiet behavior. This issue is pretty much the only 
conceptual advantage i can see of the competition like hg/mercurial ;-)

Ok, enough ranting for today i guess =B-)

	Ingo