Subject: Re: Two crazy proposals for changing git's diff commands

From: Carl Worth <[email-masked]>
Date: Thu, 09 Feb 2006 17:24:18 -0800

On Thu, 09 Feb 2006 16:13:42 -0800, Junio C Hamano wrote:
> > Index-lover:
> >
> > 	update-index
> > 	diff-index
> > 	commit-index
> >
> > Index-ignorer:
> >
> > 	diff-files
> > 	commit-files
> 
> I see where you are coming from and I personally kind of like
> this consistency.

Thanks. I think that means I've described my motivation now. Though I
still have to come up with a valid proposal.

>                   But I am hesitant to declare these two
> workflows as the _only_ ones officially supported by the tool at
> this moment.

I wouldn't want to do that either. Fortunately, I don't think the
above command set would do anything like that. The workflows above
with the silly names are just examples, but the commands would still
be available in general, and I would expect people to mix and match
for whatever fits best.

The more significant aspect of the above grouping is not "what
workflow is supported" but whether the commands operate primarily on
the index or on the files in the working directory. The distinction is
significant to understanding and taking full advantage of git. And
this aspect of git is something that is particularly unique to git
(and hence some source of confusion to newcomers).

Take a look at how the index vs. files distinction currently plays out
with existing commands:

commit:	Acts on index. Can be made to act on files with -a.

diff:	Acts between index and files (which is a sort of special case).
	Can be made to act on files by passing a tree argument.
	Can be made to act on index by passing --cached.

update-index:	Acts on index, (as obviously encoded in the name).

>                                           One of our first goals
> would be to have good set of introductory documentations for
> best current practices -- if the project you work on fits this
> workflow, here is a way to do it.  With that workflow, there is
> this way.

I agree. I think the current 'tutorial introduction to git' does a
good job at demonstrating one work flow. I'm picky though, so the two
changes I'd like to have in it are: 1) No command-line options
necessary (rename "commit -a" somehow). 2) Provide an honest
HEAD->files diff rather than the current "git diff" that just
'accidentally' happens to give the same answer in this case.

For a taking-advantage-of-the-index workflow, I think the 'short git
tutorial' does a poor job, (it makes the index notion just seem
painful and in the way). But Linus' responses to me in the recent
threads have helped me understand it better, so there's material for
an improved tutorial there I think.

> Sorry, I am not convinced about separate command names, but in
> the meantime you could have small wrappers around "git diff":
> "cw-diff-files" and "cw-diff-index" would be one liner each,
> wouldn't they?
> 
> And that is a _good_ thing about git.

Yes, I can do that personally, and I do agree it's a nice benefit of
git. (Though some might see it as a defect if such scripting is
perceived as being necessary before getting comfortable use out of the
tool.)

>               And as I said, I do not think "index-lover" and
> "index-ignorer" distinction above would be the only two valid
> workflows anyway, so I feel partitioning the command set along
> those lines is at least premature if not wrong.

Yeah, that's a false partition. People will certainly use commands
from both sets. I think the index-focused vs. files-focused
orientation I've presented here is more valid partition.

And I think if there were a clean files-focused subset of commands
(that also didn't "deny the index" in any fundamental way), that it
would make a good introduction to git, (it would certainly provide a
closer fit to what many people will conceive of as they come from
other systems).

-Carl