Carl Worth wrote:
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.
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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html