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

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

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