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

From: Philip Oakley <philipoakley@iee.org>
Date: Aug 20, 2016, 19:14 UTC
Message-ID: <91F685E894D94BB89892C695B8C1796E@PhilipOakley>
In-Reply-To: <20160820072214.GB24992@x220-a02>

From: "Zenaan Harkness" <zen@freedbms.net>

Show 21 quoted lines

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

Show 11 quoted lines

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

Show 7 quoted lines

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

Show 8 quoted lines

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