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

[Carl Worth <cworth@cworth.org>]

[-- Attachment #1: Type: text/plain, Size: 4791 bytes --]

On Thu, 30 Nov 2006 09:13:52 -0800 (PST), Linus Torvalds wrote:
> On Thu, 30 Nov 2006, Theodore Tso wrote:
> >
> > But then why is the default for "git commit" to commit the index, if
> > the index is almost == HEAD?  And why is git-update-index given such
> > prominence in the documentation?
>
> The default is: commit everything that you ask for to be committed.
...
> It has NOTHING to do with the index per se.

OK. I'll try to not mention the "index" any more in any postings
here.

And can we agree that any time git spits out a message directing the
user to use update-index that that's a (minor) user-interface wart?

> 	"git commit" with no parameters simply DOES NOT DO ANYTHING YOU
> 	HAVEN'T ALREADY ASKED YOU TO DO.

I think the response that would come from the people that are confused
is:

	"But I told git I wanted to track this file when I said 'git
	add' long ago. Why is it making me tell it again."

As you mentioned, all systems have _some_ mechanism for keeping track
of the files to be committed, (and git's is only unique in having a
name and providing more functionality for direct manipulation and lots
of extra information in the case of a merge conflict).

But I think most every system out there _except_ git default to a
state of committing every file it "knows" about as it exists in the
working tree, and then allowing the user to restrict that behavior to
some subset of the files.

Git allows the same subsetting, and has behavior that is very similar
to these other systems when the user provides a list of files.

Git also provides a unique mode in that users can "stage" file state
to be committed later in spite of subsequent different changes being
made to the same files in the working tree that won't be
committed. Some git users love this functionality. But mentioning it
to new users does scare them off to some extent, ("Why would I _want_
to do that?", "What if that happens accidentally?").

And I think one thing that happens is that the current defaults
naturally lead users to hear about this "scary" functionality, even if
the presenter, (whether a human or printed documentation), isn't
trying to go that direction:

Presenter:	So use "git commit -a" here.

New user:	Why -a?

Presenter:	To tell git that you want to commit all files rather
		than having to list them all on the command line.

New user:	Why not just "git commit" for that then?

Presenter:	Because that's something else.

New user:	What's that?

Presenter: 	It lets you stage things---stuff you think is ready to
		commit, but when you want to delay that commit until
		after making other changes to the files that you don't
		want to commit.

New user:	What? Really? That's bizarre.

Presenter:	It can be useful in some situations. But for now,
		just use "commit -a" and it will do what you want.

And at this point the user either trusts me, accepts it, gives git a
try and falls in love, or the user gives up and uses something else.

I think the above accurately captures the essence of actual
conversations I've had with new new users. And I'd be glad to take
suggestions on how to improve what I say here. But it's that feeling
of "git is bizarre" that I'd like to reduce, and I'd like to improve
the success rate of the conversation, (though I think I've done pretty
well for people that trust me).

And note that the same kind of conversation happens when using git
directly with tutorials and man pages, but without a human
presenter. Only, there the conversation is much worse. First, it's
harder to pull off "just trust me and give it a try" in technical
documentation. Second, the documentation does not do a good job of
letting the user know when they're getting more technical information
than they need.

For example, there's "git status", (used by "git commit"), that
directs the user to "git update-index". Then there's the documentation
of git-commit that says "Updates the index file...and makes a commit
object."

And so far my best response to those problems is to short-cut them by
improving the defaults of git-commit, (the documentation should be
improved too, and I did submit a patch to get "update-index" out of
git-status output for example).

Anyway, I'm repeating myself on some of these details, but only
because some people still haven't seemed to grasp the real, new-user
confusion that arises here.

That's really what I'm trying to reduce with all the talk about
"commit all known files by default".

> 	"git commit" with no parameters simply DOES NOT DO ANYTHING YOU
> 	HAVEN'T ALREADY ASKED YOU TO DO.
>
> Repeat the above sentence again. IT JUST MAKES SENSE.

Yes. And it makes sense for the user to be able to say "unless I tell
you differently, I want to always commit the working-tree state of
<files> with every commit".

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]