From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Mon, 16 Nov 2009 22:52:37 GMT
Subject: Re: [PATCH v2 0/2] user-manual: new "getting started" section
Message-ID: <94a0d4530911161452xe82858el322a1985341bf13c@mail.gmail.com>
In-Reply-To: <20091114060600.6117@nanako3.lavabit.com>

On Fri, Nov 13, 2009 at 11:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote:
> Quoting Michael J Gruber <git@drmicha.warpmail.net>
>> If you care to go back to that discussion you see that there is good
>> reason for having both --cached and --index. They are different. "git
>> help cli" explains this nicely.
>
> The need to support both options in the same command (eg. apply) means
> that anybody who says "I don't like 'index' nor 'cache'; why don't we
> change them all to 'stage'" doesn't understand the issue.
>
> But that doesn't mean "apply --cached" vs "apply --index" is the best
> way to let the users specify which operation is requested. I don't
> think Felipe seriously wants to change them to --gogo vs --dance, but
> if he made a more constructive proposal, instead of making such a
> comment whose intended effect is only to annoy people, we may see
> an improved UI at the end.  Proposing "--index-only" vs "--index-too"
> or even "--stage-only" vs "--stage-too" would have helped him appear
> to be more serious and constructive and I think your expression
> "mismatching participants" was a great way to say this.

Right, your explanation is more clear: the fact that we need both
doesn't mean we cannot use the term "stage". As to "constructive
proposal" I deliberately tried to avoid them in case somebody tried to
disregard it as bike-shedding, and move on. What I'm trying to do is
bring up the issue that the stage is not user friendly.

> There was a similar discussion about "diff --cached". The command
> compares two things and the current syntax relies on counting the
> number of treeish on the command line to specify what these two things
> are, and sometimes people are confused which way the comparison occurs.
>
>  * If you have two treeish, it compares the two treeish. Specifically,
>   it shows the change to make one treeish into the other treeish.
>
>  * If you have one treeish, it compares the treeish with working tree
>   or the index (it shows the change to make the treeish into working
>   tree or the index). You need --cached to choose the "index", and
>   this can safely be aliased to --staged.
>
>  * If you have zero treeish, it compares the index with working tree
>   (it shows the change to make the index into working tree).
>
> But it is also possible to have an alternate syntax to explicitly say
> what you are comparing with what. Perhaps these may make it unnecessary
> to remember which way the comparison occurs:
>
>  git diff --tree-vs-staged HEAD
>        same as "git diff --cached HEAD"
>  git diff --staged-vs-tree HEAD
>        same as "git diff -R --cached HEAD"
>
>  git diff --staged-vs-working
>        same as "git diff"
>  git diff --working-vs-staged
>        same as "git diff -R"
>
>  git diff --tree-vs-working HEAD
>        same as "git diff HEAD"
>  git diff --working-vs-tree HEAD
>        same as "git diff -R HEAD"

I like David Kågedal's suggestion more:
http://kerneltrap.org/mailarchive/git/2008/10/29/3857134

Cheers.

-- 
Felipe Contreras