Re: [PATCH] cmd_reset: don't trash uncommitted changes unless told to

[Junio C Hamano <gitster@pobox.com>]

しらいしななこ <nanako3@lavabit.com> writes:

> Quoting myself:
>
>>>> Don't you also want to talk about distinction between --cached and
>>>> --index that new people are often confused about?  These options are
>>>> defined consistently across commands but people who do not know it bring
>>>> up discussions to rename --cached to some commands to --index to make it
>>>> inconsistent and waste your time every once in a while.
>...
> Junio, I haven't heard back from you yet and I take it you mean you are not interested in a vague suggestion but in a concrete patch, so here it is.

Well, I pretended that I did not notice the original question because I
wanted to avoid addressing this issue ;-<.

While I think --index/--cached are not particularly good pair of words, as
one of the old article you pointed at in your documentation update states,
to describe the distinction, the commands do use them consistently to
differentiate what are operands to them clearly and consistently.  In that
sense, your documentation update would probably be a good idea.  At least
it makes it easier for new people to learn it just once, and once you know
the distinction and remember which is which, you can reuse the knowledge
to all the commands.


Even though I myself freely admit that these are not particularly a good
pair of words, it is not realistic to expect --index and --cached to ever
be deprecated.  But every time this comes up on the list, people end up
wasting time trying to repaint this old bikeshed.  That is the primary
reason I did not want to talk about it.  It still is possible to introduce
a pair of synonyms that new people might find more descriptive, perhaps:

	--index-only = --cached
        --index-also = --index

but I personally do not think it would add much value to the system..

> +NOTES ON FREQUENTLY CONFUSED OPTIONS
> +------------------------------------

Hmmm.  Is this in anticipation for more "confusing" options described in
this section?

> +Many commands that can work on files in the working tree
> +and/or in the index can take `--cached` and/or `--index`
> +options.  Sometimes people incorrectly think that, because
> +the index was originally called cache, these two are
> +synonyms.  They are _not_ --- these two options mean very

In e-mails we use _underscore_ but I do not think it works in AsciiDoc.
I'll munge this (you have others below) to "*not*".  Also unlike LaTeX,
long dash is two dashes (--), not three (---).