On Mon, 27 Nov 2006 16:42:14 -0800, Junio C Hamano wrote: > I think you are teaching backwards. Couldn't you start like this? > > "git commit" takes the list of paths you want to commit. I've always started teaching with: git init-db git add file git commit -m "Initial commit" # edit file git commit -a -m "edit file" And at that point I've either apologized about "-a" or been asked a question about it. Every time. But it's the tutorial we were talking about: http://www.kernel.org/pub/software/scm/git/docs/tutorial.html That has 6 examples of commit being used, and all of them are with "commit -a". What "git commit" does without -a must certainly be a question in the mind of any reader, (the tutorial doesn't mention anything). And unlike when I'm teaching in person, when the reader reads the tutorial, there's no person to explain the situation. The reader might just remain confused, or they might consult the documentation for git-commit and find a first sentence that says: Updates the index file for given paths, or all modified files if -a is specified, and makes a commit object. And then we're back to the question of "what the heck is an index, and why do I care?". If the "commit the index" operation were moved to a non-default command-line option of git-commit, then the commit command could be explained without having to introduce the notion of the index at all. This would be a good thing. I don't think we have any introductory documentation that introduces the index until the "core tutorial" and my goal here is to allow an introduction to using git that doesn't require that level of detail. One of the arguments I got here on the git mailing list when I first brought up these kinds of "hide the index" proposals, (back in February or so), was that the index is essential to understand for merging anyway, and that I should just teach it early on. I've tried the "teach it early" approach in the months since and found it to be largely a failure. Most new users react by deciding that git is more complicated than other systems, or that it's more specialized or not targeted at someone with their needs. As for merging, I'd rather introduce the new "git resolve" syntax so that merging could be explained in terms of the working tree without having to fully understand the index either. If we could fix "git commit" and add "git resolve" I think we would most of the confusion/complaints that I've encountered in 8 months of teaching git. There would still be some aspects of "git diff" that are potentially confusing without understanding the index, but that's been much less of a problem than "commit -a" in my experience. -Carl
Attachment:
pgpvsCpRaukRg.pgp
Description: PGP signature