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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Nov 18, 2009, 00:05 UTC
Message-ID: <94a0d4530911171605y3d366786jbc977a2e583bb57f@mail.gmail.com>
In-Reply-To: <7vzl6kd9t3.fsf@alter.siamese.dyndns.org>

On Wed, Nov 18, 2009 at 1:13 AM, Junio C Hamano <gitster@pobox.com> wrote:

Show 6 quoted lines

> 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