On Thu, 30 Nov 2006, Carl Worth wrote:
quoted text
> 
> 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.

quoted text
> 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@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html