From: Philip Oakley <philipoakley@iee.org>
Date: Sat, 20 Aug 2016 19:14:25 GMT
Subject: Re: git rm --cached should be git rm --cache or git rm --stage
Message-ID: <91F685E894D94BB89892C695B8C1796E@PhilipOakley>
In-Reply-To: <20160820072214.GB24992@x220-a02>

From: "Zenaan Harkness" <zen@freedbms.net>
>
>  Please CC me :)
>
>
> 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.
>
> Probably also the option name should change.
>
> See here for examples of community self-help compensating for git-rm man
> page's particularly bad wording:
> http://stackoverflow.com/questions/6919121/why-are-there-2-ways-to-unstage-a-file-in-git
>
> I suggest:
> - change "--cached" to "--cache" at the least (allow both)

Such small nuance changes rarely have the effect hoped for when there are 
such gross misunderstandings by the user.

>
> - probably deprecate --cached and add "--stage" to replace it
>
> - perhaps change the wording in the man page above to something similar
>   as on the stackoverflow page above,
>   e.g.:
>   "Removes a file from the index. In the case where the file is already
>   in the repo, git rm --cached will remove the file from the index,
>   leaving it in the working directory and a commit will now remove it
>   from the repo as well. Basically, after the commit, you would have
>   unversioned the file and kept a local copy."

The idea of 'removing from the repo' can have a connotation that it means 
total removal from history(the repository hold the history!), and not just 
future commits.

>
>   or perhaps something like:
>   "does not unstage a file, it actually stages the removal of the
>   file(s) from the repo (assuming it was already committed before) but
>   leaves the file in your working tree (leaving you with an untracked
>   file)"
>

The easiest way is to simply swap around the two sentences so that the 
positive action is listed first - this better matches people's typical 
cognition. Human Error (by Reason)[1] tells us to Never state warnings and 
caveats after the instruction, and preferably be positive.

"--cached:
Working tree files, whether modified or not, will be retained unchanged.
The option will remove paths from the index (only) to unstage them from 
future commits."


>
> The git "stage" is a primary concept, and a primary noun (one reason
> many of us have come to appreciate git), and git's cmd line options and
> help docs ought reflect this.
>
> Thanks,
> Zenaan
> --

Philip
[1] https://www.amazon.com/Human-Error-James-Reason/dp/0521314194