Re: Hyphens and hiding core commands

[Theodore Tso <tytso@mit.edu>]

On Mon, Nov 27, 2006 at 06:18:54PM -0800, Junio C Hamano wrote:
> Read what I wrote again.  You can explain it without talking
> about index at all.  I really do not think you need to break
> "git commit" nor rename "update-index" to "resolve" to explain
> things to new people.

I think you're both right, and talking past each other to a certain
extent.  Yes, pedagogically it would be better to talk about "git
commit Makefile hello.c ..."; and "git commit -a" as a short-cut to
not have to list all of the files explicitly.

> The tutorial might be better reworked not to start talking about
> -a but start building small project from a newly created
> hello.c, git add it, and "git commit" (the first commit), then
> edit hello.c and "git commit hello.c" (the second commit).
> 
> Perhaps.

Carl was saying that the totorial should be changed to do this.  I
would change "perhaps" to "DEFINITELY".  

I would go further and argue that the man page for git-commit should
be changed to list the:

	git commit file ...
and
	git -a

alternatives first, and then talk about the index in a subsequent
paragraph (perhaps with a note that the first two usages are best for
novice users) might also be a good idea.  Yes, the man page is
supposed to be a reference, but some novice users do bother to try to
learn by reading the man page (shock!  horror!), and it might be good
if they don't run screaming into the night.

But hey, there's room for many distributed SCM's, and we can always
let those users use Mercurial and be happy....  (Just know that
project leaders who are worried about keeping their developer base
broad might choose Mercurial because it has a gentler learning curve
--- and that perhaps a few simple documentation changes plus some
syntatic sugar might make git much more attractive to them and to
novice git users.)