Carl Worth wrote:
quoted text
> If the "create file; git add; edit file; git commit" confusion isn't
> blisteringly obvious to the git maintainers then I think I have to
> give up here.
>
> And this isn't just CVS-induced brain damage. It's the user being
> required to mentally juggle 3 states for the file, (the last
> "committed" state, the current "working tree" state, and this
> "something else" state). The sequence above, (which is very natural),
> exposes this "something else" state that to a new user.
>   

Exactly. We had a tutorial for the project I contribute to (admittedly 
the initial users were all used to how CVS worked) and while a number of 
people got the concept of the index and were fairly happy with it, it 
did add to the confusion of the tutorial, so now it doesn't mention the 
index at all.

The tutorial introduced it as a staging area for commits, but the 
trouble is that once you work like this you have to remember that 
"git-diff" won't show you what will be committed, so you have to use 
"git-diff-index" as well. If you get them mixed up then you end up 
committing the wrong thing.

Here's a selected list of the commands introduced in the tutorial, 
without mentioning the index:
git diff
git commit -a
git commit <changed-files>
git reset HEAD^
git cherry-pick

Here would be the same entries, but introducing the index too:
git-update-index
git diff
git diff-index
git commit
git commit -a
git commit <changed-files>
git reset HEAD^
git reset --soft HEAD^
git cherry-pick
git cherry-pick -n

The tutorial then goes from having ~12 common commands to learn up to ~17.

quoted text
> If we imagine a new user as coming, not from cvs, but coming from
> no revision control system, then it's less confusing to add one single
> new state, (the "last committed" state), in addition to the "working
> tree" state the user is familiar with.
>
> Forcing the user to learn two instead of one is just plain harder,
> (which is completely separate from git _allowing_ this extra state
> once you learn it).

Having the index exposed for even simple operations means that the user 
has to initially learn three states instead of two. The worst thing 
about the index is that it is a limbo state. The committed content is in 
the history and can be viewed by gitk (and other tools that the user 
will be introduced to later) and the working tree is exactly what the 
user sees in their editor. Having a hidden state isn't very good from an 
HCI point of view.

Once you understand the concept of the index, it is very useful. 
However, new users should be shielded from it if at all possible.

I'm not advocating making "git-commit" equal to "git-commit -a" as I've 
been frustrated by command's semantics changing in git before. I can 
understand long-time git users would automatically try to use 
"git-commit" to just commit their index and get annoyed if it did 
something unexpected. Therefore, I would advocate there being no default 
behaviour for "git-commit" except for displaying a help message, and 
making previous "git-commit" users now use "git-commit -i".

-- 
Rob Shearman

-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html