{"thread":{"id":"39654","subject":"[PATCH v2] git-checkout.txt: Document \"git checkout \" better","startedAt":"2015-06-17T07:54:51Z","lastAt":"2015-06-18T07:00:16Z","messageCount":20,"participants":["Torsten Bögershausen","Duy Nguyen","Matthieu Moy","Andres G. Aragoneses","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"263987","messageId":"558127CB.70603@web.de","threadId":"39654","inReplyTo":null,"subject":"[PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2015-06-17T07:54:51Z","receivedAt":"2015-06-17T07:54:51Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"git checkout can be used to reset changes in the working tree.\n\nSigned-off-by: Torsten Bögershausen \n---\nVersion 2: Try to summarize the suggestions from the mailing list\n Documentation/git-checkout.txt | 6 +++++-\n 1 file changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex d263a56..39ad36f 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -3,7 +3,7 @@ git-checkout(1)\n NAME\n ----\n-git-checkout - Checkout a branch or paths to the working tree\n+git-checkout - Switch branches or restore changes\n SYNOPSIS\n --------\n@@ -89,6 +89,10 @@ Omitting detaches HEAD at the tip of the current branch.\n \t(i.e. commit, tag or tree) to update the index for the given\n \tpaths before updating the working tree.\n +\n+'git checkout' with or `--patch` is used to restore modified or\n+deleted paths to their original contents from the index or replace paths\n+with the contents from a named (most often a commit-ish).\n++\n The index may contain unmerged entries because of a previous failed merge.\n By default, if you try to check out such an entry from the index, the\n checkout operation will fail and nothing will be checked out.\n-- \n2.2.0.rc1.790.ge19fcd2\n"},{"id":"263998","messageId":"CACsJy8CuRcV2Rxaz8Ut4ayW-Hyd8Aao5W4JMc20jcfggOG3d4g@mail.gmail.com","threadId":"39654","inReplyTo":"558127CB.70603@web.de","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2015-06-17T09:58:27Z","receivedAt":"2015-06-17T09:58:27Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Wed, Jun 17, 2015 at 2:54 PM, Torsten Bögershausen wrote:\n> -git-checkout - Checkout a branch or paths to the working tree\n> +git-checkout - Switch branches or restore changes\n\nI didn't follow closely the previous discussion. Forgive me if this is\nalready discussed, but I would keep the \"in the working tree\".\n\"Restore changes\" alone seems vague.\n-- \nDuy\n"},{"id":"264003","messageId":"vpq8ubiwqo9.fsf@anie.imag.fr","threadId":"39654","inReplyTo":"CACsJy8CuRcV2Rxaz8Ut4ayW-Hyd8Aao5W4JMc20jcfggOG3d4g@mail.gmail.com","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-06-17T10:54:46Z","receivedAt":"2015-06-17T10:54:46Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Duy Nguyen writes:\n\n> On Wed, Jun 17, 2015 at 2:54 PM, Torsten Bögershausen wrote:\n>> -git-checkout - Checkout a branch or paths to the working tree\n>> +git-checkout - Switch branches or restore changes\n>\n> I didn't follow closely the previous discussion.\n\n(Neither did I)\n\n> Forgive me if this is already discussed, but I would keep the \"in the\n> working tree\". \"Restore changes\" alone seems vague.\n\n\"Restore previous version\" would be better than \"Restore changes\" to me.\n\n\"changes\" sounds like \"the diff between a commit and its parent\", so it\nmakes sense to \"revert a change\" (git revert), but not \"restore a\nchange\".\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"264006","messageId":"mlrmnt$te5$1@ger.gmane.org","threadId":"39654","inReplyTo":"vpq8ubiwqo9.fsf@anie.imag.fr","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Andres G. Aragoneses","fromEmail":"knocte@gmail.com","sentAt":"2015-06-17T11:47:09Z","receivedAt":"2015-06-17T11:47:09Z","isPatch":true,"sender":{"key":"knocte@gmail.com","avatar":"https://gravatar.com/avatar/020c5605dcd7456d87a5f29a2af53e7bdf135fe9ccda514b9f34ab3a7e46db27?d=mp&s=160"},"body":"On 17/06/15 12:54, Matthieu Moy wrote:\n> Duy Nguyen writes:\n>\n>> On Wed, Jun 17, 2015 at 2:54 PM, Torsten Bögershausen wrote:\n>>> -git-checkout - Checkout a branch or paths to the working tree\n>>> +git-checkout - Switch branches or restore changes\n>>\n>> I didn't follow closely the previous discussion.\n>\n> (Neither did I)\n>\n>> Forgive me if this is already discussed, but I would keep the \"in the\n>> working tree\". \"Restore changes\" alone seems vague.\n>\n> \"Restore previous version\" would be better than \"Restore changes\" to me.\n\n\"previous version\" sounds ambiguous. How about \"discard local changes\"?\n"},{"id":"264008","messageId":"vpqoaketusa.fsf@anie.imag.fr","threadId":"39654","inReplyTo":"mlrmnt$te5$1@ger.gmane.org","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-06-17T11:54:13Z","receivedAt":"2015-06-17T11:54:13Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"\"Andres G. Aragoneses\" writes:\n\n> On 17/06/15 12:54, Matthieu Moy wrote:\n>> Duy Nguyen writes:\n>>\n>>> On Wed, Jun 17, 2015 at 2:54 PM, Torsten Bögershausen wrote:\n>>>> -git-checkout - Checkout a branch or paths to the working tree\n>>>> +git-checkout - Switch branches or restore changes\n>>>\n>>> I didn't follow closely the previous discussion.\n>>\n>> (Neither did I)\n>>\n>>> Forgive me if this is already discussed, but I would keep the \"in the\n>>> working tree\". \"Restore changes\" alone seems vague.\n>>\n>> \"Restore previous version\" would be better than \"Restore changes\" to me.\n>\n> \"previous version\" sounds ambiguous.\n\nYes, but \"git checkout\" can do many things. It can restore an old\ncommited state, restore from the index, ... so we need to either be\nvague, or use a long enumeration.\n\n> How about \"discard local changes\"?\n\nTo me this describes \"git checkout HEAD\", but neither \"git checkout --\nfile\" nor \"git checkout HEAD^^^\".\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"264009","messageId":"mlrn9r$9ho$1@ger.gmane.org","threadId":"39654","inReplyTo":"vpqoaketusa.fsf@anie.imag.fr","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Andres G. Aragoneses","fromEmail":"knocte@gmail.com","sentAt":"2015-06-17T11:56:43Z","receivedAt":"2015-06-17T11:56:43Z","isPatch":true,"sender":{"key":"knocte@gmail.com","avatar":"https://gravatar.com/avatar/020c5605dcd7456d87a5f29a2af53e7bdf135fe9ccda514b9f34ab3a7e46db27?d=mp&s=160"},"body":"On 17/06/15 13:54, Matthieu Moy wrote:\n> \"Andres G. Aragoneses\" writes:\n>\n>> On 17/06/15 12:54, Matthieu Moy wrote:\n>>> Duy Nguyen writes:\n>>>\n>>>> On Wed, Jun 17, 2015 at 2:54 PM, Torsten Bögershausen wrote:\n>>>>> -git-checkout - Checkout a branch or paths to the working tree\n>>>>> +git-checkout - Switch branches or restore changes\n>>>>\n>>>> I didn't follow closely the previous discussion.\n>>>\n>>> (Neither did I)\n>>>\n>>>> Forgive me if this is already discussed, but I would keep the \"in the\n>>>> working tree\". \"Restore changes\" alone seems vague.\n>>>\n>>> \"Restore previous version\" would be better than \"Restore changes\" to me.\n>>\n>> \"previous version\" sounds ambiguous.\n>\n> Yes, but \"git checkout\" can do many things. It can restore an old\n> commited state, restore from the index, ... so we need to either be\n> vague, or use a long enumeration.\n>\n>> How about \"discard local changes\"?\n>\n> To me this describes \"git checkout HEAD\", but neither \"git checkout --\n> file\" nor \"git checkout HEAD^^^\".\n>\n\nI didn't mean to use just \"discard local changes\". I was proposing that \nas a replacement to the \"restore changes\" substring.\n"},{"id":"264010","messageId":"vpqtwu6sf4r.fsf@anie.imag.fr","threadId":"39654","inReplyTo":"mlrn9r$9ho$1@ger.gmane.org","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-06-17T12:17:40Z","receivedAt":"2015-06-17T12:17:40Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"\"Andres G. Aragoneses\" writes:\n\n> On 17/06/15 13:54, Matthieu Moy wrote:\n>> \"Andres G. Aragoneses\" writes:\n>>\n>>> On 17/06/15 12:54, Matthieu Moy wrote:\n>>>> Duy Nguyen writes:\n>>>>\n>>>>> On Wed, Jun 17, 2015 at 2:54 PM, Torsten Bögershausen wrote:\n>>>>>> -git-checkout - Checkout a branch or paths to the working tree\n>>>>>> +git-checkout - Switch branches or restore changes\n>>>>>\n>>>>> I didn't follow closely the previous discussion.\n>>>>\n>>>> (Neither did I)\n>>>>\n>>>>> Forgive me if this is already discussed, but I would keep the \"in the\n>>>>> working tree\". \"Restore changes\" alone seems vague.\n>>>>\n>>>> \"Restore previous version\" would be better than \"Restore changes\" to me.\n>>>\n>>> \"previous version\" sounds ambiguous.\n>>\n>> Yes, but \"git checkout\" can do many things. It can restore an old\n>> commited state, restore from the index, ... so we need to either be\n>> vague, or use a long enumeration.\n>>\n>>> How about \"discard local changes\"?\n>>\n>> To me this describes \"git checkout HEAD\", but neither \"git checkout --\n>> file\" nor \"git checkout HEAD^^^\".\n>\n> I didn't mean to use just \"discard local changes\". I was proposing\n> that as a replacement to the \"restore changes\" substring.\n\nYes, but \"Switch branchs or discard local changes\" still does not\ndescribe \"git checkout HEAD^^^ -- file.txt\" (restore to an old state,\nbut does not switch branch) or \"git checkout -- file.txt\" (get from the\nindex).\n\nTo me, \"discard local changes\" imply that there will be no uncommited\nchanges on the files implied in the command after the operation.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"264031","messageId":"xmqqoake4akt.fsf@gitster.dls.corp.google.com","threadId":"39654","inReplyTo":"vpqtwu6sf4r.fsf@anie.imag.fr","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-17T15:29:54Z","receivedAt":"2015-06-17T15:29:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> Yes, but \"Switch branchs or discard local changes\" still does not\n> describe \"git checkout HEAD^^^ -- file.txt\" (restore to an old state,\n> but does not switch branch) or \"git checkout -- file.txt\" (get from the\n> index).\n\nYou are right, especially when file.txt does not have any change\nrelative to HEAD, there is no \"discarding\" going on. You are\nactively introducing a change to an unchanged file by checking\ncontents out of a different revision.\n\n> To me, \"discard local changes\" imply that there will be no uncommited\n> changes on the files implied in the command after the operation.\n\nYup.\n"},{"id":"264036","messageId":"55819C5A.40105@web.de","threadId":"39654","inReplyTo":"xmqqoake4akt.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2015-06-17T16:12:10Z","receivedAt":"2015-06-17T16:12:10Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On 2015-06-17 17.29, Junio C Hamano wrote:\n> Matthieu Moy writes:\n> \n>> Yes, but \"Switch branchs or discard local changes\" still does not\n>> describe \"git checkout HEAD^^^ -- file.txt\" (restore to an old state,\n>> but does not switch branch) or \"git checkout -- file.txt\" (get from the\n>> index).\n> \n> You are right, especially when file.txt does not have any change\n> relative to HEAD, there is no \"discarding\" going on. You are\n> actively introducing a change to an unchanged file by checking\n> contents out of a different revision.\n> \n>> To me, \"discard local changes\" imply that there will be no uncommited\n>> changes on the files implied in the command after the operation.\n> \n> Yup.\nThanks for the comments.\nI agree that we should keep the headline as is.\nWhat is about the the rest of the patch?\nDoes it makes sense ?\n"},{"id":"264037","messageId":"xmqqd20u48at.fsf@gitster.dls.corp.google.com","threadId":"39654","inReplyTo":"xmqqoake4akt.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-17T16:19:06Z","receivedAt":"2015-06-17T16:19:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Matthieu Moy writes:\n>\n>> Yes, but \"Switch branchs or discard local changes\" still does not\n>> describe \"git checkout HEAD^^^ -- file.txt\" (restore to an old state,\n>> but does not switch branch) or \"git checkout -- file.txt\" (get from the\n>> index).\n>\n> You are right, especially when file.txt does not have any change\n> relative to HEAD, there is no \"discarding\" going on. You are\n> actively introducing a change to an unchanged file by checking\n> contents out of a different revision.\n>\n>> To me, \"discard local changes\" imply that there will be no uncommited\n>> changes on the files implied in the command after the operation.\n>\n> Yup.\n\nWhat was discussed in this thread sounded suspiciously familiar ;-).\n\nUnfortunately \"overwrite changes in the working tree\" and \"discard\nlocal changes\" are equally bad. As it does not say overwrite with\nwhat, we invite the original confusion that triggered these threads\nif the reader thought an equally useful but different \"overwrites\nwith result of merging your local changes to the pristine\" (similar\nto what \"checkout -m\" does) would happen.\n\nAt least, \"restore working tree files\" without saying \"restoring\nthem to what state?\" is much less likely to cause such a confusion.\n\nSo perhaps\n\n git-checkout - Switch branches or restore working tree files\n\nin the headline, and then explain \"restore to what state\" in the\ndescription?\n"},{"id":"264042","messageId":"5581A3A3.1070908@web.de","threadId":"39654","inReplyTo":"xmqqd20u48at.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2015-06-17T16:43:15Z","receivedAt":"2015-06-17T16:43:15Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On 2015-06-17 18.19, Junio C Hamano wrote:\n> Junio C Hamano writes:\n> \n>> Matthieu Moy writes:\n>>\n>>> Yes, but \"Switch branchs or discard local changes\" still does not\n>>> describe \"git checkout HEAD^^^ -- file.txt\" (restore to an old state,\n>>> but does not switch branch) or \"git checkout -- file.txt\" (get from the\n>>> index).\n>>\n>> You are right, especially when file.txt does not have any change\n>> relative to HEAD, there is no \"discarding\" going on. You are\n>> actively introducing a change to an unchanged file by checking\n>> contents out of a different revision.\n>>\n>>> To me, \"discard local changes\" imply that there will be no uncommited\n>>> changes on the files implied in the command after the operation.\n>>\n>> Yup.\n> \n> What was discussed in this thread sounded suspiciously familiar ;-).\n> \n> Unfortunately \"overwrite changes in the working tree\" and \"discard\n> local changes\" are equally bad. As it does not say overwrite with\n> what, we invite the original confusion that triggered these threads\n> if the reader thought an equally useful but different \"overwrites\n> with result of merging your local changes to the pristine\" (similar\n> to what \"checkout -m\" does) would happen.\n> \n> At least, \"restore working tree files\" without saying \"restoring\n> them to what state?\" is much less likely to cause such a confusion.\n> \n> So perhaps\n> \n> git-checkout - Switch branches or restore working tree files\n> \n> in the headline, and then explain \"restore to what state\" in the\n> description?\nI'm not sure if the \"restore\" is always the right thing to describe:\n'git checkout -- '\nwill \"copy\" the version from another commit into the workspace.\n\nMy v3 will probably use the original line:\ngit-checkout - Checkout a branch or paths to the working tree\n\n(and improve the description)\n\ngit-checkout - Checkout a branch or paths to the working tree\n"},{"id":"264048","messageId":"vpqh9q6gsdt.fsf@anie.imag.fr","threadId":"39654","inReplyTo":"5581A3A3.1070908@web.de","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-06-17T17:24:30Z","receivedAt":"2015-06-17T17:24:30Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Torsten Bögershausen writes:\n\n> My v3 will probably use the original line:\n> git-checkout - Checkout a branch or paths to the working tree\n\nI think mentionning \"Switch branch\" was a real improvement. For someone\nnot familiar with the version control vocabulary, \"checkout\" does not\nmean much (just looked in a dictionary, it talks about payment and\nleaving a room in a hotel ...). And someone not understanding what\n\"checkout\" means in this context won't be helped much reading the\ndescription and getting \"checkout\" there.\n\n(Ironically, Junio did almost the same remark when I proposed to\ndocument \"git describe\" as \"Describe ...\", but the word \"describe\" does\nnot have the ambiguity problem that \"checkout\" has)\n\n> 'git checkout -- '\n> will \"copy\" the version from another commit into the workspace.\n\nIf exists, it means that the state of this path existed\nsomewhere in in the past (well, modulo \"git add -p\" and other\nways to cheat with history).\n\nSo, to me, \"restore a previous version\" does apply in this case. Perhaps\n\"restore a recorded state into the worktree\" (my favorite up to now I\nthink).\n\nBut as you say, it copies into the workspace, so \"copy a previous\nversion into the workspace\" sounds good to me.\n\nBasically, I'm fine with anything starting with \"Switch branches or\",\nbut please do change the headline ;-).\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"264051","messageId":"mlsc62$8u5$1@ger.gmane.org","threadId":"39654","inReplyTo":"vpqh9q6gsdt.fsf@anie.imag.fr","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Andres G. Aragoneses","fromEmail":"knocte@gmail.com","sentAt":"2015-06-17T17:53:06Z","receivedAt":"2015-06-17T17:53:06Z","isPatch":true,"sender":{"key":"knocte@gmail.com","avatar":"https://gravatar.com/avatar/020c5605dcd7456d87a5f29a2af53e7bdf135fe9ccda514b9f34ab3a7e46db27?d=mp&s=160"},"body":"On 17/06/15 19:24, Matthieu Moy wrote:\n> Torsten Bögershausen writes:\n>\n>> My v3 will probably use the original line:\n>> git-checkout - Checkout a branch or paths to the working tree\n>\n> I think mentionning \"Switch branch\" was a real improvement. For someone\n> not familiar with the version control vocabulary, \"checkout\" does not\n> mean much (just looked in a dictionary, it talks about payment and\n> leaving a room in a hotel ...). And someone not understanding what\n> \"checkout\" means in this context won't be helped much reading the\n> description and getting \"checkout\" there.\n>\n> (Ironically, Junio did almost the same remark when I proposed to\n> document \"git describe\" as \"Describe ...\", but the word \"describe\" does\n> not have the ambiguity problem that \"checkout\" has)\n>\n>> 'git checkout -- '\n>> will \"copy\" the version from another commit into the workspace.\n>\n> If exists, it means that the state of this path existed\n> somewhere in in the past (well, modulo \"git add -p\" and other\n> ways to cheat with history).\n>\n> So, to me, \"restore a previous version\" does apply in this case. Perhaps\n> \"restore a recorded state into the worktree\" (my favorite up to now I\n> think).\n>\n> But as you say, it copies into the workspace, so \"copy a previous\n> version into the workspace\" sounds good to me.\n>\n> Basically, I'm fine with anything starting with \"Switch branches or\",\n> but please do change the headline ;-).\n>\n\nHaving read all this thread, I think it's really confusing that:\n1) We have this command named \"checkout\", as Matthieu points out.\n2) This command allows different distinct operations (one for when it \nreceives a path, other for when it receives a branch, other for when it \nreceives a commit...).\n\nSo what I would propose is fix the root of the problem: split these \ncommand in several ones, and mark the \"checkout\" command as deprecated \n(it would still allow the same functions as before, but it would not be \ndocumented, and would be announced as deprecated when used).\n\nSo then we could have a \"git switch \" for switching to a \ndifferent branch.\n\nAlso a \"git discard \" to discard local changes.\n\nEtcetera.\n\nComments?\n"},{"id":"264060","messageId":"xmqqpp4u6swo.fsf@gitster.dls.corp.google.com","threadId":"39654","inReplyTo":"vpqh9q6gsdt.fsf@anie.imag.fr","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-17T19:23:19Z","receivedAt":"2015-06-17T19:23:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> Torsten Bögershausen writes:\n>\n>> My v3 will probably use the original line:\n>> git-checkout - Checkout a branch or paths to the working tree\n>\n> I think mentionning \"Switch branch\" was a real improvement. For someone\n> not familiar with the version control vocabulary, \"checkout\" does not\n> mean much (just looked in a dictionary, it talks about payment and\n> leaving a room in a hotel ...). And someone not understanding what\n> \"checkout\" means in this context won't be helped much reading the\n> description and getting \"checkout\" there.\n\nOr, borrow a book from a library, which I think is the closest\nanalogy for this operation. But you are right. It is suboptimal to\nexplain \"checkout\" in terms of \"checkout\" ;-).\n\n> But as you say, it copies into the workspace, so \"copy a previous\n> version into the workspace\" sounds good to me.\n\nI am afraid that \"previous\" would lead to \"Ah, you mean HEAD~1?\"\nconfusion. In any case, you cannot copy what hasn't yet been\ncreated, \"previous\" is superfluous.\n\nI think \"restore\" also by definition has to go back to _some_\nexisting version, not a future yet-to-be-created one, so \"restore to\nsome previous state\" is superfluous; in that sense, I find that\n\"restore working tree files\" may still be the one that makes most\nsense, at least to me, among the phrases floated in this thread so\nfar.\n\n> Basically, I'm fine with anything starting with \"Switch branches or\",\n> but please do change the headline ;-).\n\nLikewise; I agree \"switch branches or\" part is good.\n"},{"id":"264062","messageId":"xmqqlhfi6su2.fsf@gitster.dls.corp.google.com","threadId":"39654","inReplyTo":"mlsc62$8u5$1@ger.gmane.org","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-17T19:24:53Z","receivedAt":"2015-06-17T19:24:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Andres G. Aragoneses\" writes:\n\n> Comments?\n\nNo.\n"},{"id":"264067","messageId":"5581CAA6.5080306@web.de","threadId":"39654","inReplyTo":"xmqqpp4u6swo.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2015-06-17T19:29:42Z","receivedAt":"2015-06-17T19:29:42Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On 2015-06-17 21.23, Junio C Hamano wrote:\n[]\n>> Basically, I'm fine with anything starting with \"Switch branches or\",\n>> but please do change the headline ;-).\n> \n> Likewise; I agree \"switch branches or\" part is good.\n\nHow about this:\n\ngit-checkout - Switch branches or restore changes to the working tree\n"},{"id":"264075","messageId":"xmqq8ubi6rap.fsf@gitster.dls.corp.google.com","threadId":"39654","inReplyTo":"5581CAA6.5080306@web.de","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-17T19:58:06Z","receivedAt":"2015-06-17T19:58:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Torsten Bögershausen writes:\n\n> On 2015-06-17 21.23, Junio C Hamano wrote:\n> []\n>>> Basically, I'm fine with anything starting with \"Switch branches or\",\n>>> but please do change the headline ;-).\n>> \n>> Likewise; I agree \"switch branches or\" part is good.\n>\n> How about this:\n>\n> git-checkout - Switch branches or restore changes to the working tree\n\nGahh. We are NOT restoring CHANGES. We are restoring the whole\ncontents to a path.\n\nIt is perfectly fine to do this:\n\n\tgit reset --hard\n git checkout HEAD^ hello.c\n\nThere is no changes in hello.c after \"reset --hard\".\n\nThis is what makes it tempting for me to say \"check out (an existing\ncontents to) a working tree file\".\n\nMoreover, it does not matter if the target file is changed or not in\nthe first place, so your added text:\n\n>> 'git checkout' with or `--patch` is used to restore modified or\n>> deleted paths to their original contents from the index or replace paths\n>> with the contents from a named (most often a commit-ish).\n\nthat says \"restoring modified or deleted is from the index,\nreplacing is from a tree-ish\" is placing a stress on a wrong spot, I\nwould think.\n\n\"Checkout individual files\" is to \"replace contents with existing\nversions, taken either from the index or from a named tree-ish.\"\nThat is done in preparation to come up with the suitable contents\nfor specified paths.\n\nThis is a tangent, but on the other hand, \"checkout a whole branch\"\nis to prepare the working tree to be used to modify the specified\nbranch. And that is why the word \"checkout\" makes sense for both\noperations.\n"},{"id":"264105","messageId":"CACsJy8COWS+LoVOxKmAdMhk8FPEnOZpJ1mesJr0orOD7wN2Qsg@mail.gmail.com","threadId":"39654","inReplyTo":"xmqq8ubi6rap.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2015-06-18T00:37:45Z","receivedAt":"2015-06-18T00:37:45Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Thu, Jun 18, 2015 at 2:58 AM, Junio C Hamano wrote:\n> Torsten Bögershausen writes:\n>\n>> On 2015-06-17 21.23, Junio C Hamano wrote:\n>> []\n>>>> Basically, I'm fine with anything starting with \"Switch branches or\",\n>>>> but please do change the headline ;-).\n>>>\n>>> Likewise; I agree \"switch branches or\" part is good.\n>>\n>> How about this:\n>>\n>> git-checkout - Switch branches or restore changes to the working tree\n>\n> Gahh. We are NOT restoring CHANGES. We are restoring the whole\n> contents to a path.\n\n\"the whole contents\" is only true when --patch is not used, I think.\n-- \nDuy\n"},{"id":"264106","messageId":"xmqqy4jh4ydz.fsf@gitster.dls.corp.google.com","threadId":"39654","inReplyTo":"CACsJy8COWS+LoVOxKmAdMhk8FPEnOZpJ1mesJr0orOD7wN2Qsg@mail.gmail.com","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-18T01:07:52Z","receivedAt":"2015-06-18T01:07:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Duy Nguyen writes:\n\n>>> How about this:\n>>>\n>>> git-checkout - Switch branches or restore changes to the working tree\n>>\n>> Gahh. We are NOT restoring CHANGES. We are restoring the whole\n>> contents to a path.\n>\n> \"the whole contents\" is only true when --patch is not used, I think.\n\nI've seen that people repeat this \"patch is not the whole\" and have\nignored that comment; you really need to think if that nitpick adds\nanything of value to the description before repeating it.\n\nThe \"patch\" interface of course allows you to pick and choose. You\nhave some contents (call it W) in the working tree. You have\ndifferent contents (call it X) somewhere else. Being able to do\nthat is the whole point of the feature.\n\nBut what is presented you as the choice to pick or ignore? It is\nthe difference between W and X. If you take none from what is\noffered, you won't check out anything. If you take all of them, you\ncheck out the whole of X. The result is somewhere in between. \n\nAn important point that everybody who repeats \"patch is not the\nwhole\" seems to be missing is that it will never be somewhere\nbetween W and Y (the latter of which is different from X).\n\nNow, what is the X in this operation?\n\nIt is either what is registered in the index, or in the tree-ish\nspecified on the command line.\n\nSo I'd say that the right mental model to understand the \"--patch\"\nfeature is that it allows you to check out the whole contents from\nelsewhere; after the command line argument selects from where, i.e.\neither from the index or from a tree-ish, you _additionally_ have a\nchoice to pick which part of that whole to use. The diff between W\nand HEAD or W and index, i.e. \"CHANGES\", does not play any part of\nthis selection process.\n"},{"id":"264108","messageId":"vpqioalfqm7.fsf@anie.imag.fr","threadId":"39654","inReplyTo":"xmqqpp4u6swo.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH v2] git-checkout.txt: Document \"git checkout \" better","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-06-18T07:00:16Z","receivedAt":"2015-06-18T07:00:16Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Junio C Hamano writes:\n\n> I think \"restore\" also by definition has to go back to _some_\n> existing version, not a future yet-to-be-created one, so \"restore to\n> some previous state\" is superfluous;\n\nThat's why I found \"restore recorded state\" not too bad.\n\n> \"restore working tree files\"\n\nNot a native, but to me \"restore file\" sounds like \"the file is damaged,\nit needs to be restored/repaired\".\n\nIn any case,\n\n Switch branches or restore working tree files\n\nis an improvement over the existing to me, so my bikeshedding should not\nbe used to reject this proposal.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"}]}