Re: [PATCH 0/2] Making "git commit" to mean "git commit -a".

On Thu, 30 Nov 2006, Carl Worth wrote:

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.

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".