Re: Hyphens and hiding core commands

From: Theodore Tso <tytso@mit.edu>
Date: Nov 28, 2006, 05:40 UTC
Message-ID: <20061128054032.GC11122@thunk.org>
In-Reply-To: <7vk61gcnzl.fsf@assigned-by-dhcp.cox.net>

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.

Show 6 quoted lines

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