{"thread":{"id":"43893","subject":"Re: git rm --cached should be git rm --cache or git rm --stage","startedAt":"2016-08-20T08:35:51Z","lastAt":"2016-08-20T23:06:55Z","messageCount":6,"participants":["Zenaan Harkness","Junio C Hamano","Philip Oakley"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"299789","messageId":"20160820072500.GC24992@x220-a02","threadId":"43893","inReplyTo":"20160820072214.GB24992@x220-a02","subject":"Re: git rm --cached should be git rm --cache or git rm --stage","fromName":"Zenaan Harkness","fromEmail":"zen@freedbms.net","sentAt":"2016-08-20T07:25:00Z","receivedAt":"2016-08-20T08:35:51Z","isPatch":false,"sender":{"key":"zen@freedbms.net","avatar":null},"body":"   Please CC me :)\n\n> From man git-rm:\n> \n> --cached\n>   Use this option to unstage and remove paths only from the index.\n>   Working tree files, whether modified or not, will be left alone.\n> \n> \n> This wording is unclear and dangerous, and ought be cleaned up somehow.\n> \n> Probably also the option name should change.\n> \n> See here for examples of community self-help compensating for git-rm man\n> page's particularly bad wording:\n> http://stackoverflow.com/questions/6919121/why-are-there-2-ways-to-unstage-a-file-in-git\n\n\nAlso, perhaps a git porcelain command \"git unstage\" to unstage staged\nchanges.  Something small like this might make a huge difference for git\nnewbies.\n"},{"id":"299790","messageId":"20160820072214.GB24992@x220-a02","threadId":"43893","inReplyTo":null,"subject":"git rm --cached should be git rm --cache or git rm --stage","fromName":"Zenaan Harkness","fromEmail":"zen@freedbms.net","sentAt":"2016-08-20T07:22:14Z","receivedAt":"2016-08-20T08:55:19Z","isPatch":false,"sender":{"key":"zen@freedbms.net","avatar":null},"body":"\n  Please CC me :)\n\n\nFrom man git-rm:\n\n--cached\n  Use this option to unstage and remove paths only from the index.\n  Working tree files, whether modified or not, will be left alone.\n\n\nThis wording is unclear and dangerous, and ought be cleaned up somehow.\n\nProbably also the option name should change.\n\nSee here for examples of community self-help compensating for git-rm man\npage's particularly bad wording:\nhttp://stackoverflow.com/questions/6919121/why-are-there-2-ways-to-unstage-a-file-in-git\n\nI suggest:\n - change \"--cached\" to \"--cache\" at the least (allow both)\n\n - probably deprecate --cached and add \"--stage\" to replace it\n\n - perhaps change the wording in the man page above to something similar\n   as on the stackoverflow page above,\n   e.g.:\n   \"Removes a file from the index. In the case where the file is already\n   in the repo, git rm --cached will remove the file from the index,\n   leaving it in the working directory and a commit will now remove it\n   from the repo as well. Basically, after the commit, you would have\n   unversioned the file and kept a local copy.\"\n\n   or perhaps something like:\n   \"does not unstage a file, it actually stages the removal of the\n   file(s) from the repo (assuming it was already committed before) but\n   leaves the file in your working tree (leaving you with an untracked\n   file)\"\n\n\nThe git \"stage\" is a primary concept, and a primary noun (one reason\nmany of us have come to appreciate git), and git's cmd line options and\nhelp docs ought reflect this.\n\nThanks,\nZenaan\n"},{"id":"299792","messageId":"xmqq37lzz5yv.fsf@gitster.mtv.corp.google.com","threadId":"43893","inReplyTo":"20160820072214.GB24992@x220-a02","subject":"Re: git rm --cached should be git rm --cache or git rm --stage","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-20T17:48:56Z","receivedAt":"2016-08-20T17:49:08Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Zenaan Harkness <zen@freedbms.net> writes:\n\n> From man git-rm:\n>\n> --cached\n>   Use this option to unstage and remove paths only from the index.\n>   Working tree files, whether modified or not, will be left alone.\n>\n> This wording is unclear and dangerous, and ought be cleaned up somehow.\n\nI think \"unstage and\" can be removed to make it more clear [*1*],\nbut otherwise I do not see much wrong with the description to make\nit dangerous.\n\nCan you elaborate?  Which part of the description is unclear?\n\n\"git help cli\" gives a brief description as to why it should be\ncalled \"--cached\".\n\n\n[Footnote]\n\n*1* The reason why \"unstage\" makes it ambiguous is because people\ntend to use the word \"stage\" loosely.  Even though Git keeps track\nof the entire state of a file, it is easy to confuse oneself to\nmistakenly think that \"git add\" a modified file as \"staging the\ndifference between the last committed state and the contents being\nadded\", and from that mistaken world view, you would imagine\n\"unstage\" may bring the last committed state back in the index,\nwhich is not what \"git rm --cached\" does (it does \"remove\" the path\nfrom the index).\n"},{"id":"299798","messageId":"91F685E894D94BB89892C695B8C1796E@PhilipOakley","threadId":"43893","inReplyTo":"20160820072214.GB24992@x220-a02","subject":"Re: git rm --cached should be git rm --cache or git rm --stage","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-20T19:14:25Z","receivedAt":"2016-08-20T19:14:33Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Zenaan Harkness\" <zen@freedbms.net>\n>\n>  Please CC me :)\n>\n>\n> From man git-rm:\n>\n> --cached\n>  Use this option to unstage and remove paths only from the index.\n>  Working tree files, whether modified or not, will be left alone.\n>\n>\n> This wording is unclear and dangerous, and ought be cleaned up somehow.\n>\n> Probably also the option name should change.\n>\n> See here for examples of community self-help compensating for git-rm man\n> page's particularly bad wording:\n> http://stackoverflow.com/questions/6919121/why-are-there-2-ways-to-unstage-a-file-in-git\n>\n> I suggest:\n> - change \"--cached\" to \"--cache\" at the least (allow both)\n\nSuch small nuance changes rarely have the effect hoped for when there are \nsuch gross misunderstandings by the user.\n\n>\n> - probably deprecate --cached and add \"--stage\" to replace it\n>\n> - perhaps change the wording in the man page above to something similar\n>   as on the stackoverflow page above,\n>   e.g.:\n>   \"Removes a file from the index. In the case where the file is already\n>   in the repo, git rm --cached will remove the file from the index,\n>   leaving it in the working directory and a commit will now remove it\n>   from the repo as well. Basically, after the commit, you would have\n>   unversioned the file and kept a local copy.\"\n\nThe idea of 'removing from the repo' can have a connotation that it means \ntotal removal from history(the repository hold the history!), and not just \nfuture commits.\n\n>\n>   or perhaps something like:\n>   \"does not unstage a file, it actually stages the removal of the\n>   file(s) from the repo (assuming it was already committed before) but\n>   leaves the file in your working tree (leaving you with an untracked\n>   file)\"\n>\n\nThe easiest way is to simply swap around the two sentences so that the \npositive action is listed first - this better matches people's typical \ncognition. Human Error (by Reason)[1] tells us to Never state warnings and \ncaveats after the instruction, and preferably be positive.\n\n\"--cached:\nWorking tree files, whether modified or not, will be retained unchanged.\nThe option will remove paths from the index (only) to unstage them from \nfuture commits.\"\n\n\n>\n> The git \"stage\" is a primary concept, and a primary noun (one reason\n> many of us have come to appreciate git), and git's cmd line options and\n> help docs ought reflect this.\n>\n> Thanks,\n> Zenaan\n> --\n\nPhilip\n[1] https://www.amazon.com/Human-Error-James-Reason/dp/0521314194 \n\n"},{"id":"299803","messageId":"20160820222519.GC5044@x220-a02","threadId":"43893","inReplyTo":"91F685E894D94BB89892C695B8C1796E@PhilipOakley","subject":"Re: git rm --cached should be git rm --cache or git rm --stage","fromName":"Zenaan Harkness","fromEmail":"zen@freedbms.net","sentAt":"2016-08-20T22:25:19Z","receivedAt":"2016-08-20T22:27:23Z","isPatch":false,"sender":{"key":"zen@freedbms.net","avatar":null},"body":"On Sat, Aug 20, 2016 at 08:14:25PM +0100, Philip Oakley wrote:\n> From: \"Zenaan Harkness\" <zen@freedbms.net>\n> >\n> > Please CC me :)\n\n> >  or perhaps something like:\n> >  \"does not unstage a file, it actually stages the removal of the\n> >  file(s) from the repo (assuming it was already committed before) but\n> >  leaves the file in your working tree (leaving you with an untracked\n> >  file)\"\n> >\n> \n> The easiest way is to simply swap around the two sentences so that the\n> positive action is listed first - this better matches people's typical\n> cognition. Human Error (by Reason)[1] tells us to Never state warnings and\n> caveats after the instruction, and preferably be positive.\n> \n> \"--cached:\n> Working tree files, whether modified or not, will be retained unchanged.\n> The option will remove paths from the index (only) to unstage them from\n> future commits.\"\n\nThat's much better. +1. Thanks.\n\n\n> >\n> >The git \"stage\" is a primary concept, and a primary noun (one reason\n> >many of us have come to appreciate git), and git's cmd line options and\n> >help docs ought reflect this.\n> >\n> >Thanks,\n> >Zenaan\n> >--\n> \n> Philip\n> [1] https://www.amazon.com/Human-Error-James-Reason/dp/0521314194\n"},{"id":"299805","messageId":"48C4D1F0A72F4C559FCBC5AF70EB494F@PhilipOakley","threadId":"43893","inReplyTo":"20160820222519.GC5044@x220-a02","subject":"Re: git rm --cached should be git rm --cache or git rm --stage","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-20T23:06:48Z","receivedAt":"2016-08-20T23:06:55Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Zenaan Harkness\" <zen@freedbms.net>\n> On Sat, Aug 20, 2016 at 08:14:25PM +0100, Philip Oakley wrote:\n>> From: \"Zenaan Harkness\" <zen@freedbms.net>\n>> >\n>> > Please CC me :)\n>\n>> >  or perhaps something like:\n>> >  \"does not unstage a file, it actually stages the removal of the\n>> >  file(s) from the repo (assuming it was already committed before) but\n>> >  leaves the file in your working tree (leaving you with an untracked\n>> >  file)\"\n>> >\n>>\n>> The easiest way is to simply swap around the two sentences so that the\n>> positive action is listed first - this better matches people's typical\n>> cognition. Human Error (by Reason)[1] tells us to Never state warnings \n>> and\n>> caveats after the instruction, and preferably be positive.\n>>\n>> \"--cached:\n>> Working tree files, whether modified or not, will be retained unchanged.\n>> The option will remove paths from the index (only) to unstage them from\n>> future commits.\"\n>\n> That's much better. +1. Thanks.\n>\n\nOne better maybe to add (at the end): \"The paths become untracked.\"\n\nThat way we hit all the key codewords that the user may recognise, or need \nto see, to understand.\n\nSubmittimg a patch is faily easy, especially if you have git send-email set \nup.\n\"patches to git@vger.kernel.org (read Documentation/SubmittingPatches for \ninstructions on patch submission).\" (from the README.md)\n\nhttps://github.com/git/git/blob/master/Documentation/SubmittingPatches\n\n\n>\n>> >\n>> >The git \"stage\" is a primary concept, and a primary noun (one reason\n>> >many of us have come to appreciate git), and git's cmd line options and\n>> >help docs ought reflect this.\n>> >\n>> >Thanks,\n>> >Zenaan\n>> >--\n>>\n>> Philip\n>> [1] https://www.amazon.com/Human-Error-James-Reason/dp/0521314194\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at  http://vger.kernel.org/majordomo-info.html\n> \n\n"}]}