On 08.06.2011 20:56, Jakub Narebski wrote:
[...]
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 ;-)
No, because you used my wants in your reasoning above. Makes them highly
relevant ;-)
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'.
Ah okay. This detail about the merge process never really registered
with me. Which shows that your logic deduction what 'git diff' does is
often not possible for the casual user
[...]
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 ;-).
Then don't call the command 'diff' (... I proclaim in the knowledge that
that isn't possible). 'diff' is the short form of 'difference' which
means literally a comparison between *two* things. If someone wants to
see something he would pick the words 'show' or 'list'. So user
expectation is different from what you want diff to be.
Also there are no good words for what someone wants to see in this case.
At least I would assume the git project would have found them if they
existed. '--cached' is definitely not one of them. But we have fitting
and widely known names for the targets, i.e 'working tree', 'index' and
'head'.
[...]
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.
If they know working area, index and head, you don't have to tell them
three times how to compare this with that, they just have to know they
can compare any which way they want. In fact, the situation *now* is
exactly what you describe, you have to tell everyone for any of the 3
combinations the command to use because it is not obvious.
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.
Do you realize that you are just enumerating all the possible
combinations again, exactly what you wanted to avoid? Ok, unfair
argument, you want to just make it clear how to remember the commands.
But if I already need 3 emails from you to see the concept behind these
commands (and lets assume my slow-wittedness is par for the course) many
others will probably have the same problems. It may be a nice concept,
but the relation to the user interface is only detectable by close
examination.
Teaching concepts is good. But if git is only usable after having
learned all those concepts, the entry barrier is much too big. With
commands like 'git put' and an improved diff people can use git first,
then learn the concepts while using git. Which is what most people have
to do anyway if they encounter git at the work place for example.
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. ;-)))
If your goal is that anyone who uses git is a git expert, they may be a
hindrance (as are all the porcelain commands really). If you also want
to make git friendly to people who will never get past intermediate or
beginner stage or will only use a small part of git or use git seldomly,
training wheels are good.
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