Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras <felipe.contreras@gmail.com>]

On Wed, Nov 18, 2009 at 1:13 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Exactly.  That is where we disagree.  The funny "@stage" does not convey
> the fact that it is affecting how "git diff" operates, like any other
> option like "-R" does in "git diff -R" command line does.  Now the user
> needs to know git commands take -option like other normal tools do, but in
> addition they need to remember that an oddball "diff" subcommand takes
> "@funny" in addition to the usual "-option".

Right now there are 4 modes of operations, the user would need to
remember all of them... instead, the @stage pointer would reduce the
modes to 1, so the user would have to look on the man-page only once,
quickly.

Also, to me it feels more natural to do "git diff b a" rather than
"git diff -R a b", therefore "git diff @stage HEAD" beats "git diff -R
--cached HEAD".

Moreover, I wonder if these modes are really properly implemented. For
example, what's with these funky commands:
git diff HEAD master next <- shouldn't only 2 be allowed?
git diff HEAD..master HEAD..next

Anyway, you are making the assumption that users actually use, and
understand the different modes of operation, but I'm claiming most of
them don't, and one of the reasons could be that they are not
intuitive.

> How would that be an improvement?

It might make people actually start using the stage, which again, it
seems apparent to me they don't. This can be easily interpreted from
reading the git user survey (only 23% of the people use "git add -i /
-p", and 15% "git add -u / -A" often), but if you don't believe so, we
can wait for the next one and ask the question explicitly.

-- 
Felipe Contreras