{"thread":{"id":"45704","subject":"[PATCH] Documentation/git-checkout: make doc. of checkout clearer","startedAt":"2017-04-15T20:17:24Z","lastAt":"2017-04-25T09:11:38Z","messageCount":23,"participants":["Christoph Michelbach","Philip Oakley","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"316900","messageId":"1492287435.14812.2.camel@gmail.com","threadId":"45704","inReplyTo":null,"subject":"[PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Christoph Michelbach","fromEmail":"michelbach94@gmail.com","sentAt":"2017-04-15T20:17:15Z","receivedAt":"2017-04-15T20:17:24Z","isPatch":true,"sender":{"key":"michelbach94@gmail.com","avatar":null},"body":"While technically in the documentation, the fact that changes\nintroduced by a checkout are staged automatically, was\nnot obvious when reading its documentation. It is now specifically\npointed out.\n\nSigned-off-by: Christoph Michelbach \n---\n Documentation/git-checkout.txt | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 8e2c066..cfd7b18 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -85,9 +85,10 @@ Omitting detaches HEAD at the tip of the current branch.\n \tfrom the index file or from a named (most often a\n \tcommit).  In this case, the `-b` and `--track` options are\n \tmeaningless and giving either of them results in an error.  The\n-\t argument can be used to specify a specific tree-ish\n-\t(i.e.  commit, tag or tree) to update the index for the given\n-\tpaths before updating the working tree.\n+\t argument can be used to specify the tree-ish (i.e.\n+\tcommit,\ttag, or tree) to update the index to for the given paths\n+\tbefore updating the working tree accordingly.  Note that this means\n+\tthat the changes this command introduces are staged automatically.\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-- \n2.7.4\n"},{"id":"316901","messageId":"9535BE255A654CADB7B0AE7599A6FA96@PhilipOakley","threadId":"45704","inReplyTo":"1492287435.14812.2.camel@gmail.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2017-04-15T23:28:16Z","receivedAt":"2017-04-15T23:28:24Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Christoph Michelbach\" \n> While technically in the documentation, the fact that changes\n> introduced by a checkout are staged automatically, was\n> not obvious when reading its documentation. It is now specifically\n> pointed out.\n>\n> Signed-off-by: Christoph Michelbach \n> ---\n> Documentation/git-checkout.txt | 7 ++++---\n> 1 file changed, 4 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-checkout.txt \n> b/Documentation/git-checkout.txt\n> index 8e2c066..cfd7b18 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -85,9 +85,10 @@ Omitting detaches HEAD at the tip of the \n> current branch.\n> from the index file or from a named (most often a\n> commit). In this case, the `-b` and `--track` options are\n> meaningless and giving either of them results in an error. The\n> - argument can be used to specify a specific tree-ish\n> - (i.e. commit, tag or tree) to update the index for the given\n\nDo these lines above actually need reflowing? Their content hasn't changed \nmaking it more difficult to spot the significant changes below here.\n\n> - paths before updating the working tree.\n> + argument can be used to specify the tree-ish (i.e.\n> + commit, tag, or tree) to update the index to for the given paths\n> + before updating the working tree accordingly.\n\n> + Note that this means\n> + that the changes this command introduces are staged automatically.\n\nDoes this actually capture the intent of the user confusion it's meant to \ncover? I may have missed the original discussions.\n\nFor a clean commit checkout my mental model is not one of anything new being \nactively staged i.e. different from what was in the commit. I can see that \nif a particular tree is checkout then it's implicit staging could well be a \nsurprise.\n\nI am in favour of improving the documentation to avoid user surprise\n\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> -- \n> 2.7.4\n>\n--\nPhilip \n\n"},{"id":"316946","messageId":"1492347718.19687.14.camel@gmail.com","threadId":"45704","inReplyTo":"9535BE255A654CADB7B0AE7599A6FA96@PhilipOakley","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Christoph Michelbach","fromEmail":"michelbach94@gmail.com","sentAt":"2017-04-16T13:01:58Z","receivedAt":"2017-04-16T13:02:08Z","isPatch":true,"sender":{"key":"michelbach94@gmail.com","avatar":null},"body":"On Sun, 2017-04-16 at 00:28 +0100, Philip Oakley wrote:\n> From: \"Christoph Michelbach\" \n> > \n> > While technically in the documentation, the fact that changes\n> > introduced by a checkout are staged automatically, was\n> > not obvious when reading its documentation. It is now specifically\n> > pointed out.\n> > \n> > Signed-off-by: Christoph Michelbach \n> > ---\n> > Documentation/git-checkout.txt | 7 ++++---\n> > 1 file changed, 4 insertions(+), 3 deletions(-)\n> > \n> > diff --git a/Documentation/git-checkout.txt \n> > b/Documentation/git-checkout.txt\n> > index 8e2c066..cfd7b18 100644\n> > --- a/Documentation/git-checkout.txt\n> > +++ b/Documentation/git-checkout.txt\n> > @@ -85,9 +85,10 @@ Omitting detaches HEAD at the tip of the \n> > current branch.\n> > from the index file or from a named (most often a\n> > commit). In this case, the `-b` and `--track` options are\n> > meaningless and giving either of them results in an error. The\n> > - argument can be used to specify a specific tree-ish\n> > - (i.e. commit, tag or tree) to update the index for the given\n> Do these lines above actually need reflowing? Their content hasn't changed \n> making it more difficult to spot the significant changes below here.\n\nThey're just part of the context of the automatically created patch.\n\n\n> > +                               Note that this means\n> > + that the changes this command introduces are staged automatically.\n> Does this actually capture the intent of the user confusion it's meant to \n> cover? I may have missed the original discussions.\n\nThere is no original discussion in this mailing list. I got surprised the command\nautomatically modified my staging area even though I didn't remember to have read it in\nthe corresponding man page. Upon reading the relevant part of the man page again, I\nnoticed that it in fact can be inferred from the half sentence \"to update the index for\nthe given paths before updating the working tree.\" but it isn't pointed out explicitly.\nDoing so doesn't take a lot more text and can avoid such surprises. So yes, if it's\npointed out explicitly, the confusion is removed.\n\n\n> For a clean commit checkout my mental model is not one of anything new being \n> actively staged i.e. different from what was in the commit.\n\nNote that this is not about something like `git checkout 925b29` but about something like\n`git checkout 925b29 src`.\n\n\n> I can see that \n> if a particular tree is checkout then it's implicit staging could well be a \n> surprise.\n\nAnd it is actually documented. Just not explicitly mentioned / pointed out.\n\n--\nChristoph\n\n"},{"id":"316954","messageId":"2DCA89C3FDFF41E5B3651018BF837267@PhilipOakley","threadId":"45704","inReplyTo":"1492347718.19687.14.camel@gmail.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2017-04-16T18:03:08Z","receivedAt":"2017-04-16T18:03:17Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Christoph Michelbach\" \n> On Sun, 2017-04-16 at 00:28 +0100, Philip Oakley wrote:\n>> From: \"Christoph Michelbach\" \n>> >\n>> > While technically in the documentation, the fact that changes\n>> > introduced by a checkout are staged automatically, was\n>> > not obvious when reading its documentation. It is now specifically\n>> > pointed out.\n>> >\n>> > Signed-off-by: Christoph Michelbach \n>> > ---\n>> > Documentation/git-checkout.txt | 7 ++++---\n>> > 1 file changed, 4 insertions(+), 3 deletions(-)\n>> >\n>> > diff --git a/Documentation/git-checkout.txt\n>> > b/Documentation/git-checkout.txt\n>> > index 8e2c066..cfd7b18 100644\n>> > --- a/Documentation/git-checkout.txt\n>> > +++ b/Documentation/git-checkout.txt\n>> > @@ -85,9 +85,10 @@ Omitting detaches HEAD at the tip of the\n>> > current branch.\n>> > from the index file or from a named (most often a\n>> > commit). In this case, the `-b` and `--track` options are\n>> > meaningless and giving either of them results in an error. The\n>> > - argument can be used to specify a specific tree-ish\n>> > - (i.e. commit, tag or tree) to update the index for the given\n>> Do these lines above actually need reflowing? Their content hasn't\n>> changed\n>> making it more difficult to spot the significant changes below here.\n>\n> They're just part of the context of the automatically created patch.\n\nThe lines with +/- markings are the actual change lines. It's the lines\nwithout them that are the context lines.\n\nIt does sound like an accidental reflow where the \"(i.e.\" moved between\nlines, and the \"paths\" moved for the following lines.\n\nIf reflowing is required it's normal to put it in a separate patch so that \neach type of change gets its own commit message.\n>\n>\n>> > + Note that this means\n>> > + that the changes this command introduces are staged automatically.\n>> Does this actually capture the intent of the user confusion it's meant to\n>> cover? I may have missed the original discussions.\n>\n> There is no original discussion in this mailing list. I got surprised the\n> command\n> automatically modified my staging area even though I didn't remember to\n> have read it in\n> the corresponding man page. Upon reading the relevant part of the man page\n> again, I\n> noticed that it in fact can be inferred from the half sentence \"to update\n> the index for\n> the given paths before updating the working tree.\" but it isn't pointed\n> out explicitly.\n> Doing so doesn't take a lot more text and can avoid such surprises. So\n> yes, if it's\n> pointed out explicitly, the confusion is removed.\n>\n>\n>> For a clean commit checkout my mental model is not one of anything new\n>> being\n>> actively staged i.e. different from what was in the commit.\n>\n> Note that this is not about something like `git checkout 925b29` but about\n> something like\n> `git checkout 925b29 src`.\n\nYes, that was the part I was getting at.\n\nThe commit message (and the patch context) doesn't quite give enough to see \nthat is is particular to the -\n\ngit checkout [-p|--patch] [] [--] […​]invocation.\n\n>> I can see that\n>> if a particular tree is checkout then it's implicit staging could well be \n>> a\n>> surprise.\n\n> And it is actually documented. Just not explicitly mentioned / pointed \n> out.\n\nIt maybe worth thinking a bit more about how such a mental model may happen.\n\nTo those in the know it sounds obvious that the path content replaces the \nold path. It's that this implies a *change* within the commit that may not \nbe.\n\nExplaining that it at the heart of the documentation change.\n\n> > --\n> Christoph\n> >\n--\nPhilip \n\n"},{"id":"316956","messageId":"1492368692.22852.9.camel@gmail.com","threadId":"45704","inReplyTo":"2DCA89C3FDFF41E5B3651018BF837267@PhilipOakley","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Christoph Michelbach","fromEmail":"michelbach94@gmail.com","sentAt":"2017-04-16T18:51:32Z","receivedAt":"2017-04-16T18:51:41Z","isPatch":true,"sender":{"key":"michelbach94@gmail.com","avatar":null},"body":"On Sun, 2017-04-16 at 19:03 +0100, Philip Oakley wrote:\n> From: \"Christoph Michelbach\" \n> > \n> > On Sun, 2017-04-16 at 00:28 +0100, Philip Oakley wrote:\n> > > \n> > > From: \"Christoph Michelbach\" \n> > > > \n> > > > \n> > > > While technically in the documentation, the fact that changes\n> > > > introduced by a checkout are staged automatically,\n> > > > was\n> > > > not obvious when reading its documentation. It is now\n> > > > specifically\n> > > > pointed out.\n> > > > \n> > > > Signed-off-by: Christoph Michelbach \n> > > > ---\n> > > > Documentation/git-checkout.txt | 7 ++++---\n> > > > 1 file changed, 4 insertions(+), 3 deletions(-)\n> > > > \n> > > > diff --git a/Documentation/git-checkout.txt\n> > > > b/Documentation/git-checkout.txt\n> > > > index 8e2c066..cfd7b18 100644\n> > > > --- a/Documentation/git-checkout.txt\n> > > > +++ b/Documentation/git-checkout.txt\n> > > > @@ -85,9 +85,10 @@ Omitting detaches HEAD at the tip of\n> > > > the\n> > > > current branch.\n> > > > from the index file or from a named (most often a\n> > > > commit). In this case, the `-b` and `--track` options are\n> > > > meaningless and giving either of them results in an error. The\n> > > > - argument can be used to specify a specific tree-ish\n> > > > - (i.e. commit, tag or tree) to update the index for the given\n> > > Do these lines above actually need reflowing? Their content hasn't\n> > > changed\n> > > making it more difficult to spot the significant changes below\n> > > here.\n> > They're just part of the context of the automatically created patch.\n> The lines with +/- markings are the actual change lines. It's the\n> lines\n> without them that are the context lines.\n> \n> It does sound like an accidental reflow where the \"(i.e.\" moved\n> between\n> lines, and the \"paths\" moved for the following lines.\n> \n> If reflowing is required it's normal to put it in a separate patch so\n> that \n> each type of change gets its own commit message.\n\nAh, right. I added a missing \"to\" and changed \"to specify a specific\".\n\n\n> > > For a clean commit checkout my mental model is not one of anything\n> > > new\n> > > being\n> > > actively staged i.e. different from what was in the commit.\n> > Note that this is not about something like `git checkout 925b29` but\n> > about\n> > something like\n> > `git checkout 925b29 src`.\n> Yes, that was the part I was getting at.\n> \n> The commit message (and the patch context) doesn't quite give enough\n> to see \n> that is is particular to the -\n> \n> git checkout [-p|--patch] [] [--] […]invocation.\n\nIt's: git checkout [-p|--patch] [] [--] ...\n\nThe paths aren't optional. Added it to the commit message:\n\n\nWhile technically in the documentation, the fact that changes\nintroduced by a `git checkout [-p|--patch] [] [--]\n...` are staged automatically, was not obvious when\nreading its documentation. It is now specifically pointed out.\n\nRelated sentence cleaned up.\n\nSigned-off-by: Christoph Michelbach \n---\n Documentation/git-checkout.txt | 7 ++++---\n 1 file changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-\ncheckout.txt\nindex 8e2c066..cfd7b18 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -85,9 +85,10 @@ Omitting detaches HEAD at the tip of the\ncurrent branch.\n        from the index file or from a named (most often a\n        commit).  In this case, the `-b` and `--track` options are\n        meaningless and giving either of them results in an error.  The\n-        argument can be used to specify a specific tree-ish\n-       (i.e.  commit, tag or tree) to update the index for the given\n-       paths before updating the working tree.\n+        argument can be used to specify the tree-ish (i.e.\n+       commit, tag, or tree) to update the index to for the given paths\n+       before updating the working tree accordingly.  Note that this\nmeans\n+       that the changes this command introduces are staged\nautomatically.\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\npaths\n-- \n2.7.4\n\n\n--\nChristoph\n"},{"id":"316958","messageId":"DF5E72F5BD2F4BB99D8EC4DF1B4543F7@PhilipOakley","threadId":"45704","inReplyTo":"1492368692.22852.9.camel@gmail.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2017-04-16T21:25:56Z","receivedAt":"2017-04-16T21:26:02Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Christoph Michelbach\" \n> On Sun, 2017-04-16 at 19:03 +0100, Philip Oakley wrote:\n>> From: \"Christoph Michelbach\" \n>> >\n>> > On Sun, 2017-04-16 at 00:28 +0100, Philip Oakley wrote:\n>> > >\n>> > > From: \"Christoph Michelbach\" \n>> > > >\n>> > > >\n>> > > > While technically in the documentation, the fact that changes\n>> > > > introduced by a checkout are staged automatically,\n>> > > > was\n>> > > > not obvious when reading its documentation. It is now\n>> > > > specifically\n>> > > > pointed out.\n>> > > >\n>> > > > Signed-off-by: Christoph Michelbach \n>> > > > ---\n>> > > > Documentation/git-checkout.txt | 7 ++++---\n>> > > > 1 file changed, 4 insertions(+), 3 deletions(-)\n>> > > >\n>> > > > diff --git a/Documentation/git-checkout.txt\n>> > > > b/Documentation/git-checkout.txt\n>> > > > index 8e2c066..cfd7b18 100644\n>> > > > --- a/Documentation/git-checkout.txt\n>> > > > +++ b/Documentation/git-checkout.txt\n>> > > > @@ -85,9 +85,10 @@ Omitting detaches HEAD at the tip of\n>> > > > the\n>> > > > current branch.\n>> > > > from the index file or from a named (most often a\n>> > > > commit). In this case, the `-b` and `--track` options are\n>> > > > meaningless and giving either of them results in an error. The\n>> > > > - argument can be used to specify a specific tree-ish\n>> > > > - (i.e. commit, tag or tree) to update the index for the given\n>> > > Do these lines above actually need reflowing? Their content hasn't\n>> > > changed\n>> > > making it more difficult to spot the significant changes below\n>> > > here.\n>> > They're just part of the context of the automatically created patch.\n>> The lines with +/- markings are the actual change lines. It's the\n>> lines\n>> without them that are the context lines.\n>>\n>> It does sound like an accidental reflow where the \"(i.e.\" moved\n>> between\n>> lines, and the \"paths\" moved for the following lines.\n>>\n>> If reflowing is required it's normal to put it in a separate patch so\n>> that\n>> each type of change gets its own commit message.\n>\n> Ah, right. I added a missing \"to\" and changed \"to specify a specific\".\n>\n>\n>> > > For a clean commit checkout my mental model is not one of anything\n>> > > new\n>> > > being\n>> > > actively staged i.e. different from what was in the commit.\n>> > Note that this is not about something like `git checkout 925b29` but\n>> > about\n>> > something like\n>> > `git checkout 925b29 src`.\n>> Yes, that was the part I was getting at.\n>>\n>> The commit message (and the patch context) doesn't quite give enough\n>> to see\n>> that is is particular to the -\n>>\n>> git checkout [-p|--patch] [] [--] […]\n>> invocation.\n>\n> It's: git checkout [-p|--patch] [] [--] ...\n\nThe one I quoted is direct from the Synopsis, which does indicate there are \npotentially more aspects to resolve, such as the influence of using the \n[-p|--patch] options.\n\nIt maybe that the paragraph / sentence that needs adjusting is;\n\n'git checkout' with or `--patch` is used to restore modified or\ndeleted paths to their original contents from the index or replace paths\nwith the contents from a named (most often a commit-ish).\n\nand split it at the \"or replace paths\" option to pick out your specific \ncase.\n\n>\n> The paths aren't optional. Added it to the commit message:\n>\n>\n> While technically in the documentation, the fact that changes\n> introduced by a `git checkout [-p|--patch] [] [--]\n> ...` are staged automatically, was not obvious when\n> reading its documentation. It is now specifically pointed out.\n>\n> Related sentence cleaned up.\n>\n> Signed-off-by: Christoph Michelbach \n> ---\n> Documentation/git-checkout.txt | 7 ++++---\n> 1 file changed, 4 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-\n> checkout.txt\n> index 8e2c066..cfd7b18 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -85,9 +85,10 @@ Omitting detaches HEAD at the tip of the\n> current branch.\n> from the index file or from a named (most often a\n> commit). In this case, the `-b` and `--track` options are\n> meaningless and giving either of them results in an error. The\n> - argument can be used to specify a specific tree-ish\n\nAh yes, \"specify a specific\" does sound a bit tautological.\n\n> - (i.e. commit, tag or tree) to update the index for the given\n> - paths before updating the working tree.\n> + argument can be used to specify the tree-ish (i.e.\n> + commit, tag, or tree) to update the index to for the given paths\n> + before updating the working tree accordingly. Note that this\n> means\n> + that the changes this command introduces are staged\n> automatically.\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\n> paths\n> -- \n> 2.7.4\n>\n>\n> --\n> Christoph\n> \n\n"},{"id":"316959","messageId":"1492380399.19991.13.camel@gmail.com","threadId":"45704","inReplyTo":"DF5E72F5BD2F4BB99D8EC4DF1B4543F7@PhilipOakley","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Christoph Michelbach","fromEmail":"michelbach94@gmail.com","sentAt":"2017-04-16T22:06:39Z","receivedAt":"2017-04-16T22:06:48Z","isPatch":true,"sender":{"key":"michelbach94@gmail.com","avatar":null},"body":"On Sun, 2017-04-16 at 22:25 +0100, Philip Oakley wrote:\n> From: \"Christoph Michelbach\" \n> > It's: git checkout [-p|--patch] [] [--] ...\n> The one I quoted is direct from the Synopsis, which does indicate\n> there are \n> potentially more aspects to resolve, such as the influence of using\n> the \n> [-p|--patch] options.\n\nOh, you are right. I didn't even notice the one in the synopsis doesn't\nmatch the one further down. The one in the synopsis is wrong because\nafter removing the optional parameters, it's the same as the first one\nin the synopsis, yet we expect very different behavior from them.\n\n\n> It maybe that the paragraph / sentence that needs adjusting is;\n> \n> 'git checkout' with or `--patch` is used to restore modified\n> or\n> deleted paths to their original contents from the index or replace\n> paths\n> with the contents from a named (most often a commit-ish).\n> \n> and split it at the \"or replace paths\" option to pick out your\n> specific \n> case.\n\nThis one is confusing, too: Paths can lead to folders, yet folders whose\ncontents have been modified are not restored to their original contents\nwhen executing that command. Only files are.\n\nAfter reading the documentation and having never used the command\nbefore, one would expect\n\n #!/bin/bash\n rm -Rf repo\n mkdir repo\n cd repo\n git init &> /dev/null\n mkdir folder\n echo a > folder/a\n git add -A\n git commit -m \"Commit 1.\" &> /dev/null\n echo b > folder/b\n git add -A\n git commit -m \"Commit 2.\" &> /dev/null\n echo c > folder/c\n git add -A\n git commit -m \"Commit 3.\" &> /dev/null\n git checkout `git log --pretty=format:%H | tail -1` folder\n ls folder\n\nto print `a`. However, it prints `a b c` because all of the files inside\n`folder` which have been modified or deleted since (here: none) are\nreset to their original state after the first commit, but `folder`\nitself isn't. Yet, the only path which was passed to the command in\nquestion is `folder`.\n\nIn my opinion, this command needs improved documentation (and the\nsynopsis needs to be fixed).\n\n\n--\nChristoph\n\n"},{"id":"317013","messageId":"5EBADDE444D141918F6873BE8456E026@PhilipOakley","threadId":"45704","inReplyTo":"1492380399.19991.13.camel@gmail.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2017-04-17T16:04:05Z","receivedAt":"2017-04-17T16:04:14Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Christoph Michelbach\" \n> On Sun, 2017-04-16 at 22:25 +0100, Philip Oakley wrote:\n>> From: \"Christoph Michelbach\" \n>> > It's: git checkout [-p|--patch] [] [--] ...\n>> The one I quoted is direct from the Synopsis, which does indicate\n>> there are\n>> potentially more aspects to resolve, such as the influence of using\n>> the\n>> [-p|--patch] options.\n>\n> Oh, you are right. I didn't even notice the one in the synopsis doesn't\n> match the one further down. The one in the synopsis is wrong because\n> after removing the optional parameters, it's the same as the first one\n> in the synopsis, yet we expect very different behavior from them.\n>\n>\n>> It maybe that the paragraph / sentence that needs adjusting is;\n>>\n>> 'git checkout' with or `--patch` is used to restore modified\n>> or\n>> deleted paths to their original contents from the index or replace\n>> paths\n>> with the contents from a named (most often a commit-ish).\n>>\n>> and split it at the \"or replace paths\" option to pick out your\n>> specific\n>> case.\n>\n> This one is confusing, too: Paths can lead to folders, yet folders whose\n> contents have been modified are not restored to their original contents\n> when executing that command. Only files are.\n>\n> After reading the documentation and having never used the command\n> before, one would expect\n>\n> #!/bin/bash\n> rm -Rf repo\n> mkdir repo\n> cd repo\n> git init &> /dev/null\n> mkdir folder\n> echo a > folder/a\n> git add -A\n> git commit -m \"Commit 1.\" &> /dev/null\n> echo b > folder/b\n> git add -A\n> git commit -m \"Commit 2.\" &> /dev/null\n> echo c > folder/c\n> git add -A\n> git commit -m \"Commit 3.\" &> /dev/null\n> git checkout `git log --pretty=format:%H | tail -1` folder\n> ls folder\n>\n> to print `a`. However, it prints `a b c` because all of the files inside\n> `folder` which have been modified or deleted since (here: none) are\n> reset to their original state after the first commit, but `folder`\n> itself isn't. Yet, the only path which was passed to the command in\n> question is `folder`.\n>\n> In my opinion, this command needs improved documentation (and the\n> synopsis needs to be fixed).\n>\n\nI think this example is of a different kind of misunderstanding.\n\nWe are at commit 3, with a b c in the working directory and index, and then \nwe ask to checkout certain specific files from the first commit 1, which \ncontains the file a. That old file is extracted and replaces the file from \ncommit 3.\n\nAs the file a is identical there is no change and we still have the original \nb and c files from commit c.\n\nI'd guess that the misunderstanding is that you maybe thought that the whole \ndirectory would be reset to it's old state and the files b and c deleted, \nrather than just the named files present in that old commit being extracted. \nIf we'd created and added a file d just before the checkout, what should \nhave happened to d, and why?\n\n>\n\nComming back to the mental model issue with the implicit staging of checked \nout paths, I suspect this is a because we have both a snapshot and a diff \nbased mental model. Normally the distinction is natural. We have the \nsnapshot from the last commit (or branch checkout) in the index, and then we \nhave the two steps for additional changes we personally made, and then added \nadded, that determine the diff(s).\n\nHowever in this (git checkout -- ) case we don't get that \ntwo step option. There is IIUC no 'git copyout -- ' which \nsimply copies older files into the current worktree without adding it to the \nindex/staging area.\n\nThe confounding of the, both optional, [--patch] and [] in the same \ndescription doesn't make it any easier. Splitting their synopses and \ndescriptions may be the way forward.\n\nI also haven't used the --patch option directly so there may be more issues \nbeneath the surface.\n\n> --\n> Christoph\n>\n>\n--\nPhilip \n\n"},{"id":"317028","messageId":"5FD0803E166B4D2F9F64D8D21AC23EB3@PhilipOakley","threadId":"45704","inReplyTo":"1492452173.11708.22.camel@gmail.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2017-04-17T20:59:44Z","receivedAt":"2017-04-17T20:59:54Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"I've added back the list, as it was accidentally dropped.\n\nFrom: \"Christoph Michelbach\" \n> On Mon, 2017-04-17 at 17:04 +0100, Philip Oakley wrote:\n>> From: \"Christoph Michelbach\" \n>> >\n>> > On Sun, 2017-04-16 at 22:25 +0100, Philip Oakley wrote:\n>> > >\n>> > > From: \"Christoph Michelbach\" \n>> > > >\n>> > > > It's: git checkout [-p|--patch] [] [--] ...\n>> > > The one I quoted is direct from the Synopsis, which does indicate\n>> > > there are\n>> > > potentially more aspects to resolve, such as the influence of\n>> > > using\n>> > > the\n>> > > [-p|--patch] options.\n>> > Oh, you are right. I didn't even notice the one in the synopsis\n>> > doesn't\n>> > match the one further down. The one in the synopsis is wrong because\n>> > after removing the optional parameters, it's the same as the first\n>> > one\n>> > in the synopsis, yet we expect very different behavior from them.\n>> >\n>> >\n>> > >\n>> > > It maybe that the paragraph / sentence that needs adjusting is;\n>> > >\n>> > > 'git checkout' with or `--patch` is used to restore\n>> > > modified\n>> > > or\n>> > > deleted paths to their original contents from the index or replace\n>> > > paths\n>> > > with the contents from a named (most often a commit-\n>> > > ish).\n>> > >\n>> > > and split it at the \"or replace paths\" option to pick out your\n>> > > specific\n>> > > case.\n>> > This one is confusing, too: Paths can lead to folders, yet folders\n>> > whose\n>> > contents have been modified are not restored to their original\n>> > contents\n>> > when executing that command. Only files are.\n>> >\n>> > After reading the documentation and having never used the command\n>> > before, one would expect\n>> >\n>> > #!/bin/bash\n>> > rm -Rf repo\n>> > mkdir repo\n>> > cd repo\n>> > git init &> /dev/null\n>> > mkdir folder\n>> > echo a > folder/a\n>> > git add -A\n>> > git commit -m \"Commit 1.\" &> /dev/null\n>> > echo b > folder/b\n>> > git add -A\n>> > git commit -m \"Commit 2.\" &> /dev/null\n>> > echo c > folder/c\n>> > git add -A\n>> > git commit -m \"Commit 3.\" &> /dev/null\n>> > git checkout `git log --pretty=format:%H | tail -1` folder\n>> > ls folder\n>> >\n>> > to print `a`. However, it prints `a b c` because all of the files\n>> > inside\n>> > `folder` which have been modified or deleted since (here: none) are\n>> > reset to their original state after the first commit, but `folder`\n>> > itself isn't. Yet, the only path which was passed to the command in\n>> > question is `folder`.\n>> >\n>> > In my opinion, this command needs improved documentation (and the\n>> > synopsis needs to be fixed).\n>> >\n>> I think this example is of a different kind of misunderstanding.\n>>\n>> We are at commit 3, with a b c in the working directory and index, and\n>> then\n>> we ask to checkout certain specific files from the first commit 1,\n>> which\n>> contains the file a. That old file is extracted and replaces the file\n>> from\n>> commit 3.\n>>\n>> As the file a is identical there is no change and we still have the\n>> original\n>> b and c files from commit c.\n>>\n>> I'd guess that the misunderstanding is that you maybe thought that the\n>> whole\n>> directory would be reset to it's old state and the files b and c\n>> deleted,\n>> rather than just the named files present in that old commit being\n>> extracted.\n>> If we'd created and added a file d just before the checkout, what\n>> should\n>> have happened to d, and why?\n>\n> I understand what the command does. It behaves perfectly as I expected\n> it to. I did not find this script but wrote it to demonstrate that what\n> the documentation says is different from how it behaves after having\n> read what the documentation says it should do and noticing that that's\n> not how I expected it to work from experience.\n>\n> What it really does is to copy all files described by the given paths\n> from the given tree-ish to the working directory. Or at least that's my\n> expectation of what it does.\n>\n> The documentation, however, says that the given paths are *restored*.\n> This is different.\n\nI don't see that difference in the phrase *restored*, compared to your 'copy \nall files described by the given paths'. Could you explain a little more?\n\n>\n> To answer your question: Nothing should happen to the file `d`. I stated\n> what I genuinely believe to be true above: \"What it really does is to\n> copy all files described by the given paths from the given tree-ish to\n> the working directory.\" If we take this and apply it, we see that `d` is\n> not touched because there is nothing in the given tree-ish that could\n> override it because `d` is not in the index.\n>\n> If we, however, take the existing documentation and apply it, `d` is\n> removed if and only if a path leading to `d` (like `d` if `d` is in the\n> root of the repo or `folder` or `folder/d` if it is in the folder\n> `folder`) is passed as an argument.\n>\n>\n>> Comming back to the mental model issue with the implicit staging of\n>> checked\n>> out paths, I suspect this is a because we have both a snapshot and a\n>> diff\n>> based mental model. Normally the distinction is natural. We have the\n>> snapshot from the last commit (or branch checkout) in the index, and\n>> then we\n>> have the two steps for additional changes we personally made, and then\n>> added\n>> added, that determine the diff(s).\n>>\n>> However in this (git checkout -- ) case we don't get\n>> that\n>> two step option. There is IIUC no 'git copyout -- '\n>> which\n>> simply copies older files into the current worktree without adding it\n>> to the\n>> index/staging area.\n>\n> Well, technically we can `git reset` to that point, then `git checkout-\n> index` where the index is already up-to-date with the state of the\n> working tree we want regarding the files we care about, and then `git\n> reset` back, but I don't think there is a single command for that,\n> either.\n>\n>\n>> The confounding of the, both optional, [--patch] and [] in the\n>> same\n>> description doesn't make it any easier. Splitting their synopses and\n>> descriptions may be the way forward.\n>>\n>> I also haven't used the --patch option directly so there may be more\n>> issues\n>> beneath the surface.\n>\n> Yeah, definitely. There should be 2 separate entries for this.\n>\n> I think someone thought it was a good idea to make `...`\n> optional in the synopsis because `git checkout` behaves in that special\n> way if a patch *or* paths are given. But then, of course, with both `-\n> p|--patch` and `...` optional, the command is the same as the\n> first variation, just with optional parameters -- but the documentation\n> (correctly) says those variations should behave very differently from\n> each other.\n>\n> I don't see how this can be avoided without having 2 separate entries\n> for those cases.\n\ntrue.\n\n--\nPhilip \n\n"},{"id":"317052","messageId":"xmqqefwqims1.fsf@gitster.mtv.corp.google.com","threadId":"45704","inReplyTo":"5EBADDE444D141918F6873BE8456E026@PhilipOakley","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-04-18T00:26:22Z","receivedAt":"2017-04-18T00:26:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> I'd guess that the misunderstanding is that you maybe thought that the\n> whole directory would be reset to it's old state and the files b and c\n> deleted, rather than just the named files present in that old commit\n> being extracted. If we'd created and added a file d just before the\n> checkout, what should have happened to d, and why?\n\nIt probably is a bit unfair to call it \"misunderstanding\". I've had\nthis entry in the \"Leftover Bits\" list for quite some time:\n\n git checkout $commit -- somedir may want to remove somedir/file that\n is not in $commit but is in the original index. Anybody who wants to\n do this needs to consider ramifications and devise transition plans.\n Cf. $gmane/234935\n\nIn the thread, this message:\n\nhttps://public-inbox.org/git/xmqqeh8nxltc.fsf@gitster.dls.corp.google.com/\n\nmay be a good summary.\n"},{"id":"317054","messageId":"xmqqa87eimje.fsf@gitster.mtv.corp.google.com","threadId":"45704","inReplyTo":"5FD0803E166B4D2F9F64D8D21AC23EB3@PhilipOakley","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-04-18T00:31:33Z","receivedAt":"2017-04-18T00:31:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n>>> If we'd created and added a file d just before the checkout, what\n>>> should\n>>> have happened to d, and why?\n>>\n>> I understand what the command does. It behaves perfectly as I expected\n>> it to. I did not find this script but wrote it to demonstrate that what\n>> the documentation says is different from how it behaves after having\n>> read what the documentation says it should do and noticing that that's\n>> not how I expected it to work from experience.\n>>\n>> What it really does is to copy all files described by the given paths\n>> from the given tree-ish to the working directory. Or at least that's my\n>> expectation of what it does.\n>>\n>> The documentation, however, says that the given paths are *restored*.\n>> This is different.\n>\n> I don't see that difference in the phrase *restored*, compared to your\n> 'copy all files described by the given paths'. Could you explain a\n> little more?\n\nI am obviously not Christoph, and I was the one that defined how\n\"checkout -- \" should work, but when you say\n\"restore\" (which is not what I wrote ;-)) it is fair to expect lack\nof 'd' could also be \"restored\", in addition to path that was in the\ndirectory.\n\nObviously, \"grab all paths that match out of , add\nthem to the index and copy them out to the working tree\" will never\nbe able to _restore_ the lack of 'd', even it may match the\n being used to do this checkout, by removing it from the\ncurrent index and the working tree.\n\n"},{"id":"317099","messageId":"1492516221.5720.22.camel@gmail.com","threadId":"45704","inReplyTo":"5FD0803E166B4D2F9F64D8D21AC23EB3@PhilipOakley","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Christoph Michelbach","fromEmail":"michelbach94@gmail.com","sentAt":"2017-04-18T11:50:21Z","receivedAt":"2017-04-18T11:50:32Z","isPatch":true,"sender":{"key":"michelbach94@gmail.com","avatar":null},"body":"On Mon, 2017-04-17 at 21:59 +0100, Philip Oakley wrote:\n> I've added back the list, as it was accidentally dropped.\n\nThanks. I'm sorry. I apparently pressed the wrong button in my emails\nclient. What I wrote is visible in your quote.\n\n\n> From: \"Christoph Michelbach\" \n> > I understand what the command does. It behaves perfectly as I\n> > expected\n> > it to. I did not find this script but wrote it to demonstrate that\n> > what\n> > the documentation says is different from how it behaves after having\n> > read what the documentation says it should do and noticing that\n> > that's\n> > not how I expected it to work from experience.\n> > \n> > What it really does is to copy all files described by the given\n> > paths\n> > from the given tree-ish to the working directory. Or at least that's\n> > my\n> > expectation of what it does.\n> > \n> > The documentation, however, says that the given paths are\n> > *restored*.\n> > This is different.\n> I don't see that difference in the phrase *restored*, compared to your\n> 'copy \n> all files described by the given paths'. Could you explain a little\n> more?\n\nSuppose you have X. If you say X is restored to what it was half an hour\nago, I expect everything about X to be exactly as it was half an hour\nago. So if X is a file containing the text \"Hello, world!\", I expect\nthere to be a file (with the exact same file name) which contains the\ntext \"Hello, world!\", even if I changed that text in the mean time or\ndeleted the file entirely. If X is a folder which contains files, I\nexpect it to have the exact same contents as before. If there were 5\nfiles in the folder half an hour ago, I expect there to be 5 files with\nthe same file names and the same content in each file, again, even if I\ndeleted, renamed, changed the contents of, or added files in the mean\ntime. This is, however, not the case. Suppose I renamed a file from\n\"foo\" to \"bar\". Then there are 6 files, not 5. This is not how X was\nhalf an hour ago.\n\nIf you, however, say that all files in the path X are copied back from\nwhat they were half an hour ago, if X is a file, I expect the exact same\nthing as before for it. And that's actually what happens in reality. But\nif X is a folder, there's a difference: Because only the *files X\ncontains* are copied back – *not X itself* –, all the files in X which\ndo not occur in the state from half an hour ago, are unaffected. So now\nI expect there to be a 6th file because there is no file \"bar\" in the\nstate from half an hour ago which could overwrite the file \"bar\" in the\nworking tree.\n\n\n> > Yeah, definitely. There should be 2 separate entries for this.\n> > \n> > I think someone thought it was a good idea to make `...`\n> > optional in the synopsis because `git checkout` behaves in that\n> > special\n> > way if a patch *or* paths are given. But then, of course, with both\n> > `-\n> > p|--patch` and `...` optional, the command is the same as\n> > the\n> > first variation, just with optional parameters -- but the\n> > documentation\n> > (correctly) says those variations should behave very differently\n> > from\n> > each other.\n> > \n> > I don't see how this can be avoided without having 2 separate\n> > entries\n> > for those cases.\n> true.\n\nSo now we have to find someone who used that command with both a patch\nand a tree-ish present a lot because I have no idea how that would\nbehave and don't even know why you would use it.\n\n\n--\nChristoph\n"},{"id":"317100","messageId":"1492516967.5720.32.camel@gmail.com","threadId":"45704","inReplyTo":"xmqqefwqims1.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Christoph Michelbach","fromEmail":"michelbach94@gmail.com","sentAt":"2017-04-18T12:02:47Z","receivedAt":"2017-04-18T12:02:59Z","isPatch":true,"sender":{"key":"michelbach94@gmail.com","avatar":null},"body":"On Mon, 2017-04-17 at 17:26 -0700, Junio C Hamano wrote:\n> \"Philip Oakley\" writes:\n> \n> > \n> > I'd guess that the misunderstanding is that you maybe thought that\n> > the\n> > whole directory would be reset to it's old state and the files b and\n> > c\n> > deleted, rather than just the named files present in that old commit\n> > being extracted. If we'd created and added a file d just before the\n> > checkout, what should have happened to d, and why?\n> It probably is a bit unfair to call it \"misunderstanding\".  I've had\n> this entry in the \"Leftover Bits\" list for quite some time:\n> \n>     git checkout $commit -- somedir may want to remove somedir/file\n> that\n>     is not in $commit but is in the original index. Anybody who wants\n> to\n>     do this needs to consider ramifications and devise transition\n> plans.\n>     Cf. $gmane/234935\n> \n> In the thread, this message:\n> \n> https://public-inbox.org/git/xmqqeh8nxltc.fsf@gitster.dls.corp.google.\n> com/\n> \n> may be a good summary.\n\nFor clarification: I'm not saying that that's how the command should\nbehave. I merely want the documentation to describe how the command\nactually behaves.\n\nOf course, being able to reset a folder to a previous state would be\ngreat, too. I have needed that several times and what I ended up doing\nis to delete the folder and then do the checkout. This doesn't cause\nproblems if there are no untracked files (as of the state one wants to\nrestore; what's currently tracked is of course irrelevant) you still\nneed in that folder. If that's the case, one must make sure to not\ndelete those files.\n\nI don't know whether there's an easier/better way, though. That's merely\nwhat I did.\n\nHaving the *option* to reset an entire folder rather than the files in\nit would be great.\n\n\n--\nChristoph\n"},{"id":"317101","messageId":"1492518377.5720.47.camel@gmail.com","threadId":"45704","inReplyTo":"xmqqa87eimje.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Christoph Michelbach","fromEmail":"michelbach94@gmail.com","sentAt":"2017-04-18T12:26:17Z","receivedAt":"2017-04-18T12:26:27Z","isPatch":true,"sender":{"key":"michelbach94@gmail.com","avatar":null},"body":"On Mon, 2017-04-17 at 17:31 -0700, Junio C Hamano wrote:\n> \"Philip Oakley\" writes:\n> \n> > \n> > > \n> > > > \n> > > > If we'd created and added a file d just before the checkout,\n> > > > what\n> > > > should\n> > > > have happened to d, and why?\n> > > I understand what the command does. It behaves perfectly as I\n> > > expected\n> > > it to. I did not find this script but wrote it to demonstrate that\n> > > what\n> > > the documentation says is different from how it behaves after\n> > > having\n> > > read what the documentation says it should do and noticing that\n> > > that's\n> > > not how I expected it to work from experience.\n> > > \n> > > What it really does is to copy all files described by the given\n> > > paths\n> > > from the given tree-ish to the working directory. Or at least\n> > > that's my\n> > > expectation of what it does.\n> > > \n> > > The documentation, however, says that the given paths are\n> > > *restored*.\n> > > This is different.\n> > I don't see that difference in the phrase *restored*, compared to\n> > your\n> > 'copy all files described by the given paths'. Could you explain a\n> > little more?\n> I am obviously not Christoph, and I was the one that defined how\n> \"checkout -- \" should work, but when you say\n> \"restore\" (which is not what I wrote ;-)) it is fair to expect lack\n> of 'd' could also be \"restored\", in addition to path that was in the\n> directory.\n\nYes, you didn't write \"restore\" but you wrote: \"It updates the named\npaths in the working tree from the index file or from a named \n(most often a commit).\"\n\nI suppose that from reading this, some people will assume that `d` is\ngone after the command was executed because the folder to which the\ngiven path leads is updated \"in the working tree from the index file or\nfrom a named \", and others will not be sure what happens. But\nI doubt that a lot of people guess the behavior correctly and are sure\nabout them being correct.\n\nNote that for the first group of people, it doesn't matter that git\ndoesn't track folders. You can restore a folder \"in the working tree\nfrom the index file or from a named \" without tracking folders\nbecause there only is one property of a folder git cares about, apart\nfrom it itself being able to access files in that folder: Its name. And\nit can get that name from the paths of the files in that folder. If\nthere are no files in that folder, there isn't a contradiction, either,\nbecause then there is no folder in the index or tree-ish which can\npossibly be restored.\n\n\n> Obviously, \"grab all paths that match out of , add\n> them to the index and copy them out to the working tree\" will never\n> be able to _restore_ the lack of 'd', even it may match the\n> being used to do this checkout, by removing it from the\n> current index and the working tree.\n\nExactly. \"grab all paths that match out of , add them\nto the index and copy them out to the working tree\" is a more accurate\ndescription of what the command does (but it might need some rewording\n;-) ).\n"},{"id":"317170","messageId":"xmqq1sspdvjk.fsf@gitster.mtv.corp.google.com","threadId":"45704","inReplyTo":"1492518377.5720.47.camel@gmail.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-04-19T01:40:31Z","receivedAt":"2017-04-19T01:40:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Christoph Michelbach writes:\n\n> On Mon, 2017-04-17 at 17:31 -0700, Junio C Hamano wrote:\n>\n>> Obviously, \"grab all paths that match out of , add\n>> them to the index and copy them out to the working tree\" will never\n>> be able to _restore_ the lack of 'd', even it may match the\n>> being used to do this checkout, by removing it from the\n>> current index and the working tree.\n>\n> Exactly. \"grab all paths that match out of , add them\n> to the index and copy them out to the working tree\" is a more accurate\n> description of what the command does (but it might need some rewording\n> ;-) ).\n\nOf course it is accurate, as that is how I would write it, not\n\"restore\", if I were doing the documentation.\n\nCare to send in a patch to update the documentation?\n"},{"id":"317198","messageId":"AC79ED43D69A4063B2F30AE43B1AEE63@PhilipOakley","threadId":"45704","inReplyTo":"xmqqa87eimje.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2017-04-19T07:32:08Z","receivedAt":"2017-04-19T07:32:16Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" Sent: Tuesday, April 18, 2017 \n1:31 AM\n> \"Philip Oakley\" writes:\n>\n>>>> If we'd created and added a file d just before the checkout, what\n>>>> should\n>>>> have happened to d, and why?\n>>>\n>>> I understand what the command does. It behaves perfectly as I expected\n>>> it to. I did not find this script but wrote it to demonstrate that what\n>>> the documentation says is different from how it behaves after having\n>>> read what the documentation says it should do and noticing that that's\n>>> not how I expected it to work from experience.\n>>>\n>>> What it really does is to copy all files described by the given paths\n>>> from the given tree-ish to the working directory. Or at least that's my\n>>> expectation of what it does.\n>>>\n>>> The documentation, however, says that the given paths are *restored*.\n>>> This is different.\n>>\n>> I don't see that difference in the phrase *restored*, compared to your\n>> 'copy all files described by the given paths'. Could you explain a\n>> little more?\n>\n> I am obviously not Christoph, and I was the one that defined how\n> \"checkout -- \" should work, but when you say\n> \"restore\" (which is not what I wrote ;-)) it is fair to expect lack\n> of 'd' could also be \"restored\", in addition to path that was in the\n> directory.\n>\n> Obviously, \"grab all paths that match out of , add\n> them to the index and copy them out to the working tree\" will never\n> be able to _restore_ the lack of 'd', even it may match the\n> being used to do this checkout, by removing it from the\n> current index and the working tree.\n>\nMy attempt at asking about an additional file 'd' ended up being a bit of a \nred herring as it went off at a tangent.\n\nHopefully Christoph will hang in to help clarify the original issue. I think \nI'm getting a sense of the potential confusion between the different \nmessages Git sends out, and which one is the right one here. On the one hand \nGit promotes the two step staging area approach, but on the other hand the \ncheckout of a file suggests IIUC that all checkouts will end up as staged \nrevisions (one step only).\n\nPhilip \n\n"},{"id":"317202","messageId":"FFDB9C5D48B642D7B8E4C30352815565@PhilipOakley","threadId":"45704","inReplyTo":"xmqqefwqims1.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2017-04-19T08:14:31Z","receivedAt":"2017-04-19T08:14:41Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Thanks,\n\nThe link does contatin the ref to the original commit, which is helpful. \n(expands to https://github.com/git/git/commit/0a1283bc3955a97557)\n\nPhilip\n[I'll be off-line all day]\n----- Original Message ----- \nFrom: \"Junio C Hamano\" \nTo: \"Philip Oakley\" \nCc: \"Christoph Michelbach\" ; \"Git Mailing List\" \n\nSent: Tuesday, April 18, 2017 1:26 AM\nSubject: Re: [PATCH] Documentation/git-checkout: make doc. of checkout \n clearer\n\n\n> \"Philip Oakley\" writes:\n>\n>> I'd guess that the misunderstanding is that you maybe thought that the\n>> whole directory would be reset to it's old state and the files b and c\n>> deleted, rather than just the named files present in that old commit\n>> being extracted. If we'd created and added a file d just before the\n>> checkout, what should have happened to d, and why?\n>\n> It probably is a bit unfair to call it \"misunderstanding\". I've had\n> this entry in the \"Leftover Bits\" list for quite some time:\n>\n> git checkout $commit -- somedir may want to remove somedir/file that\n> is not in $commit but is in the original index. Anybody who wants to\n> do this needs to consider ramifications and devise transition plans.\n> Cf. $gmane/234935\n>\n> In the thread, this message:\n>\n> https://public-inbox.org/git/xmqqeh8nxltc.fsf@gitster.dls.corp.google.com/\n>\n> may be a good summary.\n> \n\n"},{"id":"317544","messageId":"1492881136.7368.3.camel@gmail.com","threadId":"45704","inReplyTo":"xmqq1sspdvjk.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Christoph Michelbach","fromEmail":"michelbach94@gmail.com","sentAt":"2017-04-22T17:12:16Z","receivedAt":"2017-04-22T17:12:25Z","isPatch":true,"sender":{"key":"michelbach94@gmail.com","avatar":null},"body":"On Tue, 2017-04-18 at 18:40 -0700, Junio C Hamano wrote:\n> Christoph Michelbach writes:\n> \n> > \n> > On Mon, 2017-04-17 at 17:31 -0700, Junio C Hamano wrote:\n> > \n> > > \n> > > Obviously, \"grab all paths that match out of ,\n> > > add\n> > > them to the index and copy them out to the working tree\" will\n> > > never\n> > > be able to _restore_ the lack of 'd', even it may match the\n> > > being used to do this checkout, by removing it from the\n> > > current index and the working tree.\n> > Exactly. \"grab all paths that match out of , add\n> > them\n> > to the index and copy them out to the working tree\" is a more\n> > accurate\n> > description of what the command does (but it might need some\n> > rewording\n> > ;-) ).\n> Of course it is accurate, as that is how I would write it, not\n> \"restore\", if I were doing the documentation.\n> \n> Care to send in a patch to update the documentation?\n\nFrom 10c362b0632255f90e0975fb6656feedca5fd407 Mon Sep 17 00:00:00 2001\nFrom: Christoph Michelbach \nDate: Sat, 22 Apr 2017 18:49:57 +0200\nSubject: [PATCH] Doc./git-checkout: correct doc. of checkout\n...\n\nThe previous documentation states that the named paths are\nupdated both in the index and the working tree. This is not\ncorrect as those paths can point to folders which are not\nupdated to what they are in the given tree-ish. Rather,\nthe files pointed to by the pathspecs are copied from the\ntree-ish to the index and working tree One difference being\nthat one can name paths which are not present in the working\ntree and another being that only files which are already\npresent in the given tree-ish are affected.\n\nFurthermore, the changed text is intended to be more\nintelligible as it is written in a way which is easy to\nfollow, rather than describing the technical process in\norder of execution.\n\nA hint alerting the users that changes introduced by this\ncommand when naming a tree-ish are automatically staged has\nbeen introduced.\n\nSigned-off-by: Christoph Michelbach \n---\n Documentation/git-checkout.txt | 16 +++++++++-------\n 1 file changed, 9 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-\ncheckout.txt\nindex 8e2c066..f74f237 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -81,13 +81,15 @@ Omitting detaches HEAD at the tip of the\ncurrent branch.\n 'git checkout' [-p|--patch] [] [--] ...::\n \n \tWhen or `--patch` are given, 'git checkout' does *not*\n-\tswitch branches.  It updates the named paths in the working\ntree\n-\tfrom the index file or from a named (most often a\n-\tcommit).  In this case, the `-b` and `--track` options are\n-\tmeaningless and giving either of them results in an error.  The\n-\t argument can be used to specify a specific tree-ish\n-\t(i.e.  commit, tag or tree) to update the index for the given\n-\tpaths before updating the working tree.\n+\tswitch branches.  It copies the files matching the pathspecs in\n+\t (i.e. a commit, tag, or tree) to the index and\n+\tsubsequently to the working directory, overwriting changes\n+\t(including deletion of files) in those files.  In this case,\nthe\n+\t-b and --track options are meaningless and giving either of\nthem\n+\tresults in an error.  Note that because the index is updated,\nthe\n+\tchanges introduced by this command are automatically\nstaged.  If\n+\tno tree-ish is provided, the current index is used and remains\n+\tunchanged, modifying only the working directory.\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\npaths\n-- \n2.7.4\n\n"},{"id":"317628","messageId":"xmqqo9vm36xg.fsf@gitster.mtv.corp.google.com","threadId":"45704","inReplyTo":"1492881136.7368.3.camel@gmail.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-04-24T01:55:55Z","receivedAt":"2017-04-24T01:56:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Christoph Michelbach writes:\n\n>> Care to send in a patch to update the documentation?\n\nThanks. The attached patch text appears linewrapped, but I think\nI'll be able to salvage, so forgetting about the formatting, here\nare some comments.\n\n\n> From: Christoph Michelbach \n> Date: Sat, 22 Apr 2017 18:49:57 +0200\n> Subject: [PATCH] Doc./git-checkout: correct doc. of checkout\n> ...\n>\n> The previous documentation states that the named paths are\n> updated both in the index and the working tree. This is not\n> correct as those paths can point to folders which are not\n> updated to what they are in the given tree-ish. Rather,\n> the files pointed to by the pathspecs are copied from the\n\ns/pointed to by/that match/\n\n> tree-ish to the index and working tree One difference being\n\nMissing full-stop after \"tree\".\n\n> that one can name paths which are not present in the working\n> tree ...\n\nThat one is not a difference, I would think. If your current index\nand working tree lack F, you give pathspec that match F, and the\ntree-ish has that path F, that named path _is_ updated both in the\nindex and in the working tree.\n\n> ... and another being that only files which are already\n> present in the given tree-ish are affected.\n\nThis one indeed was missing piece of information.\n\n> Signed-off-by: Christoph Michelbach \n> ---\n>  Documentation/git-checkout.txt | 16 +++++++++-------\n>  1 file changed, 9 insertions(+), 7 deletions(-)\n>\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-\n> checkout.txt\n> index 8e2c066..f74f237 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -81,13 +81,15 @@ Omitting detaches HEAD at the tip of the\n> current branch.\n>  'git checkout' [-p|--patch] [] [--] ...::\n>  \n>  \tWhen or `--patch` are given, 'git checkout' does *not*\n> +\tswitch branches.  It copies the files matching the pathspecs in\n> +\t (i.e. a commit, tag, or tree) to the index and\n\n is misspelled here. Drop (i.e. ...) as (1) it is not\ncorrect (a tag may not point at a tree-ish) and (2) \"checkout\" is\nnot a place to learn what a tree-ish is (glossary is).\n\n> +\tsubsequently to the working directory, overwriting changes\n\nDo we need to say \"subsequently\" when we are aiming to be more\nintelligible by not describing the order of execution? The end\nresult is that the blobs named by the pathspecs from the tree-ish\nare checked out to the index and to the working tree at the same\ntime.\n\n> +...\tNote that because the index is updated, the\n> +\tchanges introduced by this command are automatically staged.\n\nThis is redundant and unnecessary, I would say. If you absolutely\nneed to say this, at least drop \"automatically\". There is nothing\nautomatic about it. The user is asking to checkout the named blobs\nout of the tree-ish to the index and to the working tree, and Git is\nmerely doing as it was told.\n\nIn addition the description is fuzzy; what are \"changes introduced\nby this command\" relative to? If you did \"checkout HEAD path\" after\nediting path in the working tree, is \"reverting my edit\" the\n\"changes introduced by this command\"? If you did \"checkout HEAD\npath\" after editing path, \"git add path\" and then editing path\nfurther, what are the \"changes introduced by this command\"?\n"},{"id":"317674","messageId":"1493036682.4708.9.camel@gmail.com","threadId":"45704","inReplyTo":"xmqqo9vm36xg.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Christoph Michelbach","fromEmail":"michelbach94@gmail.com","sentAt":"2017-04-24T12:24:42Z","receivedAt":"2017-04-24T12:25:03Z","isPatch":true,"sender":{"key":"michelbach94@gmail.com","avatar":null},"body":"On Sun, 2017-04-23 at 18:55 -0700, Junio C Hamano wrote:\n> Christoph Michelbach writes:\n> > From: Christoph Michelbach \n> > Date: Sat, 22 Apr 2017 18:49:57 +0200\n> > Subject: [PATCH] Doc./git-checkout: correct doc. of checkout\n> > ...\n> > \n> > The previous documentation states that the named paths are\n> > updated both in the index and the working tree. This is not\n> > correct as those paths can point to folders which are not\n> > updated to what they are in the given tree-ish. Rather,\n> > the files pointed to by the pathspecs are copied from the\n> s/pointed to by/that match/\n\nOk.\n\n\n> > \n> > tree-ish to the index and working tree One difference being\n> Missing full-stop after \"tree\".\n\nOops.\n\n\n> > \n> > that one can name paths which are not present in the working\n> > tree ...\n> That one is not a difference, I would think.  If your current index\n> and working tree lack F, you give pathspec that match F, and the\n> tree-ish has that path F, that named path _is_ updated both in the\n> index and in the working tree.\n\nI don't think it's inherently obvious that you can name paths which don't\noccur in the working tree if it's stated that those are updated. For\nsomething to be updated, I suppose it has to exist in the first place. But I\ndon't really want to discuss the commit message as everyone even reading it\nalready knows how the command works so I just removed it.\n\n\nFrom 24a5ca5affbe8a09413b72ceb3cb50ae2fe9fd2b Mon Sep 17 00:00:00 2001\nFrom: Christoph Michelbach \nDate: Sat, 22 Apr 2017 18:49:57 +0200\nSubject: [PATCH] Doc./git-checkout: correct doc. of checkout ...\n\nThe previous documentation states that the named paths are\nupdated both in the index and the working tree. This is not\ncorrect as those paths can point to folders which are not\nupdated to what they are in the given tree-ish. Rather,\nthe files which match the pathspecs are copied from the\ntree-ish to the index and working tree. The difference being\nthat only files which are already present in the given\ntree-ish are affected.\n\nFurthermore, the changed text is intended to be more\nintelligible as it is written in a way which is easy to\nfollow, rather than describing the technical process in\norder of execution.\n\nA hint alerting the users that changes introduced by this\ncommand when naming a tree-ish are automatically staged has\nbeen introduced.\n\nSigned-off-by: Christoph Michelbach \n---\n Documentation/git-checkout.txt | 16 +++++++++-------\n 1 file changed, 9 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 8e2c066..306b9d2 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -81,13 +81,15 @@ Omitting detaches HEAD at the tip of the\ncurrent branch.\n 'git checkout' [-p|--patch] [] [--] ...::\n \n \tWhen or `--patch` are given, 'git checkout' does *not*\n-\tswitch branches.  It updates the named paths in the working tree\n-\tfrom the index file or from a named (most often a\n-\tcommit).  In this case, the `-b` and `--track` options are\n-\tmeaningless and giving either of them results in an error.  The\n-\t argument can be used to specify a specific tree-ish\n-\t(i.e.  commit, tag or tree) to update the index for the given\n-\tpaths before updating the working tree.\n+\tswitch branches.  It copies the files matching the pathspecs in\n+\t (i.e. a commit, tag, or tree) to the index and\n+\tsubsequently to the working tree, overwriting changes\n+\t(including deletion of files) in those files.  In this case, the\n+\t-b and --track options are meaningless and giving either of them\n+\tresults in an error.  Note that because the index is updated, the\n+\tchanges introduced by this command are automatically staged.  If\n+\tno tree-ish is provided, the current index is used and remains\n+\tunchanged, modifying only 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-- \n2.7.4\n\n"},{"id":"317676","messageId":"1493038014.4708.21.camel@gmail.com","threadId":"45704","inReplyTo":"xmqqo9vm36xg.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Christoph Michelbach","fromEmail":"michelbach94@gmail.com","sentAt":"2017-04-24T12:46:54Z","receivedAt":"2017-04-24T12:47:12Z","isPatch":true,"sender":{"key":"michelbach94@gmail.com","avatar":null},"body":"I'm sorry, somehow my email client deleted half of your message when I saved it\nwhen replying. I only noticed this when wanting to delete your email and noticed\nthat it was pretty long.\n\n--------------------------------------------------------------------------------\n\nOn Sun, 2017-04-23 at 18:55 -0700, Junio C Hamano wrote:\n> Christoph Michelbach writes:\n> > From: Christoph Michelbach \n> > Date: Sat, 22 Apr 2017 18:49:57 +0200\n> > Subject: [PATCH] Doc./git-checkout: correct doc. of checkout\n> > ...\n> > \n> > The previous documentation states that the named paths are\n> > updated both in the index and the working tree. This is not\n> > correct as those paths can point to folders which are not\n> > updated to what they are in the given tree-ish. Rather,\n> > the files pointed to by the pathspecs are copied from the\n> s/pointed to by/that match/\n\nOk.\n\n\n> > \n> > tree-ish to the index and working tree One difference being\n> Missing full-stop after \"tree\".\n\nOops.\n\n\n> > \n> > that one can name paths which are not present in the working\n> > tree ...\n> That one is not a difference, I would think.  If your current index\n> and working tree lack F, you give pathspec that match F, and the\n> tree-ish has that path F, that named path _is_ updated both in the\n> index and in the working tree.\n\nI don't think it's inherently obvious that you can name paths which don't\noccur in the working tree if it's stated that those are updated. For\nsomething to be updated, I suppose it has to exist in the first place. But I\ndon't really want to discuss the commit message as everyone even reading it\nalready knows how the command works so I just removed it.\n> >  \tWhen or `--patch` are given, 'git checkout' does *not*\n> > +\tswitch branches.  It copies the files matching the pathspecs in\n> > +\t (i.e. a commit, tag, or tree) to the index and\n> is misspelled here.  Drop (i.e. ...) as (1) it is not\n> correct (a tag may not point at a tree-ish) and (2) \"checkout\" is\n> not a place to learn what a tree-ish is (glossary is).\n\nDone.\n\n> \n> > \n> > +\tsubsequently to the working directory, overwriting changes\n> Do we need to say \"subsequently\" when we are aiming to be more\n> intelligible by not describing the order of execution?  The end\n> result is that the blobs named by the pathspecs from the tree-ish\n> are checked out to the index and to the working tree at the same\n> time.\n\nI agree. Done.\n\n\n> \n> > \n> > +...\tNote that because the index is updated, the\n> > +\tchanges introduced by this command are automatically staged.\n> This is redundant and unnecessary, I would say.  If you absolutely\n> need to say this, at least drop \"automatically\".  There is nothing\n> automatic about it.  The user is asking to checkout the named blobs\n> out of the tree-ish to the index and to the working tree, and Git is\n> merely doing as it was told.\n\nDone.\n\n\n> In addition the description is fuzzy; what are \"changes introduced\n> by this command\" relative to?  If you did \"checkout HEAD path\" after\n> editing path in the working tree, is \"reverting my edit\" the\n> \"changes introduced by this command\"?\n\nAll of those no changes which could possibly be staged are immediately staged.\nAll statements about all elements of the empty set are true.\n\n\n> If you did \"checkout HEAD\n> path\" after editing path, \"git add path\" and then editing path\n> further, what are the \"changes introduced by this command\"?\n\nThe command can't introduce any further changes just because you edit files\nafter it has already terminated execution.\n\n\n\nFrom fe0d1298cf4de841af994f4d9f72d49e25edea00 Mon Sep 17 00:00:00 2001\nFrom: Christoph Michelbach \nDate: Sat, 22 Apr 2017 18:49:57 +0200\nSubject: [PATCH] Doc./git-checkout: correct doc. of checkout ...\n\nThe previous documentation states that the named paths are\nupdated both in the index and the working tree. This is not\ncorrect as those paths can point to folders which are not\nupdated to what they are in the given tree-ish. Rather,\nthe files which match the pathspecs are copied from the\ntree-ish to the index and working tree. The difference being\nthat only files which are already present in the given\ntree-ish are affected.\n\nFurthermore, the changed text is intended to be more\nintelligible as it is written in a way which is easy to\nfollow, rather than describing the technical process in\norder of execution.\n\nA hint alerting the users that changes introduced by this\ncommand when naming a tree-ish are automatically staged has\nbeen introduced.\n\nSigned-off-by: Christoph Michelbach \n---\n Documentation/git-checkout.txt | 15 ++++++++-------\n 1 file changed, 8 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 8e2c066..ea3b4df 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -81,13 +81,14 @@ Omitting detaches HEAD at the tip of the current\nbranch.\n 'git checkout' [-p|--patch] [] [--] ...::\n \n \tWhen or `--patch` are given, 'git checkout' does *not*\n-\tswitch branches.  It updates the named paths in the working tree\n-\tfrom the index file or from a named (most often a\n-\tcommit).  In this case, the `-b` and `--track` options are\n-\tmeaningless and giving either of them results in an error.  The\n-\t argument can be used to specify a specific tree-ish\n-\t(i.e.  commit, tag or tree) to update the index for the given\n-\tpaths before updating the working tree.\n+\tswitch branches.  It copies the files matching the pathspecs in\n+\t to the index and to the working tree, overwriting\n+\tchanges\t(including deletion of files) in those files.  In this\n+\tcase, the -b and --track options are meaningless and giving either\n+\tof them results in an error.  Note that because the index is updated,\n+\tthe changes introduced by this command are staged.  If no tree-ish is\n+\tprovided, the current index is used and remains unchanged, modifying\n+\tonly 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-- \n2.7.4\n\n"},{"id":"317749","messageId":"xmqqzif5xo9m.fsf@gitster.mtv.corp.google.com","threadId":"45704","inReplyTo":"1493038014.4708.21.camel@gmail.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-04-25T01:35:33Z","receivedAt":"2017-04-25T01:35:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Christoph Michelbach writes:\n\n> I'm sorry, somehow my email client deleted half of your message when I saved it\n> when replying. I only noticed this when wanting to delete your email and noticed\n> that it was pretty long.\n\nPlease separate your discussion from the patch proper. Check\nDocumentation/SubmittingPatches and send a proper patch like other\npeople do.\n\n\n> From fe0d1298cf4de841af994f4d9f72d49e25edea00 Mon Sep 17 00:00:00 2001\n> From: Christoph Michelbach \n> Date: Sat, 22 Apr 2017 18:49:57 +0200\n> Subject: [PATCH] Doc./git-checkout: correct doc. of checkout ...\n\nThese we take from the e-mail header. You usually remove them from\nthe body of the message (and move the Subject: to e-mail subject), hence\n\n> The previous documentation states that the named paths are\n\nthis line will become the first line in the body of the message.\n\n> A hint alerting the users that changes introduced by this\n> command when naming a tree-ish are automatically staged has\n> been introduced.\n\nWe are still saying automatically here?\n\n> Signed-off-by: Christoph Michelbach \n> ---\n>  Documentation/git-checkout.txt | 15 ++++++++-------\n>  1 file changed, 8 insertions(+), 7 deletions(-)\n\nThis is not limited to your message, but from time to time, I see\nmessages with SP substituted with non-breaking space like the above\ntwo lines (and they appear in the patch text). I can still read and\ncomment on the patch, but it is unusuable as an input to \"git am\" to\nbe applied. I wonder where these NBSP come from---perhaps some\ncommmon MUAs corrupt text messages like this?\n\n>\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index 8e2c066..ea3b4df 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -81,13 +81,14 @@ Omitting detaches HEAD at the tip of the current\n> branch.\n>  'git checkout' [-p|--patch] [] [--] ...::\n>  \n>  \tWhen or `--patch` are given, 'git checkout' does *not*\n> -\tswitch branches.  It updates the named paths in the working tree\n> -\tfrom the index file or from a named (most often a\n> -\tcommit).  In this case, the `-b` and `--track` options are\n> -\tmeaningless and giving either of them results in an error.  The\n> -\t argument can be used to specify a specific tree-ish\n> -\t(i.e.  commit, tag or tree) to update the index for the given\n> -\tpaths before updating the working tree.\n> +\tswitch branches.  It copies the files matching the pathspecs in\n\nI am debating myself if rephrasing \"in \" to \"from\n\" makes the result clearer to understand. When we say\n\"Copy files from T to I and W\", it would be obvious that what does\nnot exist in T will not be copied.\n\nI also wonder \"If no-tree-ish is provided\" at the end of this\nparagraph you have is a bit too far from the above primary point of\nthe description, because you have an unrelated \"In this case,\n-b/-t...\", in between. \n\n\tThe blobs matching the pathspecs are checked out from the\n\tindex to the working tree. Optionally, when is\n\tgiven, the blobs matching the pathspecs from the \n\tis copied to the index before that happens.\n\nis what I would want to say, but obviously that does not describe\nwhat happens in the chronological order, so it is the most clear\ndescription for people who understand what is written, but it will\ntake two reading until the reader gets to that stage X-<.\n\nPerhaps the unrelated \"In this case, the -b...\" should go first; it\nis part of \"does *not* switch branches\". Also even with your patch,\nit starts with \"X is not Y\" and does not clearly say \"X is Z\".\n\n\tWhen or `--patch` ar given, 'git checkout' does\n\t*not* switch branches (giving the `-b` and `--track` options\n\twill cause an error, as they are meaningless). It checks\n\tout paths out of the (if given) and the index to\n\tthe to working tree. When an optional is given\n\tblobs in the that match are copied to\n\tthe index. The blobs that match are then copied\n\tfrom the index to the working tree, overwriting what is in\n\t(or missing from) the working tree.\n\nMay be an improvement (i.e. say what Z is: checking out paths from\ntree-ish and/or index to the working tree). By explicitly phrasing\nthat , from which the index is updated, is optional, it is\nclear that without there is no update to the index.\n\"missing from\" covers two cases: (1) the user removed the file from\nthe working tree and , e.g. HEAD, has the file, hence\nremoved one is resurrected; (2) the user didn't touch the file and\nHEAD didn't have it, but by checking out from that has\nthe file, the user added that new file to the set of files the user\nis working with.\n\nHmm?\n\n"},{"id":"317791","messageId":"1493111483.18809.0.camel@gmail.com","threadId":"45704","inReplyTo":"xmqqzif5xo9m.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer","fromName":"Christoph Michelbach","fromEmail":"michelbach94@gmail.com","sentAt":"2017-04-25T09:11:23Z","receivedAt":"2017-04-25T09:11:38Z","isPatch":true,"sender":{"key":"michelbach94@gmail.com","avatar":null},"body":"I give up. Bye.\nOn Mon, 2017-04-24 at 18:35 -0700, Junio C Hamano wrote:\n> Christoph Michelbach writes:\n> \n> > \n> > I'm sorry, somehow my email client deleted half of your message when I saved\n> > it\n> > when replying. I only noticed this when wanting to delete your email and\n> > noticed\n> > that it was pretty long.\n> Please separate your discussion from the patch proper.  Check\n> Documentation/SubmittingPatches and send a proper patch like other\n> people do.\n> \n> \n> > \n> > From fe0d1298cf4de841af994f4d9f72d49e25edea00 Mon Sep 17 00:00:00 2001\n> > From: Christoph Michelbach \n> > Date: Sat, 22 Apr 2017 18:49:57 +0200\n> > Subject: [PATCH] Doc./git-checkout: correct doc. of checkout ...\n> These we take from the e-mail header.  You usually remove them from\n> the body of the message (and move the Subject: to e-mail subject), hence\n> \n> > \n> > The previous documentation states that the named paths are\n> this line will become the first line in the body of the message.\n> \n> > \n> > A hint alerting the users that changes introduced by this\n> > command when naming a tree-ish are automatically staged has\n> > been introduced.\n> We are still saying automatically here?\n> \n> > \n> > Signed-off-by: Christoph Michelbach \n> > ---\n> >  Documentation/git-checkout.txt | 15 ++++++++-------\n> >  1 file changed, 8 insertions(+), 7 deletions(-)\n> This is not limited to your message, but from time to time, I see\n> messages with SP substituted with non-breaking space like the above\n> two lines (and they appear in the patch text).  I can still read and\n> comment on the patch, but it is unusuable as an input to \"git am\" to\n> be applied.  I wonder where these NBSP come from---perhaps some\n> commmon MUAs corrupt text messages like this?\n> \n> > \n> > \n> > diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> > index 8e2c066..ea3b4df 100644\n> > --- a/Documentation/git-checkout.txt\n> > +++ b/Documentation/git-checkout.txt\n> > @@ -81,13 +81,14 @@ Omitting detaches HEAD at the tip of the\n> > current\n> > branch.\n> >  'git checkout' [-p|--patch] [] [--] ...::\n> >  \n> >  \tWhen or `--patch` are given, 'git checkout' does *not*\n> > -\tswitch branches.  It updates the named paths in the working tree\n> > -\tfrom the index file or from a named (most often a\n> > -\tcommit).  In this case, the `-b` and `--track` options are\n> > -\tmeaningless and giving either of them results in an error.  The\n> > -\t argument can be used to specify a specific tree-ish\n> > -\t(i.e.  commit, tag or tree) to update the index for the given\n> > -\tpaths before updating the working tree.\n> > +\tswitch branches.  It copies the files matching the pathspecs in\n> I am debating myself if rephrasing \"in \" to \"from\n> \" makes the result clearer to understand.  When we say\n> \"Copy files from T to I and W\", it would be obvious that what does\n> not exist in T will not be copied.\n> \n> I also wonder \"If no-tree-ish is provided\" at the end of this\n> paragraph you have is a bit too far from the above primary point of\n> the description, because you have an unrelated \"In this case,\n> -b/-t...\", in between.  \n> \n> \tThe blobs matching the pathspecs are checked out from the\n> \tindex to the working tree.  Optionally, when is\n> \tgiven, the blobs matching the pathspecs from the \n> \tis copied to the index before that happens.\n> \n> is what I would want to say, but obviously that does not describe\n> what happens in the chronological order, so it is the most clear\n> description for people who understand what is written, but it will\n> take two reading until the reader gets to that stage X-<.\n> \n> Perhaps the unrelated \"In this case, the -b...\" should go first; it\n> is part of \"does *not* switch branches\".  Also even with your patch,\n> it starts with \"X is not Y\" and does not clearly say \"X is Z\".\n> \n> \tWhen or `--patch` ar given, 'git checkout' does\n> \t*not* switch branches (giving the `-b` and `--track` options\n> \twill cause an error, as they are meaningless).  It checks\n> \tout paths out of the (if given) and the index to\n> \tthe to working tree.  When an optional is given\n> \tblobs in the that match are copied to\n> \tthe index.  The blobs that match are then copied\n> \tfrom the index to the working tree, overwriting what is in\n> \t(or missing from) the working tree.\n> \n> May be an improvement (i.e. say what Z is: checking out paths from\n> tree-ish and/or index to the working tree).  By explicitly phrasing\n> that , from which the index is updated, is optional, it is\n> clear that without there is no update to the index.\n> \"missing from\" covers two cases: (1) the user removed the file from\n> the working tree and , e.g. HEAD, has the file, hence\n> removed one is resurrected; (2) the user didn't touch the file and\n> HEAD didn't have it, but by checking out from that has\n> the file, the user added that new file to the set of files the user\n> is working with.\n> \n> Hmm?\n> \n"}]}