On Thu, 30 Nov 2006, Carl Worth wrote: > > What I'm trying to say is that the _defaults_ are not well geared > toward helping new users do what they want to with git. I really think we're better off just telling people how things work (with practical examples, and _not_ by trying to explain things at too high a conceptual level). I don't think people generally are all that stupid, and I think it's actually counter-productive to try to basically lie about how things work. It will just make it harder for people later. > One thing you never really answered was my conversation with a new > user that left the user with the impression of "git is bizarre". How > can I fix that conversation? I really _think_ that a lot of that is in the documentation being overly technically oriented and talking often about the technical side of how things work in the index, rather than the purely user side of what that _results_ in. I really believe that people can understand the concept of "git add" squirrelling away the whole state of the file at add-time, and suddenly it's not all that complicated. Also, it's not even something that people really need to worry about, and I think we should make that more clear. In other words, the documentation could _literally_ give the example of git add file.c .. change file.c .. git commit git diff file.c and talk about this issue up-front, but then just say outright to people that "if you don't want to know about these details, you can always just use 'git commit -a', and you'll never really even notice". There really isn't all that much to "hide". I think we've sometimes done a horrible job on _presentation_, but I also think that it's better to give examples of thigns like this, and then tell people not to worry, because they'll never need to care unless they actually start doing something fancy. So all your examples of "badness" aren't really all that bad. Newbies should be told: - use "git commit -a" normally (with pointers on fancier usage) - and yes, we obviously should change the message to say "git commit -a" instead of "git update-index" - do NOT use the "-m" flag, and look at what git tells you in the commit message! This is actually important, because even for non-newbie users, the git commit message for a conflicting merge contains useful information, and people should read it. It lists the conflicting filenames for a reason, namely so that you can talk about what the conflicts in question _were_. [ Btw, I can't stress that last point enough. Using the "-m" flag should really really REALLY be discouraged. It is almost always a horrible mistake, not just because it means that you miss what git will tell you about which files are getting checked in, but because it invariably leads to bad single-line commit messages. In my personal opinion, the "-m" flag is really only good for scripts and sending example git sequences to each other, ie it's there for automated "do this" kind of scripting, and using it for real work should be a castration offence, so that you don't perpetuate your genes. (I've seen _way_ too many projects where there's a lot of "update version" one-liner commit messages. Damn, I can understand that in CVS, where the logs are useless _anyway_, but in git it shouldn't be allowed!). ] Ok, with that rant out of the way, my _point_ is that we're actually much better off educating users about _why_ git is different, than trying to lie to them and say "it's just like CVS by default, but when you're a real man, we'll show you how you can rock your world". Linus - 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