{"thread":{"id":"46863","subject":"\"man git-checkout\", man page is inconsistent between SYNOPSIS and details","startedAt":"2017-09-30T09:27:31Z","lastAt":"2017-10-11T05:16:26Z","messageCount":11,"participants":["Robert P. J. Day","Kevin Daudt","Junio C Hamano","Jonathan Nieder"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"329243","messageId":"alpine.LFD.2.21.1709300523190.27819@localhost.localdomain","threadId":"46863","inReplyTo":null,"subject":"\"man git-checkout\", man page is inconsistent between SYNOPSIS and details","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-09-30T09:27:22Z","receivedAt":"2017-09-30T09:27:31Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"\n  just noticed that in \"man git-checkout\", the SYNOPSIS contains the\nline:\n\n  git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]\n\nimplying that <paths> is optional, but further down in the\nDESCRIPTION, one reads:\n\n  git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...\n\nsuggesting that <pathspec> is required.\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"329245","messageId":"20170930143258.GA20886@alpha.vpn.ikke.info","threadId":"46863","inReplyTo":"alpine.LFD.2.21.1709300523190.27819@localhost.localdomain","subject":"Re: \"man git-checkout\", man page is inconsistent between SYNOPSIS and details","fromName":"Kevin Daudt","fromEmail":"me@ikke.info","sentAt":"2017-09-30T14:32:58Z","receivedAt":"2017-09-30T14:33:06Z","isPatch":false,"sender":{"key":"me@ikke.info","avatar":"https://avatars.githubusercontent.com/u/135698?v=4"},"body":"On Sat, Sep 30, 2017 at 05:27:22AM -0400, Robert P. J. Day wrote:\n> \n>   just noticed that in \"man git-checkout\", the SYNOPSIS contains the\n> line:\n> \n>   git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]\n> \n> implying that <paths> is optional, but further down in the\n> DESCRIPTION, one reads:\n> \n>   git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...\n> \n> suggesting that <pathspec> is required.\n> \n\nHello Robert, thank you for this report.\n\nGit checkout has 2 major modes of operating:\n\n1. Checking out branches (and then update your working tree to match that\n  commit.\n2. Checking out 1 or more files from a commit.\n\nThe first four lines of the synopsis match mode nr. 1. The next two\nbelong to mode nr. 2.\n\nThe pathspec in the synopsis line you are quoting is required, because\nthat's how you tell git you want mode nr 2. That's why it's not\nmentioned between [].  The last section under description explains that\nmode. \n\nDo you feel this distinction needs to be made more clear?\n\nKevin.\n"},{"id":"329246","messageId":"alpine.LFD.2.21.1709301100320.2982@localhost.localdomain","threadId":"46863","inReplyTo":"20170930143258.GA20886@alpha.vpn.ikke.info","subject":"Re: \"man git-checkout\", man page is inconsistent between SYNOPSIS and details","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-09-30T15:01:08Z","receivedAt":"2017-09-30T15:01:15Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Sat, 30 Sep 2017, Kevin Daudt wrote:\n\n> On Sat, Sep 30, 2017 at 05:27:22AM -0400, Robert P. J. Day wrote:\n> >\n> >   just noticed that in \"man git-checkout\", the SYNOPSIS contains the\n> > line:\n> >\n> >   git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]\n> >\n> > implying that <paths> is optional, but further down in the\n> > DESCRIPTION, one reads:\n> >\n> >   git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...\n> >\n> > suggesting that <pathspec> is required.\n> >\n>\n> Hello Robert, thank you for this report.\n>\n> Git checkout has 2 major modes of operating:\n>\n> 1. Checking out branches (and then update your working tree to match that\n>   commit.\n> 2. Checking out 1 or more files from a commit.\n>\n> The first four lines of the synopsis match mode nr. 1. The next two\n> belong to mode nr. 2.\n>\n> The pathspec in the synopsis line you are quoting is required, because\n> that's how you tell git you want mode nr 2. That's why it's not\n> mentioned between [].  The last section under description explains that\n> mode.\n>\n> Do you feel this distinction needs to be made more clear?\n\n  hmmmmm ... let me read it again before i answer that.\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"329260","messageId":"alpine.LFD.2.21.1709301800060.7869@localhost.localdomain","threadId":"46863","inReplyTo":"20170930143258.GA20886@alpha.vpn.ikke.info","subject":"Re: \"man git-checkout\", man page is inconsistent between SYNOPSIS and details","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-09-30T22:04:05Z","receivedAt":"2017-09-30T22:04:17Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Sat, 30 Sep 2017, Kevin Daudt wrote:\n\n> On Sat, Sep 30, 2017 at 05:27:22AM -0400, Robert P. J. Day wrote:\n> >\n> >   just noticed that in \"man git-checkout\", the SYNOPSIS contains\n> > the line:\n> >\n> >   git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]\n> >\n> > implying that <paths> is optional, but further down in the\n> > DESCRIPTION, one reads:\n> >\n> >   git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...\n> >\n> > suggesting that <pathspec> is required.\n> >\n>\n> Hello Robert, thank you for this report.\n>\n> Git checkout has 2 major modes of operating:\n>\n> 1. Checking out branches (and then update your working tree to match that\n>   commit.\n> 2. Checking out 1 or more files from a commit.\n>\n> The first four lines of the synopsis match mode nr. 1. The next two\n> belong to mode nr. 2.\n>\n> The pathspec in the synopsis line you are quoting is required,\n> because that's how you tell git you want mode nr 2. That's why it's\n> not mentioned between [].  The last section under description\n> explains that mode.\n>\n> Do you feel this distinction needs to be made more clear?\n\n  upon re-examination, not so much more clear, as simply not\nself-contradictory. just compare the lines in the SYNOPSIS and the\nDESCRIPTION sections:\n\nSYNOPSIS\n       ...\n       git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]\n\nDESCRIPTION\n       ...\n       git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...\n\n  those lines clearly represent the same operating mode -- they are\nidentical in every respect -- but in the first case, paths is\noptional, whereas in the second case, it's mandatory.\n\n  it's simply a matter of the forms not matching between the SYNOPSIS\nand the DESCRIPTION sections. am i making sense?\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"329271","messageId":"xmqqo9prv86l.fsf@gitster.mtv.corp.google.com","threadId":"46863","inReplyTo":"alpine.LFD.2.21.1709301800060.7869@localhost.localdomain","subject":"Re: \"man git-checkout\", man page is inconsistent between SYNOPSIS and details","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-01T03:49:38Z","receivedAt":"2017-10-01T03:49:45Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Robert P. J. Day\" <rpjday@crashcourse.ca> writes:\n\n>   it's simply a matter of the forms not matching between the SYNOPSIS\n> and the DESCRIPTION sections. am i making sense?\n\nI think the whole thing is wrong and the root cause is because the\n(relatively newer) description of the \"--patch\" mode lazily tried to\npiggy-back the description of existing \"check out from the index or\ntree-ish\" mode, ending up in a confusing description.\n\n\"git checkout [<tree-ish>] -- <pathspec>...\" is a way to overwrite\nthe working tree files with what is in the object store.  When you\ngive <tree-ish>, the paths that match the <pathspec> are grabbed\nfrom the tree-ish, added to the index, and overwrites the working\ntree files.  In this mode, you need to have at least one pathspec\nelement on the command line, so <pathspec> is mandatory.  With no\npathspec, if <tree-ish> happens to be a commit-ish, then the\noperation is \"check out the commit, so that we can prepare to make\na new commit as its child\".\n\n\"git checkout -p/--patch [<tree-ish>]\" is quite different.  It can\nbe used without any <pathspec> to pick and choose from all changes\ntreewide, but you can use <pathspec> to limit the changes you need\nto choose from.\n\nSomething like the following may be a good starting point.  As I\ndidn't spend many brain-cycles to come up with a description for the\n\"--patch\" mode, that paragraph needs a total rewrite on top, but I\nthink the structure to separate the normal \"per-path\" checkout mode\nand \"patch\" mode and describe it separately should make it a lot\nclearer to see what is being described.\n\nShort of such a fundamental correction,\n\n\tgit checkout [-p|--patch] [<tree-ish>] -- [<pathspec>...]\n\nwould allow you to give none of -p/--patch/<pathspec>, which is\ntotally a different operation from what is being described in the\ntext.\n\n Documentation/git-checkout.txt | 17 ++++++++++++-----\n 1 file changed, 12 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex d6399c0af8..3d88f703e9 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -13,7 +13,8 @@ SYNOPSIS\n 'git checkout' [-q] [-f] [-m] [--detach] <commit>\n 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...\n-'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]\n+'git checkout' [<tree-ish>] [--] <pathspec>...\n+'git checkout' (-p|--patch) [<tree-ish>] [--] [<paths>...]\n \n DESCRIPTION\n -----------\n@@ -78,10 +79,9 @@ be used to detach HEAD at the tip of the branch (`git checkout\n +\n Omitting <branch> detaches HEAD at the tip of the current branch.\n \n-'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::\n+'git checkout' [<tree-ish>] [--] <pathspec>...::\n \n-\tWhen <paths> or `--patch` are given, 'git checkout' does *not*\n-\tswitch branches.  It updates the named paths in the working tree\n+\tUpdates the named paths in the working tree\n \tfrom the index file or from a named <tree-ish> (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@@ -89,7 +89,7 @@ Omitting <branch> 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 <paths> or `--patch` is used to restore modified or\n+'git checkout' with <paths> 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 <tree-ish> (most often a commit-ish).\n +\n@@ -101,6 +101,13 @@ specific side of the merge can be checked out of the index by\n using `--ours` or `--theirs`.  With `-m`, changes made to the working tree\n file can be discarded to re-create the original conflicted merge result.\n \n+'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::\n+\tThis is similar to the \"check out paths to the working tree\"\n+\tmode described above, but lets you use the interactive\n+\tinterface show the \"diff\" output and choose which hunks to\n+\tuse in the result.\n+\n+\n OPTIONS\n -------\n -q::\n"},{"id":"329278","messageId":"alpine.LFD.2.21.1710010603340.17338@localhost.localdomain","threadId":"46863","inReplyTo":"xmqqo9prv86l.fsf@gitster.mtv.corp.google.com","subject":"Re: \"man git-checkout\", man page is inconsistent between SYNOPSIS and details","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-10-01T10:05:44Z","receivedAt":"2017-10-01T10:05:53Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Sun, 1 Oct 2017, Junio C Hamano wrote:\n\n> \"Robert P. J. Day\" <rpjday@crashcourse.ca> writes:\n>\n> >   it's simply a matter of the forms not matching between the SYNOPSIS\n> > and the DESCRIPTION sections. am i making sense?\n>\n> I think the whole thing is wrong and the root cause is because the\n> (relatively newer) description of the \"--patch\" mode lazily tried to\n> piggy-back the description of existing \"check out from the index or\n> tree-ish\" mode, ending up in a confusing description...\n\n  ... big snip ...\n\nok, i'm going to have to digest all that; pretty sure someone else\nwill need to change the man page to clarify the apparent inconsistency\ni was referring to:\n\n  SYNOPSIS\n       git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]\n  DESCRIPTION\n       git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...\n\nand on that note, i'll get back to proofreading.\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"329356","messageId":"xmqqtvzis87i.fsf@gitster.mtv.corp.google.com","threadId":"46863","inReplyTo":"alpine.LFD.2.21.1710010603340.17338@localhost.localdomain","subject":"Re: \"man git-checkout\", man page is inconsistent between SYNOPSIS and details","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-02T00:29:37Z","receivedAt":"2017-10-02T00:29:49Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Robert P. J. Day\" <rpjday@crashcourse.ca> writes:\n\n> ok, i'm going to have to digest all that; pretty sure someone else\n> will need to change the man page to clarify the apparent inconsistency\n> i was referring to:\n>\n>   SYNOPSIS\n>        git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]\n>   DESCRIPTION\n>        git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...\n\nYes, and a short-version of my answer is that they both are wrong\n;-)\n"},{"id":"330146","messageId":"xmqqefqao1av.fsf_-_@gitster.mtv.corp.google.com","threadId":"46863","inReplyTo":"xmqqtvzis87i.fsf@gitster.mtv.corp.google.com","subject":"[PATCH] checkout doc: clarify command line args for \"checkout paths\" mode","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-11T02:39:36Z","receivedAt":"2017-10-11T02:39:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"There are \"git checkout [-p][<tree-ish>][--][<paths>...]\" in the\nSYNOPSIS section, and \"git checkout [-p][<tree-ish>][--]<paths>...\"\nas the header for the section that explains the \"check out paths\nfrom index/tree-ish\" mode.  It is unclear if we require at least one\npath, or it is entirely optional.\n\nActually, both are wrong.  Without the \"-p(atch)\" option, you must\nhave <pathspec> (otherwise, with a commit that is a <tree-ish>, you\nwould be checking out that commit to build a new history on top of\nit).  With it, it is already clear that you are checking out paths,\nit is optional.  In other words, you cannot omit both.\n\nThe source of the confusion is that -p(atch) is described as if it\nis just another \"optional\" part and its description is lumped\ntogether with the non patch mode, even though the actual end user\nexperience is vastly different.\n\nLet's split the entry into two, and describe the regular mode and\nthe patch mode separately.  This allows us to make it clear that the\nregular mode MUST be given at least one pathspec, that the patch\nmode can be invoked with either '-p' or '--patch' but one of these\nmust be given, and that the pathspec is entirely optional in the\npatch mode.\n\nAlso, revamp the explanation of \"checkout paths\" by removing\nextraneous description at the beginning, that says \"checking out\npaths is not checking out a branch\".  Explaining what it is for and\nwhen the user wants to use it upfront is the most direct way to help\nthe readers.\n\nNoticed-by: Robert P J Day\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n\n * As people burned braincycles discussing this earlier already,\n   let's try to tie the loose end to help future readers of the\n   manual.\n\n Documentation/git-checkout.txt | 32 +++++++++++++++++---------------\n 1 file changed, 17 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex d6399c0af8..8e77a9de49 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -13,7 +13,8 @@ SYNOPSIS\n 'git checkout' [-q] [-f] [-m] [--detach] <commit>\n 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...\n-'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]\n+'git checkout' [<tree-ish>] [--] <pathspec>...\n+'git checkout' (-p|--patch) [<tree-ish>] [--] [<paths>...]\n \n DESCRIPTION\n -----------\n@@ -78,20 +79,13 @@ be used to detach HEAD at the tip of the branch (`git checkout\n +\n Omitting <branch> detaches HEAD at the tip of the current branch.\n \n-'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::\n-\n-\tWhen <paths> 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 <tree-ish> (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<tree-ish> 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-+\n-'git checkout' with <paths> 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 <tree-ish> (most often a commit-ish).\n+'git checkout' [<tree-ish>] [--] <pathspec>...::\n+\tRestore modified or deleted paths in the working tree by\n+\treplacing with their original contents from the index, or\n+\tthe contents from a named <tree-ish> (most often a\n+\tcommit-ish). When a <tree-ish> is given, the paths that\n+\tmatch the <pathspec> are updated both in the index and in\n+\tthe working tree.\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@@ -101,6 +95,14 @@ specific side of the merge can be checked out of the index by\n using `--ours` or `--theirs`.  With `-m`, changes made to the working tree\n file can be discarded to re-create the original conflicted merge result.\n \n+'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::\n+\tThis is similar to the \"check out paths to the working tree\n+\tfrom either the index or from a tree-ish\" mode described\n+\tabove, but lets you use the interactive interface to show\n+\tthe \"diff\" output and choose which hunks to use in the\n+\tresult.\n+\n+\n OPTIONS\n -------\n -q::\n-- \n2.15.0-rc0-211-g82b28a23bd\n\n"},{"id":"330147","messageId":"20171011032240.GZ19555@aiede.mtv.corp.google.com","threadId":"46863","inReplyTo":"xmqqefqao1av.fsf_-_@gitster.mtv.corp.google.com","subject":"Re: [PATCH] checkout doc: clarify command line args for \"checkout paths\" mode","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-10-11T03:22:40Z","receivedAt":"2017-10-11T03:22:50Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nJunio C Hamano wrote:\n\n[...]\n> The source of the confusion is that -p(atch) is described as if it\n> is just another \"optional\" part and its description is lumped\n> together with the non patch mode, even though the actual end user\n> experience is vastly different.\n\nMakes sense.  This should have been done as part of b831deda\n(2010-06-01), but better late than never.\n\nLet's see how the patch goes...\n\n[...]\n>  Documentation/git-checkout.txt | 32 +++++++++++++++++---------------\n>  1 file changed, 17 insertions(+), 15 deletions(-)\n> \n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index d6399c0af8..8e77a9de49 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -13,7 +13,8 @@ SYNOPSIS\n>  'git checkout' [-q] [-f] [-m] [--detach] <commit>\n>  'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n>  'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...\n> +'git checkout' [<tree-ish>] [--] <pathspec>...\n> -'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]\n> +'git checkout' (-p|--patch) [<tree-ish>] [--] [<paths>...]\n\nThis file is inconsistent about <commit> versus <commit-ish>, <paths>\nversus <pathspec>, etc.\n\nOn the subject of <commit> versus <commit-ish>, nowadays <commit> is\nalmost always preferable.  Git commands consistently accept a tag\npointing to a commit where a commit is expected, so emphasizing that\nfeature by calling it a commit-ish only adds distraction.  That's not\nwhat this patch is about, though.\n\nEven for this particular form, the current file is inconsistent about\nwhether to call the arguments '<paths>...' or '<pathspec>...'.\n\"<paths>...\" is even more strange when I think about it for a moment,\nsince it is the plural of the plural of path --- i.e., it implies that\neach argument names multiple paths.  Why does this patch use\n<pathspec> for the --no-patch case and <paths> for the --patch case?\n\n\n>  DESCRIPTION\n>  -----------\n> @@ -78,20 +79,13 @@ be used to detach HEAD at the tip of the branch (`git checkout\n>  +\n>  Omitting <branch> detaches HEAD at the tip of the current branch.\n>  \n> +'git checkout' [<tree-ish>] [--] <pathspec>...::\n> +\tRestore modified or deleted paths in the working tree by\n> +\treplacing with their original contents from the index, or\n> +\tthe contents from a named <tree-ish> (most often a\n\nThis sentence is hard to read:\n\n- \"Restore ... in\" reads oddly, as though this is an art conservation\n  project that takes place in the working tree.  Is the intent that\n  the command will bring the content of those paths back to the\n  working tree, or something else?\n\n- \"replacing with\" reads a little briskly and informally.  In this\n  context, \"replacing them with\" will work better.\n\n- \"their original contents from\" also reads oddly.  \"Their original\n  content from\" would be fine, meaning their original content as\n  obtained from.  I was tempted to read this as \"The original contents\n  of\", but that was a misreading.\n\n- Similarly, \"the contents from\" perhaps should be \"the content of\".\n\nStepping back, what problem is this solving in the original text?\nIt said\n\n\tWhen <paths> or --patch are given, git checkout does *not*\n\tswitch branches. It updates the named paths in the working\n\ttree from the index file or from a named <tree-ish> (most\n\toften a commit). In this case, the -b and --track options are\n\tmeaningless and giving either of them results in an error. The\n\t<tree-ish> 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\nThe \"or --patch\" would have to go, of course.  Is the problem that\nthe description focuses too much on what this form does not do?\nTo fix that, it could say\n\n\tReplace matching paths in the working tree with content\n\tfrom the index or the named tree (most often a commit).  The\n\t<tree-ish> argument can be used to specify a specific tree,\n\tcommit, or tag that will be used to update the entries for\n\tmatching paths in the index before updating the working tree.\n\nOne thing that doesn't tell is what happens to files that are present\nin the worktree but deleted in the index or the named tree.  Does \"git\ncheckout\" delete them?  I remember wishing that it would but don't\nremember whether it does, so it's probably worth mentioning the\nmanpage giving an answer.\n\n... aha, now I see the next paragraph where this text came from.  I\nstill think I like my example text based on the first paragraph\nbetter. :)\n\n[...]\n> @@ -101,6 +95,14 @@ specific side of the merge can be checked out of the index by\n>  using `--ours` or `--theirs`.  With `-m`, changes made to the working tree\n>  file can be discarded to re-create the original conflicted merge result.\n>  \n> +'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::\n> +\tThis is similar to the \"check out paths to the working tree\n> +\tfrom either the index or from a tree-ish\" mode described\n> +\tabove, but lets you use the interactive interface to show\n> +\tthe \"diff\" output and choose which hunks to use in the\n> +\tresult.\n\ns/use/apply/, perhaps.\n\nThe options section explains --patch again.  Maybe that should point\nback to here to avoid some duplication.\n\nThanks,\nJonathan\n"},{"id":"330149","messageId":"xmqqzi8ymg4f.fsf@gitster.mtv.corp.google.com","threadId":"46863","inReplyTo":"20171011032240.GZ19555@aiede.mtv.corp.google.com","subject":"Re: [PATCH] checkout doc: clarify command line args for \"checkout paths\" mode","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-11T05:02:24Z","receivedAt":"2017-10-11T05:02:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder <jrnieder@gmail.com> writes:\n\n>> +'git checkout' [<tree-ish>] [--] <pathspec>...\n>> -'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]\n>> +'git checkout' (-p|--patch) [<tree-ish>] [--] [<paths>...]\n> ...\n> Even for this particular form, the current file is inconsistent about\n> whether to call the arguments '<paths>...' or '<pathspec>...'.\n> \"<paths>...\" is even more strange when I think about it for a moment,\n> since it is the plural of the plural of path --- i.e., it implies that\n> each argument names multiple paths.  Why does this patch use\n> <pathspec> for the --no-patch case and <paths> for the --patch case?\n\nNo particular reason, other than \"the original had <paths>, which\nwas inherited by the line that was minimally modified, while the\nline I typed anew has more preferrable <pathspec>\" ;-)\n\n>>  DESCRIPTION\n>>  -----------\n>> @@ -78,20 +79,13 @@ be used to detach HEAD at the tip of the branch (`git checkout\n>>  +\n>>  Omitting <branch> detaches HEAD at the tip of the current branch.\n>>  \n>> +'git checkout' [<tree-ish>] [--] <pathspec>...::\n>> +\tRestore modified or deleted paths in the working tree by\n>> +\treplacing with their original contents from the index, or\n>> +\tthe contents from a named <tree-ish> (most often a\n>\n> This sentence is hard to read:\n>\n> - \"Restore ... in\" reads oddly, as though this is an art conservation\n>   project that takes place in the working tree.  Is the intent that\n>   the command will bring the content of those paths back to the\n>   working tree, or something else?\n\nThe \"restore\" was taken from the sentence that was buried in the\nparagraph removed by this patch.  I think the original used the\nword, fully intending to evoke \"an art conservation project\"\nconnotation---after all, the user made a mess in the working tree\nand a known-to-be-good copy stored in the index or tree is used to\nrestore the working tree copy.\n\n> To fix that, it could say\n>\n> \tReplace matching paths in the working tree with content\n> \tfrom the index or the named tree (most often a commit).  The\n> \t<tree-ish> argument can be used to specify a specific tree,\n> \tcommit, or tag that will be used to update the entries for\n> \tmatching paths in the index before updating the working tree.\n\nIt could (and it was what my earlier draft said), but I found it\nless clear than necessary.  It does not matter the data goes from\ntree-ish to index and then to the working tree, and a more important\nthing is to say both are updated from the tree-ish, for example.\n\n> ... aha, now I see the next paragraph where this text came from.  I\n> still think I like my example text based on the first paragraph\n> better. :)\n\nAnd I already said the reason why I started from that and improved\nit.\n\n>> @@ -101,6 +95,14 @@ specific side of the merge can be checked out of the index by\n>>  using `--ours` or `--theirs`.  With `-m`, changes made to the working tree\n>>  file can be discarded to re-create the original conflicted merge result.\n>>  \n>> +'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::\n>> +\tThis is similar to the \"check out paths to the working tree\n>> +\tfrom either the index or from a tree-ish\" mode described\n>> +\tabove, but lets you use the interactive interface to show\n>> +\tthe \"diff\" output and choose which hunks to use in the\n>> +\tresult.\n>\n> s/use/apply/, perhaps.\n\nThat might sound technically more accurate, but when we consider\nthat this application is done in reverse, it is probably not such a\ngood idea to say \"apply\" here.  The user chooses which one to use,\nand the way it is \"used\" is by applying the hunk in reverse.\n\"choose the preimage of which hunks to use in the result\" may be\nmore technically accurate, but it is a mouthful.  I dunno.\n\nThe interactive UI explains it by saying\n\n\tDiscard this hunk from worktree?\n\nwhich is probably the easiest explanation.\n\n> The options section explains --patch again.  Maybe that should point\n> back to here to avoid some duplication.\n\nhere is another attempt, this time to avoid \"Restore\" and <paths>...\n\n\n Documentation/git-checkout.txt | 30 ++++++++++++++++--------------\n 1 file changed, 16 insertions(+), 14 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex d6399c0af8..088266e7e9 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -13,7 +13,8 @@ SYNOPSIS\n 'git checkout' [-q] [-f] [-m] [--detach] <commit>\n 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...\n-'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]\n+'git checkout' [<tree-ish>] [--] <pathspec>...\n+'git checkout' (-p|--patch) [<tree-ish>] [--] [<paths>...]\n \n DESCRIPTION\n -----------\n@@ -78,20 +79,13 @@ be used to detach HEAD at the tip of the branch (`git checkout\n +\n Omitting <branch> detaches HEAD at the tip of the current branch.\n \n-'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::\n+'git checkout' [<tree-ish>] [--] <pathspec>...::\n \n-\tWhen <paths> 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 <tree-ish> (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<tree-ish> 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-+\n-'git checkout' with <paths> 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 <tree-ish> (most often a commit-ish).\n+\tOverwrite paths in the working tree by replacing with the\n+\tcontents in the index or in the <tree-ish> (most often a\n+\tcommit).  When a <tree-ish> is given, the paths that\n+\tmatch the <pathspec> are updated both in the index and in\n+\tthe working tree.\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@@ -101,6 +95,14 @@ specific side of the merge can be checked out of the index by\n using `--ours` or `--theirs`.  With `-m`, changes made to the working tree\n file can be discarded to re-create the original conflicted merge result.\n \n+'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::\n+\tThis is similar to the \"check out paths to the working tree\n+\tfrom either the index or from a tree-ish\" mode described\n+\tabove, but lets you use the interactive interface to show\n+\tthe \"diff\" output and choose which hunks to use in the\n+\tresult.  See below for the descriptoin of `--patch` option.\n+\n+\n OPTIONS\n -------\n -q::\n"},{"id":"330150","messageId":"20171011051604.GA140836@aiede.mtv.corp.google.com","threadId":"46863","inReplyTo":"xmqqzi8ymg4f.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] checkout doc: clarify command line args for \"checkout paths\" mode","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-10-11T05:16:04Z","receivedAt":"2017-10-11T05:16:26Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n\n> here is another attempt, this time to avoid \"Restore\" and <paths>...\n>\n>  Documentation/git-checkout.txt | 30 ++++++++++++++++--------------\n>  1 file changed, 16 insertions(+), 14 deletions(-)\n\nThanks.  I find this one easier to read indeed.\n\n[...]\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -13,7 +13,8 @@ SYNOPSIS\n[...]\n> @@ -101,6 +95,14 @@ specific side of the merge can be checked out of the index by\n>  using `--ours` or `--theirs`.  With `-m`, changes made to the working tree\n>  file can be discarded to re-create the original conflicted merge result.\n>  \n> +'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::\n> +\tThis is similar to the \"check out paths to the working tree\n> +\tfrom either the index or from a tree-ish\" mode described\n> +\tabove, but lets you use the interactive interface to show\n> +\tthe \"diff\" output and choose which hunks to use in the\n> +\tresult.  See below for the descriptoin of `--patch` option.\n\nnit: s/descriptoin/description/\n\nWith that tweak,\nReviewed-by: Jonathan Nieder <jrnieder@gmail.com>\n\nThanks.\n"}]}