Re: Command-line interface thoughts

[Jakub Narebski <jnareb@gmail.com>]

On Tue, 7 June 2011, Jonathan Nieder wrote:
> Holger Hellmuth wrote:
> 
> > If someone finds the three-way diff completely mystifiying, how do
> > you expect him to resolve a merge conflict at all? Or recognize that
> > there is one? Or find the command to use after editing out the
> > conflict markers?
> >
> > A novice user will have no real mental model anyway.
> 
> Yes, I think you're getting closer to the point I was trying to make.
> A novice will have a naive mental model, and a good user interface
> needs to be close to it but not too close.  Close because the UI must
> be intuitive on its own.  Not too close because a good UI will help in
> leading such a person to productive ways of thinking and working, by
> making common tasks convenient.
> 
> So much for generalities.

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.

   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.

   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.

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".

-- 
Jakub Narebski
Poland