Subject: Re: Command-line interface thoughts

From: Jakub Narebski <[email-masked]>
Date: Fri, 10 Jun 2011 20:35:41 +0200

Dnia piątek 10. czerwca 2011 20:07, Holger Hellmuth napisał:
> On 10.06.2011 18:44, Jakub Narebski wrote:
> > On Thu, 9 Jun 2011, Holger Hellmuth wrote:
> >> 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'.
> >
> > "I want to see if there are any remiaining changes", "I want to see what
> > 'git commit' would bring", "I want to see what 'git commit -a' would bring".
> > Neither of those is about targets for diff.
> 
> Are you proposing a command "git 
> --I-want-to-see-if-there-are-any-remaining-changes" ? ;-). I was looking 
> for short command or parameter names that are easy to remember, not for 
> definitions of the output of cryptic commands.
> 
> But lets see. If I didn't know much git, where would I look for the 
> right command for your three needs? Where would I expect the solution? 
> (note I'm not proposing any of these commands)
> 
> "I want to see if there are any remaining changes"?
> git status
> git status --full
> git status --detailed

"Any differences"?

git diff

"I want to see what I staged"

git diff --staged

Isn't it simpler than "I want to see the changes between what I already
staged, which is put in place called index, but must refer to it by NEXT,
and the changes I didn't staged, in my working area, which I refer to by
WORK... no, it is TREE... oh, wait, it is WTREE" :-)  I am exaggerating
much here, but I think you can see what I want to point out.

> Now I'll add a question I would want to ask:
> "I want to see the changes between what I have in my working tree and 
> what I already added to the index"

That's not a beginner question.

> git diff WTREE INDEX
           ^^^^^^^^^^^ --- reverse to "git diff"

In this direction it is surely suprising... you see, how again and again
having to explicitely state what to compare with which leads to mistakes
such like this one, and the one in few mails earlier.
 
> 
> Btw. even the 'git diff' man page emphasizes that diff is about a 
> comparision between two things. Citation: "Show changes *between* two 
> trees, a tree and the working tree, a tree and the index file,...".
 
That's more about explaining result of command.  Besides manpages are
reference documentation; new users should start with user's manual, or
tutorial (or "Pro Git"), not manpages.
 
> > [...]
> >>> 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.
> >
> > Those "training wheels" are useless for beginner, and might be not very
> > useful to middle expert user either, depending on corner cases.
> 
> "useless for beginner". No reasoning, just a fat road block for my opinion?
> As git expert you are so far removed from any beginner status. Are you 
> sure you still know how a beginner thinks?

Well, that depends by what you mean by beginner.  Beginner to git, but
not beginner to version control knows about "<scm> diff" form to check
for one's changes, for example.

But I don't think that beginner knows that there is such thing like the
index, and know that he/she has to compare the index to the working area.
When he/she starts to use the index, probably he/she isn't a beginner
anymore.

-- 
Jakub Narebski
Poland