Re: git rm --cached should be git rm --cache or git rm --stage

Zenaan Harkness [off-list ref] writes:

From man git-rm:

--cached
  Use this option to unstage and remove paths only from the index.
  Working tree files, whether modified or not, will be left alone.

This wording is unclear and dangerous, and ought be cleaned up somehow.

I think "unstage and" can be removed to make it more clear [*1*],
but otherwise I do not see much wrong with the description to make
it dangerous.

Can you elaborate?  Which part of the description is unclear?

"git help cli" gives a brief description as to why it should be
called "--cached".


[Footnote]

*1* The reason why "unstage" makes it ambiguous is because people
tend to use the word "stage" loosely.  Even though Git keeps track
of the entire state of a file, it is easy to confuse oneself to
mistakenly think that "git add" a modified file as "staging the
difference between the last committed state and the contents being
added", and from that mistaken world view, you would imagine
"unstage" may bring the last committed state back in the index,
which is not what "git rm --cached" does (it does "remove" the path
from the index).