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)
- 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."
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 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
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
Also, perhaps a git porcelain command "git unstage" to unstage staged
changes. Something small like this might make a huge difference for git
newbies.
From: "Zenaan Harkness" <redacted>
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
On Sat, Aug 20, 2016 at 08:14:25PM +0100, Philip Oakley wrote:
From: "Zenaan Harkness" <redacted>
quoted
Please CC me :)
quoted
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."
That's much better. +1. Thanks.
quoted
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
From: "Zenaan Harkness" <redacted>
On Sat, Aug 20, 2016 at 08:14:25PM +0100, Philip Oakley wrote:
quoted
From: "Zenaan Harkness" <redacted>
quoted
Please CC me :)
quoted
quoted
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."
That's much better. +1. Thanks.
One better maybe to add (at the end): "The paths become untracked."
That way we hit all the key codewords that the user may recognise, or need
to see, to understand.
Submittimg a patch is faily easy, especially if you have git send-email set
up.
"patches to git@vger.kernel.org (read Documentation/SubmittingPatches for
instructions on patch submission)." (from the README.md)
https://github.com/git/git/blob/master/Documentation/SubmittingPatches
quoted
quoted
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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html