Carl Worth [off-list ref] writes:
Yes, there is a learning curve. There's the "once you grok the index"
stuff you just mentioned. And it's really backwards to have to teach
people that the "basic" way to do something is with a command line
that looks more complex, ("commit -a"), and that "once you learn more
you'll understand what that -a is all about and you'll know when not
to use it".
I think you are teaching backwards. Couldn't you start like this?
"git commit" takes the list of paths you want to commit.
Editing hello.c and saying "git commit hello.c" would
commit your changes to hello.c. It is cumbersome to
list everything when your edit is all over the place,
and in such a case you can say "git commit -a" to mean
"everything I changed".
Later you can enhance that experience by teaching them index,
saying:
You might want to tell git that your change to this file
is more or less complete, even when you are not ready to
commit the whole thing. You could use update-index to
mark them and then later say "git commit" will make a
commit from the state you used update-index on, without
having you list them on the command line. When you do
this, the commit template would list three classes of
files and here are what they mean...
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