Re: Command-line interface thoughts

From: Jakub Narebski <jnareb@gmail.com>
Date: Jun 8, 2011, 18:56 UTC
Message-ID: <201106082056.38774.jnareb@gmail.com>
In-Reply-To: <4DEF7378.20307@ira.uka.de>

On Wed, 8 Jun 2011, Holger Hellmuth wrote:

> On 07.06.2011 22:33, Jakub Narebski wrote:

Show 10 quoted lines

> > To reiterate; perhaps it is not stated clearly in documentation:
> >
> > 1. "git diff" is about examining _your_ changes.  This short form is the
> >     same in every SCM.
> 
> you are right, more explicit mention in the docs would help about this.
> 
> But other SCMs don't have the additional target 'index'. Much easier to 
> reason there. Also, wouldn't Joe User then conclude that 'git diff' must 
> be comparing working area against HEAD ?

Well, actually it should be that "git diff" is about examining _your_ *remaining* changes.

If Joe User doesn't use index, then "git diff" and "git diff HEAD" shows
the same contents (modulo "git add" / "git add -N" trouble).  So Joe
doesn't need to worry if it is worktree versus index, or versus HEAD;
it is enought to know when it is used.

Show 9 quoted lines

> >     Because of explicit index (cache, staging area) one needs to know if
> >     it is working area against index, or working area against HEAD.
> >     Thinking about merge conflict case helps to remember; in such case
> >     you want your changes against partially resolved merge.
> 
> This is far from a straightforward reasoning that would pop up in 
> anyones mind. In truth, I can't follow that reasoning even now. In case 
> of a merge conflict the working area doesn't concern me at all, I would 
> want a diff between 'ours' and 'theirs'.

What you want is irrelevant ;-) Because in the case of merge conflict entries in index is populated automatically, *your* changes are changes agains index. So there.

And what "git diff" would show in that case is --cc diff of file with merge markers against stages '1' and '2' in index, which is quite useful. Which is 3-way diff between 'ours' and 'theirs'.

Nb. I don't know how to get _remaining_ diff between 'ours' and 'theirs', but the NEXT proposal doesn't address it either...

Show 5 quoted lines

> 
> Since perl has been brought up as example of this DWIM philosophy: In 
> perl commands have their defaults, but you always can specify exactly 
> what you want if you are not sure or want to make it explicit. You can 
> use 'chomp' or you can use 'chomp $_'.

By TIMTOWTDI I rather meant here that you can write

  if (...) {
     ...
  }

or

  ... if (...);

or

  ... or ...;

I wasn't saying anything about DWIM-mery, just TIMTOWTDI and context...

> But I can't make it explicit which two targets I want to compare with
> 'git diff'.

For me it looks XY problem; instead of wanting to compare two explicit
targets, you should specify what you want to see ;-).

> >     Also advanced users can use index to hide fully cooked changes from
> >     having to browse during review.

What is where "remaining" in 'examining your remaining changes' come from. Advanced users can "git add <file>" (or "git add -p" even) when some change is fully cooked and ready to be included, to reduce size of diff when reviewing remaining changes.

Show 15 quoted lines

> >     Novice users which do not use index (and use "git commit -a") would
> >     never notice the difference, if not for the complication of newly
> >     added files: in other SCM you would see on "<scm>  diff" creation
> >     diff (well, there is "git add -N").  Same with removal if one uses
> >     "git rm" and not simply "rm".
> 
> > 2. "git diff --cached" is about cached (staged) changes, therefore
> >     it is index against HEAD.
> 
> We use three words to talk about the index: cache, stage, index. So 
> apart from having an additional target for diff that target also is 
> diffused by three words. Sure, index is the real designation and cached 
> and staged are used as verbs, but that is just one more confusing bit. 
> Also 'cache' in computer science is a transparent buffer to access data 
> faster (wikipedia definition). Not what I would think of the index.

At the very beginning it was named 'dircache'... ;-)))

There was an attempt to introduce 'to stage', 'staged contents' and 'staging area', and you can use "git diff --staged" instead... but support might be incomplete.

The area is called 'the index', but you examine 'cached' contents,
not 'indexed' contents.  One of resons for the index is making git
faster, so it is the cache as well (keeps e.g. cached stats info to
make it possible for git to swiftly find which files changed).

> Probably there are good reasons to not use "git diff --index" and 
> probably they have been discussed a few times, but it doesn't make using 
> diff easier. But that's a side issue.

The issue is with "git apply" and "git stash", where --index means
'use staging area in addition to working directory' and not like
--cached for "git apply" 'use staging area _instead_ of working
directory" (though _instead_ is not very precise here).

Show 5 quoted lines

> If someone sees 'git diff --cached' he might know one target, the index. 
> But how does he get the other? By reasoning that 'git diff' alone is 
> already index against working area? But for that he would have first to 
> conclude that 'git diff' is not working area against HEAD (as it is in 
> other SCMs), see above.

"git diff --cached" / "git diff --staged" is about 'what changes are
in index' (are 'staged'), i.e. what you "git add"-ed / "git stage"-d.
Because changes always go working directory -> staging area -> repository
(commit) it is abvious that those are "staging area -> repository"
changes.

Show 12 quoted lines

> > 3. "git diff<commit>" in general, and "git diff HEAD" in particular,
> >     is about your changes (worktree), compared to given commit.
> >
> > At in no place I _have_ to explain what is compared with what to explain
> > when and what for to use "git diff", "git diff --cached" and "git diff
> > HEAD".
> 
> I'm sure every part of the user interface of gimp can be rationalized in 
> the same way by someone deeply involved in the concepts and the 
> structure of gimp, but still it is perceived as difficult by nearly 
> everyone else. You look at it from inside and it looks logical. Others 
> just don't have all the pieces to make that reasoning really work.

What I wanted to say here that instead of teaching / trying to teach new people something like the following:

  There is working area, index and current commit (HEAD).  To compare
  workdir with index use this, to compare index with HEAD use that, to
  compare workdir with HEAD use this one.

we better do explaining higher level concepts

  To examine your remaining changes, i.e. what you can "git stage",
  use "git diff".  To examine staged changes, i.e. what you 
  "git stage"-d, use "git diff --staged"; that is what "git commit"
  will create.  To compare working version with given older version,
  use "git diff <revision>", in particular to compare with last version
  use "git diff HEAD"; that is what "git commit --all" would create.

The "git diff NEXT WTREE" looks like training wheels to me. And like training wheels they could become obstacles and not help to learning git. Neverthemind they can snag on sharp corners^W corner-cases. ;-)))

-- 
Jakub Narebski
Poland