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.) - Ted - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html