Subject: Two ideas for improving git's user interface

From: Carl Worth <[email-masked]>
Date: Wed, 01 Feb 2006 15:33:44 -0800

On Wed, 1 Feb 2006 14:35:33 -0800 (PST), Linus Torvalds wrote:
>
> Agreed. However, I think that one is pretty easy to explain, and 
> conceptually it's not a problem to just tell people to use the "-a" flag 
> if they want to get CVS/SVN semantics.

"Just use -a" is tempting, but I don't think it's a satisfying stance
to take.

Consider the following operations:

	echo "original" > A; git add A; echo "modified" > A;
	git commit -a -m "add A";

	echo "original" > B; git add B; echo "modified" > B;
	git commit -m "add B" B;

	echo "original" > C; git add C; echo "modified" > C;
	git commit -m "add C";

After which we can see:

	$ git diff
	diff --git a/C b/C
	index 4b48dee..2e09960 100644
	--- a/C
	+++ b/C
	@@ -1 +1 @@
	-original
	+modified

To explain this, "just use -a" isn't enough, it would have to be
something like, "always use -a or else 'git commit' just won't work
and you can end up committing stale garbage". And perhaps "unless you
also add the filename to the commit line, then it will start working
again."

There's explanation for the above behavior requires a rather careful
description of the index, the operations, the flags, and some rather
subtle interactions between them.

I don't even think "embrace the index" is enough to make the above
behavior obvious---the variations in the above behavior are a bit too
subtle. 

But I don't think git is doomed to be hard to learn or that its
behavior needs to be hard to predict. I think this should be fairly
easy to fix.

Here's a fundamental question I have, (and thanks to Keith Packard for
helping me to phrase it):

	Is it ever useful (reasonable, desirable) to commit file
	contents that differ from the contents of the working
	directory?

I don't think it is, (but please let me know if I've missed some
useful case).

Idea #1 (prevent the index from being used to commit stale data)
-------
If this isn't useful, then I think git would do well to make it
harder/impossible to perform this operation. For example, the index
could have a new notion of "use working directory contents" for a
given file in addition to the current "use this blob". This would
allow a user to use the index to stage subsequent file
additions/modifications for commit without introducing the various
opportunities for confusing commits of stale data.

I would think this would then naturally resolve the confusion around
the various diff operations, (diff-index, diff-index --cached, and
diff-files).

Idea #2 (make it easy to preview diffs of what will be committed)
-------
Independent of the above, I'd like to propose another change to help
prevent confusion and to help users learn git. There should be an
obvious "diff" operation that presents exactly the result of what any
"commit" operation will perform.

I assume that there currently exist appropriate diff operations for
any commit, but the correspondence certainly isn't obvious. For
example, the simplest of commit commands:

	git commit

seems to correspond to a rather complex diff command (which I may not
have completely correct yet---and if not, that would just demonstrate
the point even more):

	git diff-index -p --cached HEAD

What I would love to have is the ability to pass the same arguments to
git diff to get a preview of what any get commit would do. For
example, something like:

	git diff		# would be a preview of:
	git commit

	git diff -a		# would be a preview of:
	git commit -a

	git diff fileA fileB	# would be a preview of:
	git commit fileA fileB

etc.

Again, thanks for your consideration to these thoughts from woefully
clueless and inexperienced user.

-Carl