On 07.06.2011 22:33, Jakub Narebski wrote:
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 ?
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'
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 $_'. But I can't make it explicit
which two targets I want to compare with 'git diff'.
Also advanced users can use index to hide fully cooked changes from
having to browse during review.
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.
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.
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.
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.
Holger.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html