{"thread":{"id":"31417","subject":"checkout extra files","startedAt":"2012-09-03T13:42:11Z","lastAt":"2012-09-10T20:34:05Z","messageCount":36,"participants":["Angelo Borsotti","Carlos Martín Nieto","Nguyen Thai Ngoc Duy","Junio C Hamano","Philip Oakley","Matthieu Moy","Jeff King"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"198250","messageId":"CAB9Jk9BvQmFfTq3a+e-7t-66s06jLK4fWuZB+MJHrAtbznBvHw@mail.gmail.com","threadId":"31417","inReplyTo":null,"subject":"checkout extra files","fromName":"Angelo Borsotti","fromEmail":"angelo.borsotti@gmail.com","sentAt":"2012-09-03T13:42:11Z","receivedAt":"2012-09-03T13:42:11Z","isPatch":false,"sender":{"key":"angelo.borsotti@gmail.com","avatar":null},"body":"Hello,\n\nthe man page of git checkout states:\n\ngit checkout [-p|--patch] [] [--] ...\n\nIt updates the named paths in the working tree from the index file or\nfrom a named ...\n\nThis means that for each file denoted by pathspec, git tries to\nrestore it from the tree-ish.\nHowever, it seems that git does more than this: it restores also files\nthat are not denoted\nby pathspec.\nThis sequence of commands shows it:\n\n$ mkdir gittest\n$ cd gittest\n$ git init\nInitialized empty Git repository in d:/gittest/.git/\n$ touch f1\n$ git add f1\n$ git commit commit -m \"first commit\"\n[master (root-commit) 94d882a] first commit\n 0 files changed\n create mode 100644 f1\n$ rm f1\n$ git checkout 94d8 -- *\n$ ls\nf1\n\nNote that the work directory is empty when the checkout is done, and\nthat the checkout restores f1\nin it, a file that is not denoted by the * pathspec.\nI guess that this is the intended behaviour, and that the man page\nshould be updated to tell exactly\nwhat files git restores.\n\n-Angelo Borsotti\n"},{"id":"198252","messageId":"87sjazw6qq.fsf@centaur.cmartin.tk","threadId":"31417","inReplyTo":"CAB9Jk9BvQmFfTq3a+e-7t-66s06jLK4fWuZB+MJHrAtbznBvHw@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Carlos Martín Nieto","fromEmail":"cmn@elego.de","sentAt":"2012-09-03T13:55:41Z","receivedAt":"2012-09-03T13:55:41Z","isPatch":false,"sender":{"key":"cmn@elego.de","avatar":"https://avatars.githubusercontent.com/u/335443?v=4"},"body":"Angelo Borsotti writes:\n\n> Hello,\n>\n> the man page of git checkout states:\n>\n> git checkout [-p|--patch] [] [--] ...\n>\n> It updates the named paths in the working tree from the index file or\n> from a named ...\n>\n> This means that for each file denoted by pathspec, git tries to\n> restore it from the tree-ish.\n> However, it seems that git does more than this: it restores also files\n> that are not denoted\n> by pathspec.\n> This sequence of commands shows it:\n>\n> $ mkdir gittest\n> $ cd gittest\n> $ git init\n> Initialized empty Git repository in d:/gittest/.git/\n> $ touch f1\n> $ git add f1\n> $ git commit commit -m \"first commit\"\n> [master (root-commit) 94d882a] first commit\n> 0 files changed\n> create mode 100644 f1\n> $ rm f1\n> $ git checkout 94d8 -- *\n> $ ls\n> f1\n>\n> Note that the work directory is empty when the checkout is done, and\n> that the checkout restores f1\n> in it, a file that is not denoted by the * pathspec.\n\nThe '*' pathspec refers to every file. There are no files in the current\ndirectory, so your shell can't expand the glob and passes it to git,\nwhich then looks and sees that the glob expands to f1 in the given\ncommit which it then checks out.\n\n cmn\n"},{"id":"198253","messageId":"CACsJy8A6-Ok34QDqgSVavFDBE81UdcK4rLzkHe7P7UO=fXptGw@mail.gmail.com","threadId":"31417","inReplyTo":"CAB9Jk9BvQmFfTq3a+e-7t-66s06jLK4fWuZB+MJHrAtbznBvHw@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Nguyen Thai Ngoc Duy","fromEmail":"pclouds@gmail.com","sentAt":"2012-09-03T13:59:21Z","receivedAt":"2012-09-03T13:59:21Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Mon, Sep 3, 2012 at 8:42 PM, Angelo Borsotti\n wrote:\n> $ git checkout 94d8 -- *\n> $ ls\n> f1\n>\n> Note that the work directory is empty when the checkout is done, and\n> that the checkout restores f1\n> in it, a file that is not denoted by the * pathspec.\n\nI think in this case '*' remains unexpanded by the shell. Which means\nit is still a pathspec to checkout (iow equivalent to \"git checkout\n94d8 -- '*'\"). Checkout in turns matches the pathspec '*' against the\ntree and decides to restore 'fl'.\n\nIt's confusing but I don't think there's much we can do about it.\n\n> I guess that this is the intended behaviour, and that the man page\n> should be updated to tell exactly\n> what files git restores.\n-- \nDuy\n"},{"id":"198257","messageId":"87harfw4bp.fsf@centaur.cmartin.tk","threadId":"31417","inReplyTo":"CAB9Jk9AkFW-fAqOZuhCMgMBdEZwDpe5ZG9Dkse=Wz_x9LvJEPw@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Carlos Martín Nieto","fromEmail":"cmn@elego.de","sentAt":"2012-09-03T14:47:54Z","receivedAt":"2012-09-03T14:47:54Z","isPatch":false,"sender":{"key":"cmn@elego.de","avatar":"https://avatars.githubusercontent.com/u/335443?v=4"},"body":"Angelo Borsotti writes:\n\n[please keep it in the list]\n\n> Hi Carlos,\n>\n> the behavior is quite clear, but the man pages do not describe it properly.\n> The man pages state:\n>\n> \"It updates the named paths in the working tree from the index file or\n> from a named ...\".\n>\n> In my example, the \"named paths in the working tree\" is '*', which\n> denotes\n\nThat grouping is not what it's saying. It doesn't update the files that\nexist in the working tree matching some glob. It updates the files in\nthe working tree from either the index or a treeish. The pathspec\nrefers, as always, to the data source, and '*' matches all files.\n\nIt puts the named paths on to the working tree. Is that clearer?\n\n> no files. So, the man pages are telling that the command updates nothing.\n> The man pages should state that it copies from the index file of the names\n> the files that match the names paths and that are not present\n> in the working tree.\n\nWhether they are missing doesn't make any difference. It updates the\nfiles you tell it from the index/tree. You told it to update all of\nthem.\n\n cmn\n"},{"id":"198265","messageId":"7vsjayew50.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"CACsJy8A6-Ok34QDqgSVavFDBE81UdcK4rLzkHe7P7UO=fXptGw@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-03T19:36:43Z","receivedAt":"2012-09-03T19:36:43Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nguyen Thai Ngoc Duy writes:\n\n> On Mon, Sep 3, 2012 at 8:42 PM, Angelo Borsotti\n> wrote:\n>> $ git checkout 94d8 -- *\n>> $ ls\n>> f1\n>>\n>> Note that the work directory is empty when the checkout is done, and\n>> that the checkout restores f1\n>> in it, a file that is not denoted by the * pathspec.\n>\n> I think in this case '*' remains unexpanded by the shell. Which means\n> it is still a pathspec to checkout (iow equivalent to \"git checkout\n> 94d8 -- '*'\"). Checkout in turns matches the pathspec '*' against the\n> tree and decides to restore 'fl'.\n>\n> It's confusing but I don't think there's much we can do about it.\n\nThe user can, by telling the shell to expand '*' that does not match\nto nothing, though.\n\nIs there anything that is confusing in our documentation? I am not\nlooking for a change to the documentation that protects it from\ngetting misunderstood by deliberately twisted interpretations (such\na change would make the resulting text would harder to read), but I\ndo want to make sure it is not prone to confusion even to a casual\nand careless reader.\n\nFor this particular scenario, I do not see anything offhand that is\nunclear about the behaviour of Git in the documentation, even though\nas you pointed out, if the user is unaware that the shell passes\nglobs unmodified when they do not match, it may lead to a confusion\nlike this. I certainly do not want to do a full \"introduction to\nshell\" in our documentation, but if adding a short sentence or two\nhelps to avoid confusion like this, I do not strongly object to it.\n"},{"id":"198273","messageId":"CACsJy8BDtV95QmWmJ8CEh06FUePOB7KY6nKPR1KCZ7DkMN_MNQ@mail.gmail.com","threadId":"31417","inReplyTo":"7vsjayew50.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Nguyen Thai Ngoc Duy","fromEmail":"pclouds@gmail.com","sentAt":"2012-09-04T01:49:10Z","receivedAt":"2012-09-04T01:49:10Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Tue, Sep 4, 2012 at 2:36 AM, Junio C Hamano wrote:\n>> It's confusing but I don't think there's much we can do about it.\n>\n> The user can, by telling the shell to expand '*' that does not match\n> to nothing, though.\n\nIt works 99% the time, I don't think any users would bother setting\nthat or studying the shell at that detail, until they are surprised.\n\n> Is there anything that is confusing in our documentation? I am not\n> looking for a change to the documentation that protects it from\n> getting misunderstood by deliberately twisted interpretations (such\n> a change would make the resulting text would harder to read), but I\n> do want to make sure it is not prone to confusion even to a casual\n> and careless reader.\n>\n> For this particular scenario, I do not see anything offhand that is\n> unclear about the behaviour of Git in the documentation, even though\n> as you pointed out, if the user is unaware that the shell passes\n> globs unmodified when they do not match, it may lead to a confusion\n> like this. I certainly do not want to do a full \"introduction to\n> shell\" in our documentation, but if adding a short sentence or two\n> helps to avoid confusion like this, I do not strongly object to it.\n\nYeah, one or two sentences about two level expansion might help new\nusers. I'll check that. Maybe in the pathspec definition, then split\nthat part of out glossary-content.txt to be included in pathspec-using\ncommands as a separate pathspec section. Too much?\n-- \nDuy\n"},{"id":"198274","messageId":"87txvev9bw.fsf@centaur.cmartin.tk","threadId":"31417","inReplyTo":"CAB9Jk9BjO+HdxhaGxEyaDoXgGisi0QpuVvsx3dZUnJV1VoKN1g@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Carlos Martín Nieto","fromEmail":"cmn@elego.de","sentAt":"2012-09-04T01:57:23Z","receivedAt":"2012-09-04T01:57:23Z","isPatch":false,"sender":{"key":"cmn@elego.de","avatar":"https://avatars.githubusercontent.com/u/335443?v=4"},"body":"\nKeep it in the list.\n\nAngelo Borsotti writes:\n\n> Hi Carlos,\n>>\n>> That grouping is not what it's saying. It doesn't update the files that\n>> exist in the working tree matching some glob. It updates the files in\n>> the working tree from either the index or a treeish. The pathspec\n>> refers, as always, to the data source, and '*' matches all files.\n>>\n>> It puts the named paths on to the working tree. Is that clearer?\n>>\n> This was mi first understanding, until one day I had in the working directory\n> a file that matched the (the path was '*') and that was NOT in the\n> index or a treeish. The git checkout command tried to copy it and\n> complained that there was no such file to restore.\n\nSo you're saying that you ran\n\n git checkout -- *\n\nand git complained that there was no such file? This is because the\nshell expanded the glob and gave git a list of files.\n\n> Then I thought that it visited the working directory and tried to restore\n> each file it matched and at the end restored also the ones that were not\n> there.\n\nI can't quite parse this. Git will restore whichever files you tell it\nto. If you use an asterisk, then your shell will usually expand it. In\nthe case you posted to the list there were no files, so there was\nnothing to expand it to. Some shells complain in this case by default,\nsome don't and just pass the asterisk to the program and let it figure\nout what to do with it. This was the case in your example. You told git\nto expand all the files it found in that tree-ish.\n\n cmn\n"},{"id":"198275","messageId":"7vd322ebsz.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"CACsJy8BDtV95QmWmJ8CEh06FUePOB7KY6nKPR1KCZ7DkMN_MNQ@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-04T02:55:56Z","receivedAt":"2012-09-04T02:55:56Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nguyen Thai Ngoc Duy writes:\n\n>> For this particular scenario, I do not see anything offhand that is\n>> unclear about the behaviour of Git in the documentation, even though\n>> as you pointed out, if the user is unaware that the shell passes\n>> globs unmodified when they do not match, it may lead to a confusion\n>> like this. I certainly do not want to do a full \"introduction to\n>> shell\" in our documentation, but if adding a short sentence or two\n>> helps to avoid confusion like this, I do not strongly object to it.\n\nPerhaps like this?\n\n Documentation/git-checkout.txt | 12 ++++++++++++\n 1 file changed, 12 insertions(+)\n\ndiff --git i/Documentation/git-checkout.txt w/Documentation/git-checkout.txt\nindex 63a2516..e7272b6 100644\n--- i/Documentation/git-checkout.txt\n+++ w/Documentation/git-checkout.txt\n@@ -360,20 +360,32 @@ mistake, and gets it back from the index.\n $ git checkout master <1>\n $ git checkout master~2 Makefile <2>\n $ rm -f hello.c\n $ git checkout hello.c <3>\n ------------\n +\n <1> switch branch\n <2> take a file out of another commit\n <3> restore hello.c from the index\n +\n+If you want to check out _all_ C source files out of the index,\n+you can say\n++\n+------------\n+$ git checkout -- '*.c'\n+------------\n++\n+Note the quotes around '*.c'. 'hello.c' will also be checked\n+out, even though it is no longer in the working tree, because\n+the pathspec is used to match entries in the index (not in the\n+working tree by your shell).\n++\n If you have an unfortunate branch that is named `hello.c`, this\n step would be confused as an instruction to switch to that branch.\n You should instead write:\n +\n ------------\n $ git checkout -- hello.c\n ------------\n \n . After working in the wrong branch, switching to the correct\n branch would be done using:\n"},{"id":"198277","messageId":"CAB9Jk9BbOJgVNepFittD5fVkFLY24Tf10PVg3MD6E1M3hMyNsQ@mail.gmail.com","threadId":"31417","inReplyTo":"7vd322ebsz.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Angelo Borsotti","fromEmail":"angelo.borsotti@gmail.com","sentAt":"2012-09-04T07:15:42Z","receivedAt":"2012-09-04T07:15:42Z","isPatch":false,"sender":{"key":"angelo.borsotti@gmail.com","avatar":null},"body":"Hi all,\n\nconsider this example:\n\n$ mkdir gittest\n$ cd gittest\n$ git init\nInitialized empty Git repository in d:/gittest/.git/\n$ touch f1\n$ git add f1\n$ git commit commit -m \"first commit\"\n[master (root-commit) e6f935e] first commit\n 0 files changed\n create mode 100644 f1\n$ touch f2\n$ git checkout e6f9 -- *\nerror: pathspec 'f2' did not match any file(s) known to git.\n\nNote the error.\nIt is clear that the set of file names that git checkout is taking is\nthe union of the ones that\nmatch the specified path ('*') in the work directory (gittest) with\nthe ones that match the\npath in the specified commit (e6f9).\nI am not questioning this behavior, but the documentation, which does\nnot describe it:\n\n \"It updates the named paths in the working tree from the index file or\n from a named ...\"\n\nThere are two ways to read this sentence:\n\n 1. \"named paths\" referred to working tree, i.e. the files whose\nnames match the\n paths among all the ones present in the working tree\n 2. \"named paths\" referred to the index or tree-ish, i.e. the\nfiles whose names match\n paths among oll the ones present in the index or tree-ish\n\nIn both cases, nothing tells the user that the matching of the paths\nis done over the union\nof the set of file names of the working tree + ndex or tree-ish.\nIndeed, the first time I have seen the error above I got quite\nconfused because I thought\nthat the checkout would restore the working directory as it was at the\ntime I made the commit,\nwithout bothering about extra files that the directory contained at\nthe moment (and note that\nf2 is not even a tracked one).\nThis behavior is a bit strange, but if it is a hundred percent clearly\ndocumented I can live\nwith it.\n\nI think that knowing precisely what files are involved in this command\nis essential for the user.\n\n-Angelo\n"},{"id":"198287","messageId":"7v8vcqdv8x.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"CAB9Jk9BbOJgVNepFittD5fVkFLY24Tf10PVg3MD6E1M3hMyNsQ@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-04T08:53:34Z","receivedAt":"2012-09-04T08:53:34Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Angelo Borsotti writes:\n\n> \"It updates the named paths in the working tree from the index file or\n> from a named ...\"\n\nIt checks out the contents of the named paths out of either the\nindex or out of the tree-ish and stores that to a file in the\nworking tree. The working tree is not consulted by Git to tell what\npaths the user wants to affect at all, but if you pass fileglob,\nyour shell may consult the working tree to expand it to concrete\npathnames it gives to Git.\n"},{"id":"198290","messageId":"CACsJy8C36eghwEOYqbnd2z5C5KnynWsvwMDa4e2hns3uW243EQ@mail.gmail.com","threadId":"31417","inReplyTo":"7vd322ebsz.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Nguyen Thai Ngoc Duy","fromEmail":"pclouds@gmail.com","sentAt":"2012-09-04T10:14:28Z","receivedAt":"2012-09-04T10:14:28Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Tue, Sep 4, 2012 at 9:55 AM, Junio C Hamano wrote:\n> Perhaps like this?\n\nLooks good. I was going to complain that this patch applied to\ngit-checkout.txt only but I just saw git-add.txt also mentions about\nquoting wildcards. So I'm good.\n\n> diff --git i/Documentation/git-checkout.txt w/Documentation/git-checkout.txt\n> index 63a2516..e7272b6 100644\n> --- i/Documentation/git-checkout.txt\n> +++ w/Documentation/git-checkout.txt\n> @@ -360,20 +360,32 @@ mistake, and gets it back from the index.\n> $ git checkout master <1>\n> $ git checkout master~2 Makefile <2>\n> $ rm -f hello.c\n> $ git checkout hello.c <3>\n> ------------\n> +\n> <1> switch branch\n> <2> take a file out of another commit\n> <3> restore hello.c from the index\n> +\n> +If you want to check out _all_ C source files out of the index,\n> +you can say\n> ++\n> +------------\n> +$ git checkout -- '*.c'\n> +------------\n> ++\n> +Note the quotes around '*.c'. 'hello.c' will also be checked\n> +out, even though it is no longer in the working tree, because\n> +the pathspec is used to match entries in the index (not in the\n> +working tree by your shell).\n> ++\n> If you have an unfortunate branch that is named `hello.c`, this\n> step would be confused as an instruction to switch to that branch.\n> You should instead write:\n> +\n> ------------\n> $ git checkout -- hello.c\n> ------------\n>\n> . After working in the wrong branch, switching to the correct\n> branch would be done using:\n-- \nDuy\n"},{"id":"198303","messageId":"CAB9Jk9D0DHBJEpVq=Z=12TV=+Av0oFVZ0yO1svLh1wyuP+9r1Q@mail.gmail.com","threadId":"31417","inReplyTo":"CACsJy8AUYigHVKjzE-0NT0hnOrQWdufN+COmkk=2Q8L1Rimytw@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Angelo Borsotti","fromEmail":"angelo.borsotti@gmail.com","sentAt":"2012-09-04T13:24:28Z","receivedAt":"2012-09-04T13:24:28Z","isPatch":false,"sender":{"key":"angelo.borsotti@gmail.com","avatar":null},"body":"Hi Duy,\n\nthe semantics of \"git checkout -- '*'\" is quite clear because there is\nno expansion done by the shell. The wildcard is passed to git checkout,\nthat interprets is properly.\n\nThat of \"git checkout -- *\" is the problem when the directory is empty.\nNote that this happens with the shell that is shipped with git (in the\nwindows distro). A note in the documentation could help the user\nto understand this.\n\n-Angelo\n"},{"id":"198304","messageId":"7vpq61dfn9.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"CAB9Jk9BbOJgVNepFittD5fVkFLY24Tf10PVg3MD6E1M3hMyNsQ@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-04T14:30:34Z","receivedAt":"2012-09-04T14:30:34Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Angelo Borsotti writes:\n\n> $ mkdir gittest\n> $ cd gittest\n> $ git init\n> Initialized empty Git repository in d:/gittest/.git/\n\nAt this point, the working tree presumably is empty.\n\n> $ touch f1\n> $ git add f1\n> $ git commit commit -m \"first commit\"\n> [master (root-commit) e6f935e] first commit\n> 0 files changed\n> create mode 100644 f1\n\nNow we have f1 in the working tree in the index, and in the tree of\nthe commit.\n\n> $ touch f2\n\nNow we have f1 and f2 in the working tree.\n\n> $ git checkout e6f9 -- *\n\nThat is the same as \"git checkout e6f935e -- f1 f2\", as the shell\nexpanded \"*\" into \"f1\" and \"f2\".\n\n> error: pathspec 'f2' did not match any file(s) known to git.\n>\n> Note the error.\n\nYes?\n\n> It is clear that the set of file names that git checkout is taking is\n> the union of the ones that\n> match the specified path ('*') in the work directory (gittest) with\n> the ones that match the\n> path in the specified commit (e6f9).\n\nThe command tells git to check out \"f1\" and \"f2\" out of the tree of\ne6f935e, and git found \"f1\" but did not find \"f2\" and reported an\nerror. I do not see a room or need for \"union\" to come into the\npicture to explain what we see in the above transcript.\n"},{"id":"198306","messageId":"7vharddcsw.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"CACsJy8C36eghwEOYqbnd2z5C5KnynWsvwMDa4e2hns3uW243EQ@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-04T15:31:59Z","receivedAt":"2012-09-04T15:31:59Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nguyen Thai Ngoc Duy writes:\n\n> On Tue, Sep 4, 2012 at 9:55 AM, Junio C Hamano wrote:\n>> Perhaps like this?\n>\n> Looks good. I was going to complain that this patch applied to\n> git-checkout.txt only but I just saw git-add.txt also mentions about\n> quoting wildcards. So I'm good.\n\nOk, with a log message like this:\n\n Document file-glob for \"git checkout -- '*.c'\"\n \n Just like we give a similar example in \"git add\" documentation.\n"},{"id":"198308","messageId":"7v8vcpdat2.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"7vpq61dfn9.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-04T16:15:05Z","receivedAt":"2012-09-04T16:15:05Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Now we have f1 and f2 in the working tree.\n>\n>> $ git checkout e6f9 -- *\n>\n> That is the same as \"git checkout e6f935e -- f1 f2\", as the shell\n> expanded \"*\" into \"f1\" and \"f2\".\n>\n>> error: pathspec 'f2' did not match any file(s) known to git.\n>>\n>> Note the error.\n>\n> Yes?\n>\n>> It is clear that the set of file names that git checkout is taking is\n>> the union of the ones that\n>> match the specified path ('*') in the work directory (gittest) with\n>> the ones that match the\n>> path in the specified commit (e6f9).\n>\n> The command tells git to check out \"f1\" and \"f2\" out of the tree of\n> e6f935e, and git found \"f1\" but did not find \"f2\" and reported an\n> error. I do not see a room or need for \"union\" to come into the\n> picture to explain what we see in the above transcript.\n\nActually, I \"kind of sort of\" can see where that \"union\" is coming\nfrom, if I squint my eyes hard enough.\n\nYes, it makes it look like the path affected has some relationship\nbetween two sets of paths:\n\n - set W, which consists of f1 and f2, that is the result of\n matching '*' against working tree files; and\n\n - set T, which consists of f1 (but not f2), that is the result of\n matching '*' against the tree contained in e6f935e\n\nand the intersection of W and T (i.e. f1) is what is checked out.\n\nBut that is not what is happening at all. What goes on is far\nsimpler than that.\n\n - the shell sees '*', matches it against working tree files, to\n obtain \"f1\" and \"f2\";\n\n - the shell tells \"git\" to \"checkout e6f935e -- f1 f2\";\n\n - \"git\" looks into the tree of e6f935e to find paths that match\n \"f1\" and \"f2\".\n\nWhen \"git\" is run by the shell in the last step, it has _no_ clue\nthat the end user typed \"*\" from the shell. It only sees \"f1\" and\n\"f2\" on the command line. There is no \"set T\" to be intersected\nwith \"set W\", so stop thinking in those terms, and you will be fine.\n\nNow the question is, _you_ will be fine, but can the documentation \nbe updated in such a way so that it will help _others_ to also stop\nthinking about \"intersection between set W and set T\"? I do not\nhave a good answer to that.\n"},{"id":"198309","messageId":"7v4nndd98g.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"CAB9Jk9D0DHBJEpVq=Z=12TV=+Av0oFVZ0yO1svLh1wyuP+9r1Q@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-04T16:49:03Z","receivedAt":"2012-09-04T16:49:03Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Angelo Borsotti writes:\n\n> That of \"git checkout -- *\" is the problem when the directory is empty.\n> Note that this happens with the shell that is shipped with git (in the\n> windows distro). A note in the documentation could help the user\n> to understand this.\n\nPassing unmatched glob intact to the program has always been the\nstandard behaviour of shells for decades, and is not specific to\n\"the shell that is shipped with msysgit\", no?\n\nI would imagine that msysgit could be shipped with man pages for\nbash, but I doubt anybody would consult it when hitting this \"I\ntyped * in an empty directory\" situation. In any case, what to\ninclude in the package is something msysgit folks to decide.\n"},{"id":"198337","messageId":"CAB9Jk9DVcG14mS3HaGE4JEY0AwExvjqrnQqzTEZxHLjEQ6UObg@mail.gmail.com","threadId":"31417","inReplyTo":"7v4nndd98g.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Angelo Borsotti","fromEmail":"angelo.borsotti@gmail.com","sentAt":"2012-09-04T19:29:46Z","receivedAt":"2012-09-04T19:29:46Z","isPatch":false,"sender":{"key":"angelo.borsotti@gmail.com","avatar":null},"body":"Hi,\n\nfiguring out what the behavior is by guessing how a command is implemented and\nwhat are its interactions with the shell is a bit hard for the user:\ns/he should instead\nget it from the documentation.\nI tried to figure it out from the examples I have done, and as you\nsee, I did not get it\nquite right.\n\nThe issue here is that the paths must denote filenames that are\npresent in the index\nor tree-ish, so, wildcards are misleading since they would instead be\ninterpreted\nwith respect to the working directory.\nA possible way to make this clear is to warn the user to quote paths\nthat contain\nwildcards. Something like, e.g.:\n\n \"Note that that contain wildcards must be quoted in order to\ndenote files that\n belong to the index or . Otherwise, they are interpreted\nby the shell with\n respect to the current directory, with a result that may depend on\nthe shell.\"\n\n-Angelo\n"},{"id":"198342","messageId":"7vobll8qn2.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"CAB9Jk9DVcG14mS3HaGE4JEY0AwExvjqrnQqzTEZxHLjEQ6UObg@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-04T20:44:17Z","receivedAt":"2012-09-04T20:44:17Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Angelo Borsotti writes:\n\n> The issue here is that the paths must denote filenames that are\n> present in the index\n> or tree-ish, so, wildcards are misleading since they would instead be\n> interpreted\n> with respect to the working directory.\n\nWhen you are talking to a shell (and you almost never directly talk\nto Git), wildcards are always interpreted with respect to the\nworking directory by the shell. And that is not specific to Git.\n\n> A possible way to make this clear is to warn the user to quote paths\n> that contain\n> wildcards. Something like, e.g.:\n>\n> \"Note that that contain wildcards must be quoted in order to\n> denote files that\n> belong to the index or . Otherwise, they are interpreted\n> by the shell with\n> respect to the current directory, with a result that may depend on\n> the shell.\"\n\nPerhaps, if you drop \", with a result...\" from that sentence.\n\nEven though that description is a bit too much on the side of \"shell\nprimer\" than \"git documentation\" for my taste, I could see it may\nhelp some people, so I wouldn't reject such a phrasing out of hand.\n\nLet's see what others feel.\n"},{"id":"198349","messageId":"53AE674D81CD4B9CB013C1DE846240B2@PhilipOakley","threadId":"31417","inReplyTo":"7vobll8qn2.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-09-04T22:53:47Z","receivedAt":"2012-09-04T22:53:47Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \nSent: Tuesday, September 04, 2012 9:44 PM\n> Angelo Borsotti writes:\n>\n>> The issue here is that the paths must denote filenames that are\n>> present in the index\n>> or tree-ish, so, wildcards are misleading since they would instead be\n>> interpreted\n>> with respect to the working directory.\n>\n> When you are talking to a shell (and you almost never directly talk\n> to Git), wildcards are always interpreted with respect to the\n> working directory by the shell. And that is not specific to Git.\n>\n>> A possible way to make this clear is to warn the user to quote paths\n>> that contain\n>> wildcards. Something like, e.g.:\n>>\n>> \"Note that that contain wildcards must be quoted in order \n>> to\n>> denote files that\n>> belong to the index or . Otherwise, they are interpreted\n>> by the shell with\n>> respect to the current directory, with a result that may depend on\n>> the shell.\"\n>\n> Perhaps, if you drop \", with a result...\" from that sentence.\n>\n> Even though that description is a bit too much on the side of \"shell\n> primer\" than \"git documentation\" for my taste, I could see it may\n> help some people, so I wouldn't reject such a phrasing out of hand.\n>\n> Let's see what others feel.\n>\n\nA comment about the need to quote wild cards would certainly be of \nadvantage to many Windows users who won't have used a shell in that way \nbefore.\n\nPlus I suspect that a large fraction of basic unix/linux users will have \nnever really considered the difference between shell expansion and git \nexpansion in this case where there are two diifferent 'file systems', as \ndemonstrated by the initial query. \n"},{"id":"198352","messageId":"7vwr0974ci.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"53AE674D81CD4B9CB013C1DE846240B2@PhilipOakley","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-04T23:31:09Z","receivedAt":"2012-09-04T23:31:09Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> A comment about the need to quote wild cards would certainly be of\n> advantage to many Windows users who won't have used a shell in that\n> way before.\n>\n> Plus I suspect that a large fraction of basic unix/linux users will\n> have never really considered the difference between shell expansion\n> and git expansion in this case where there are two diifferent 'file\n> systems', as demonstrated by the initial query. \n\nOK, anybody wants to do a patch on top of 5635be1 (on 'pu') or on\ncaae319 (which is 5635be1^2), which adds an example of quoted\nfileglob to git-checkout documentation?\n"},{"id":"198552","messageId":"7vk3w5woc4.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"7v8vcpdat2.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-07T20:49:15Z","receivedAt":"2012-09-07T20:49:15Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> But that is not what is happening at all. What goes on is far\n> simpler than that.\n>\n> - the shell sees '*', matches it against working tree files, to\n> obtain \"f1\" and \"f2\";\n>\n> - the shell tells \"git\" to \"checkout e6f935e -- f1 f2\";\n>\n> - \"git\" looks into the tree of e6f935e to find paths that match\n> \"f1\" and \"f2\".\n>\n> When \"git\" is run by the shell in the last step, it has _no_ clue\n> that the end user typed \"*\" from the shell. It only sees \"f1\" and\n> \"f2\" on the command line. There is no \"set T\" to be intersected\n> with \"set W\", so stop thinking in those terms, and you will be fine.\n>\n> Now the question is, _you_ will be fine, but can the documentation \n> be updated in such a way so that it will help _others_ to also stop\n> thinking about \"intersection between set W and set T\"? I do not\n> have a good answer to that.\n\nLet's do this. I do not want a shell tutorial in \"git checkout\"\ndocumentation, but this would fit better in the documentation for\nthe CLI convention.\n\n-- >8 --\ngitcli: contrast wildcard given to shell and to git\n\nPeople who are not used to working with shell may intellectually\nunderstand how the command line argument is massaged by the shell\nbut still have a hard time visualizing the difference between\nletting the shell expand fileglobs and having Git see the fileglob\nto use as a pathspec.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/gitcli.txt | 16 ++++++++++++++++\n 1 file changed, 16 insertions(+)\n\ndiff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\nindex ea17f7a..220621b 100644\n--- c/Documentation/gitcli.txt\n+++ w/Documentation/gitcli.txt\n@@ -38,6 +38,22 @@ arguments. Here are the rules:\n you have to say either `git diff HEAD --` or `git diff -- HEAD` to\n disambiguate.\n \n+ * Many commands allow wildcards in paths, but you need to protect\n+them from getting globbed by the shell. These two mean different things:\n++\n+--------------------------------\n+$ git checkout -- *.c\n+$ git checkout -- \\*.c\n+--------------------------------\n++\n+The former lets your shell expand the fileglob, and you are asking\n+the dot-C files in your working tree to be overwritten with the version\n+in the index. The latter passes the `*.c` to Git, and you are asking\n+the paths in the index that match the pattern to be checked out to your\n+working tree. After running `git add hello.c; rm hello.c`, you will _not_\n+see `hello.c` in your working tree with the former, but with the latter\n+you will.\n+\n When writing a script that is expected to handle random user-input, it is\n a good practice to make it explicit which arguments are which by placing\n disambiguating `--` at appropriate places.\n"},{"id":"198576","messageId":"7va9x0uyz9.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"CAB9Jk9BtZzgi32kxVTbGC7eAjFG41bdae=MaK==sKq=9ohf8_w@mail.gmail.com","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-08T18:54:34Z","receivedAt":"2012-09-08T18:54:34Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Angelo Borsotti writes:\n\n> It makes quite clear that the command accepts wildcards\n> (not expanded by the shell), which was is not clear in the current\n> man page (although one could imagine that could also be a\n> wildcard).\n>\n> P.S. In the man page there is also a \n>\n> \"*git checkout* [-p|--patch] [] [--] ...\n>\n> that should perhaps be a \n\nThat's backwards. Saying as if it means a plain vanilla\npathname is a cause of confusion. The command takes pathspec, which\nis a pattern (see \"git help glossary\"). The places in the text that\nsay may need to be fixed.\n\nIt just happens that you do not realize that you are using pathspec\nwhen you say \"git checkout hello.c\", as the pattern \"hello.c\" only\nmatches the one pathname \"hello.c\".\n"},{"id":"198585","messageId":"3DA7C9D97E19414C81F8D73CB66171DA@PhilipOakley","threadId":"31417","inReplyTo":"7vk3w5woc4.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-09-08T20:40:20Z","receivedAt":"2012-09-08T20:40:20Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \nSent: Friday, September 07, 2012 9:49 PM\n> Junio C Hamano writes:\n>\n>> But that is not what is happening at all. What goes on is far\n>> simpler than that.\n>>\n>> - the shell sees '*', matches it against working tree files, to\n>> obtain \"f1\" and \"f2\";\n>>\n>> - the shell tells \"git\" to \"checkout e6f935e -- f1 f2\";\n>>\n>> - \"git\" looks into the tree of e6f935e to find paths that match\n>> \"f1\" and \"f2\".\n>>\n>> When \"git\" is run by the shell in the last step, it has _no_ clue\n>> that the end user typed \"*\" from the shell. It only sees \"f1\" and\n>> \"f2\" on the command line. There is no \"set T\" to be intersected\n>> with \"set W\", so stop thinking in those terms, and you will be fine.\n>>\n>> Now the question is, _you_ will be fine, but can the documentation\n>> be updated in such a way so that it will help _others_ to also stop\n>> thinking about \"intersection between set W and set T\"? I do not\n>> have a good answer to that.\n>\n> Let's do this. I do not want a shell tutorial in \"git checkout\"\n> documentation, but this would fit better in the documentation for\n> the CLI convention.\n\nThe difficulty with putting it in gitcli is that it is referenced from \nalmost nowhere, so won't provide help to the user.\n\nHaving said that, it would therefore be better to point folk at gitcli \nin a few more places, not just the 'see also' line at the very end of \nthe general 'git' page, and buried within rev-parse.\n\n>\n> -- >8 --\n> gitcli: contrast wildcard given to shell and to git\n>\n> People who are not used to working with shell may intellectually\n> understand how the command line argument is massaged by the shell\n> but still have a hard time visualizing the difference between\n> letting the shell expand fileglobs and having Git see the fileglob\n> to use as a pathspec.\n>\n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/gitcli.txt | 16 ++++++++++++++++\n> 1 file changed, 16 insertions(+)\n>\n> diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\n> index ea17f7a..220621b 100644\n> --- c/Documentation/gitcli.txt\n> +++ w/Documentation/gitcli.txt\n> @@ -38,6 +38,22 @@ arguments. Here are the rules:\n> you have to say either `git diff HEAD --` or `git diff -- HEAD` to\n> disambiguate.\n>\n> + * Many commands allow wildcards in paths, but you need to protect\n> +them from getting globbed by the shell. These two mean different \n> things:\n> ++\n> +--------------------------------\n> +$ git checkout -- *.c\n> +$ git checkout -- \\*.c\n> +--------------------------------\n> ++\n> +The former lets your shell expand the fileglob, and you are asking\n> +the dot-C files in your working tree to be overwritten with the \n> version\n> +in the index. The latter passes the `*.c` to Git, and you are asking\n> +the paths in the index that match the pattern to be checked out to \n> your\n> +working tree. After running `git add hello.c; rm hello.c`, you will \n> _not_\n> +see `hello.c` in your working tree with the former, but with the \n> latter\n> +you will.\n> +\n> When writing a script that is expected to handle random user-input, it \n> is\n> a good practice to make it explicit which arguments are which by \n> placing\n> disambiguating `--` at appropriate places.\n"},{"id":"198586","messageId":"7voblfub16.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"3DA7C9D97E19414C81F8D73CB66171DA@PhilipOakley","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-09T03:31:49Z","receivedAt":"2012-09-09T03:31:49Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> Having said that, it would therefore be better to point folk at gitcli\n> in a few more places, not just the 'see also' line at the very end of\n> the general 'git' page, and buried within rev-parse.\n\nDidn't we update the very early part of git(1) for exactly for that\nreason recently?\n"},{"id":"198628","messageId":"vpq627ntii0.fsf@bauges.imag.fr","threadId":"31417","inReplyTo":"7voblfub16.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2012-09-09T13:48:07Z","receivedAt":"2012-09-09T13:48:07Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Junio C Hamano writes:\n\n> \"Philip Oakley\" writes:\n>\n>> Having said that, it would therefore be better to point folk at gitcli\n>> in a few more places, not just the 'see also' line at the very end of\n>> the general 'git' page, and buried within rev-parse.\n>\n> Didn't we update the very early part of git(1) for exactly for that\n> reason recently?\n\nI don't think many people read git(1) directly, as there are many other\nstarting points to learn Git (official tutorial, user-manual, and tens\nof very good tutorial on the web). On the other hand, reading\ngit- is probably much more common, as it is the only place to\nfind exhaustive documentation about a particular command.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"198635","messageId":"7vd31vqcmd.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"vpq627ntii0.fsf@bauges.imag.fr","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-09T18:23:22Z","receivedAt":"2012-09-09T18:23:22Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> Junio C Hamano writes:\n>\n>> \"Philip Oakley\" writes:\n>>\n>>> Having said that, it would therefore be better to point folk at gitcli\n>>> in a few more places, not just the 'see also' line at the very end of\n>>> the general 'git' page, and buried within rev-parse.\n>>\n>> Didn't we update the very early part of git(1) for exactly for that\n>> reason recently?\n>\n> I don't think many people read git(1) directly, as there are many other\n> starting points to learn Git (official tutorial, user-manual, and tens\n> of very good tutorial on the web).\n\nMany of which is outside what patches made against to my tree would\nbe able to fix. I wonder if we can have some mechanism to easily\nnotify and help the owners of these material to keep them up to\ndate.\n\n> On the other hand, reading git- is probably much more\n> common, as it is the only place to find exhaustive documentation\n> about a particular command.\n\nThat \"people diving into 'git --help ', assuming everything\ncan be learned there\" is a problem within the scope of what we could\ncontrol. For obvious reasons, including \"glossary-contents\" and\n\"gitcli\" at the beginning of documentation for each and every\nsubcommand is not a useful solution, and referring the prerequisite\nreading for them in git(1) was done as the first step to solve that\nissue, and you are essentially saying that it is not enough.\n\nSo what is the right second step?\n"},{"id":"198654","messageId":"498B6DF9C7714C278DC3DC9F3EF4A178@PhilipOakley","threadId":"31417","inReplyTo":"7vd31vqcmd.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2012-09-09T23:25:36Z","receivedAt":"2012-09-09T23:25:36Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Matthieu Moy writes:\n>\n>> Junio C Hamano writes:\n>>\n>>> \"Philip Oakley\" writes:\n>>>\n>>>> Having said that, it would therefore be better to point folk at \n>>>> gitcli\n>>>> in a few more places, not just the 'see also' line at the very end \n>>>> of\n>>>> the general 'git' page, and buried within rev-parse.\n>>>\n>>> Didn't we update the very early part of git(1) for exactly for that\n>>> reason recently?\n\nOops I'd forgotten that specific change.\n\n>>\n>> I don't think many people read git(1) directly, as there are many \n>> other\n>> starting points to learn Git (official tutorial, user-manual, and \n>> tens\n>> of very good tutorial on the web).\n>\n> Many of which is outside what patches made against to my tree would\n> be able to fix. I wonder if we can have some mechanism to easily\n> notify and help the owners of these material to keep them up to\n> date.\n>\n>> On the other hand, reading git- is probably much more\n>> common, as it is the only place to find exhaustive documentation\n>> about a particular command.\n>\n> That \"people diving into 'git --help ', assuming everything\n> can be learned there\" is a problem within the scope of what we could\n> control. For obvious reasons, including \"glossary-contents\" and\n> \"gitcli\" at the beginning of documentation for each and every\n> subcommand is not a useful solution, and referring the prerequisite\n> reading for them in git(1) was done as the first step to solve that\n> issue, and you are essentially saying that it is not enough.\n>\n> So what is the right second step?\n\na simple link to the gitcli page? or, add the into the \ncheckout options list and a link to a suitable place for that, which can \nthen point to the gitcli.\n\n>\nFrom my perspective the majority of the top twenty git commands should, \nwithin each of their help pages, have an in-text link into one or other \nof the various 'guide' style articles, which can then be interconnected \nto each other. This should give the beginner help by directing them away \nfrom the details of a man page for the general issues. That is, \ndistinguish which parts are help for those who aren't sure what they \nneed to know, from the those parts that provide the specfic details for \nthose do know.\n\nI hope to have some documentation patches in the next few days on other \nsmall misunderstandings I've seen/made. Just battling my windows / \nmsysgit / pu set-up at the moment. \n"},{"id":"198655","messageId":"7vwr02pvwh.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"7va9x0uyz9.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-10T00:24:30Z","receivedAt":"2012-09-10T00:24:30Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Angelo Borsotti writes:\n>\n>> It makes quite clear that the command accepts wildcards\n>> (not expanded by the shell), which was is not clear in the current\n>> man page (although one could imagine that could also be a\n>> wildcard).\n>>\n>> P.S. In the man page there is also a \n>>\n>> \"*git checkout* [-p|--patch] [] [--] ...\n>>\n>> that should perhaps be a \n>\n> That's backwards. Saying as if it means a plain vanilla\n> pathname is a cause of confusion. The command takes pathspec, which\n> is a pattern (see \"git help glossary\"). The places in the text that\n> say may need to be fixed.\n>\n> It just happens that you do not realize that you are using pathspec\n> when you say \"git checkout hello.c\", as the pattern \"hello.c\" only\n> matches the one pathname \"hello.c\".\n\nI've read Documentation/git-checkout.txt and looked at the use of\n\"paths\".\n\nthe most of the \"paths\" (if not all) in the description are used as\nshort-hand to mean \"paths that the end user specified by giving a\npathspec without repeating that expression over and over again. And\nit should be clear from the context, especially in places where we\nsay things like \"It updates the named paths\", \"update the index for\nthe given paths\", \"checking out paths from the index\", \"when paths\nare given\" etc.\n\nAs long as readers notice that the command takes on the\ncommand line, and understand has a specific meaning\n(i.e. it is a way to specify set of paths to be manipulated) and\nsemantics, the existing text should be OK. The in synopsis\nsection should be updated to , though.\n"},{"id":"198683","messageId":"20120910161904.GC9435@sigill.intra.peff.net","threadId":"31417","inReplyTo":"7vk3w5woc4.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-09-10T16:19:04Z","receivedAt":"2012-09-10T16:19:04Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Sep 07, 2012 at 01:49:15PM -0700, Junio C Hamano wrote:\n\n> -- >8 --\n> gitcli: contrast wildcard given to shell and to git\n> \n> People who are not used to working with shell may intellectually\n> understand how the command line argument is massaged by the shell\n> but still have a hard time visualizing the difference between\n> letting the shell expand fileglobs and having Git see the fileglob\n> to use as a pathspec.\n\nI think this is an improvement, but...\n\n> diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\n> index ea17f7a..220621b 100644\n> --- c/Documentation/gitcli.txt\n> +++ w/Documentation/gitcli.txt\n> @@ -38,6 +38,22 @@ arguments. Here are the rules:\n> you have to say either `git diff HEAD --` or `git diff -- HEAD` to\n> disambiguate.\n> \n> + * Many commands allow wildcards in paths, but you need to protect\n> +them from getting globbed by the shell. These two mean different things:\n> ++\n> +--------------------------------\n> +$ git checkout -- *.c\n> +$ git checkout -- \\*.c\n> +--------------------------------\n> ++\n> +The former lets your shell expand the fileglob, and you are asking\n> +the dot-C files in your working tree to be overwritten with the version\n> +in the index. The latter passes the `*.c` to Git, and you are asking\n> +the paths in the index that match the pattern to be checked out to your\n> +working tree. After running `git add hello.c; rm hello.c`, you will _not_\n> +see `hello.c` in your working tree with the former, but with the latter\n> +you will.\n> +\n> When writing a script that is expected to handle random user-input, it is\n> a good practice to make it explicit which arguments are which by placing\n> disambiguating `--` at appropriate places.\n\nLook at the paragraph below your addition. It is typographically outside\nof the bulleted list you are adding to, but it really makes sense\ndirectly after the prior two bullet points, which are explicitly about\ndisambiguation between revisions and paths. Your addition splits them\napart.\n\nDoes it make sense to join that final paragraph into what is now the\nthird bullet, and then add your new text (the fourth bullet) after?\n\n-Peff\n"},{"id":"198697","messageId":"7vpq5told4.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"20120910161904.GC9435@sigill.intra.peff.net","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-10T17:09:43Z","receivedAt":"2012-09-10T17:09:43Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n>> When writing a script that is expected to handle random user-input, it is\n>> a good practice to make it explicit which arguments are which by placing\n>> disambiguating `--` at appropriate places.\n>\n> Look at the paragraph below your addition. It is typographically outside\n> of the bulleted list you are adding to, but it really makes sense\n> directly after the prior two bullet points, which are explicitly about\n> disambiguation between revisions and paths. Your addition splits them\n> apart.\n\nYes, I noticed it and thought about different possibilities,\nincluding making the description of glob the first bullet point.\n\n> Does it make sense to join that final paragraph into what is now the\n> third bullet, and then add your new text (the fourth bullet) after?\n\nI am not sure. After re-reading it, I do not think the fileglob\ndiscussion belongs to the existing \"Here are the rules\" list in the\nfirst place. It should probably be the extended description for the\nfirst point (revisions then paths) to explain what kind of \"paths\"\nwe accept there.\n\nI generally consider follow-up paragraphs after bulleted list to be\nenhancements on any of the points in the list, not necessarily\napplying to all of them. The existing structure is:\n\n * point A (revisions and paths)\n * point B (-- can be used to disambiguate)\n * point C (ambiguation leads to an error)\n\n Note that point B and point C taken together imply corollary BC.\n\nSo something like this would be the right thing to do:\n\n * point A\n * point B\n * point C\n\n Note that point B and point C taken together imply corollary BC.\n Also note that point A implies corollary AA.\n\nor even\n\n * point A\n * point B\n * point C\n\n Note that point A implies corollary AA. Also note that point B\n and point C taken together imply corollary BC.\n\n\nSo perhaps something like this squashed in on top of the patch in\nquestion?\n\n Documentation/gitcli.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\nindex c70cd81..4413489 100644\n--- c/Documentation/gitcli.txt\n+++ w/Documentation/gitcli.txt\n@@ -38,9 +38,9 @@ arguments. Here are the rules:\n you have to say either `git diff HEAD --` or `git diff -- HEAD` to\n disambiguate.\n \n- * Many commands allow wildcards in paths, but you need to protect\n- them from getting globbed by the shell. These two mean different\n- things:\n+Many commands allow wildcards in paths (see pathspec in\n+linkgit:gitglossary[7]), but you need to protect them\n+from getting globbed by the shell. These two mean different things:\n +\n --------------------------------\n $ git checkout -- *.c\n"},{"id":"198699","messageId":"20120910171954.GA15583@sigill.intra.peff.net","threadId":"31417","inReplyTo":"7vpq5told4.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-09-10T17:19:55Z","receivedAt":"2012-09-10T17:19:55Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Sep 10, 2012 at 10:09:43AM -0700, Junio C Hamano wrote:\n\n> > Does it make sense to join that final paragraph into what is now the\n> > third bullet, and then add your new text (the fourth bullet) after?\n> \n> I am not sure. After re-reading it, I do not think the fileglob\n> discussion belongs to the existing \"Here are the rules\" list in the\n> first place.\n\nI had a vague feeling that it did not quite belong, too, but I was not\nsure where it should go.\n\n> It should probably be the extended description for the\n> first point (revisions then paths) to explain what kind of \"paths\"\n> we accept there.\n\nI do not think so. That point is about the order of revisions and paths,\nand has nothing to do with the syntax of paths. Really, every element of\nthat list is about handling revisions versus paths. I think this content\ndoes not necessarily go in such a list.\n\n> I generally consider follow-up paragraphs after bulleted list to be\n> enhancements on any of the points in the list, not necessarily\n> applying to all of them.\n\nI would argue the opposite; if it is about a specific point, then put it\nwith the point. Otherwise, you are asking the reader to remember back to\nan earlier point (that they may not even have read; in reference\ndocumentation, the point of a list is often to let readers skip from\nbullet to bullet easily).\n\nIf it is a synthesis of multiple elements in the list, then that makes\nmore sense. And I think that is what you are implying here:\n\n> The existing structure is:\n> \n> * point A (revisions and paths)\n> * point B (-- can be used to disambiguate)\n> * point C (ambiguation leads to an error)\n> \n> Note that point B and point C taken together imply corollary BC.\n\nWhich is fine by me. But inserting a point D that is not related to B,\nC, or BC, only makes it harder to read.\n\n> So perhaps something like this squashed in on top of the patch in\n> question?\n> \n> Documentation/gitcli.txt | 6 +++---\n> 1 file changed, 3 insertions(+), 3 deletions(-)\n> \n> diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\n> index c70cd81..4413489 100644\n> --- c/Documentation/gitcli.txt\n> +++ w/Documentation/gitcli.txt\n> @@ -38,9 +38,9 @@ arguments. Here are the rules:\n> you have to say either `git diff HEAD --` or `git diff -- HEAD` to\n> disambiguate.\n> \n> - * Many commands allow wildcards in paths, but you need to protect\n> - them from getting globbed by the shell. These two mean different\n> - things:\n> +Many commands allow wildcards in paths (see pathspec in\n> +linkgit:gitglossary[7]), but you need to protect them\n> +from getting globbed by the shell. These two mean different things:\n> +\n> --------------------------------\n> $ git checkout -- *.c\n\nI don't think that makes it any better. You went from:\n\n * A\n * B\n * C\n * D\n\n By the way, B and C imply BC.\n\nto:\n\n * A\n * B\n * C\n\n By the way, D.\n\n Also, B and C imply BC.\n\nI think it would make more sense to do:\n\n * A\n * B\n * C\n\n By the way, B and C imply BC.\n\n Also, D.\n\n(where obviously my \"connecting\" phrases do not need to be part of the\ntext, but are meant to illustrate how I am thinking about the\nstructure).\n\n-Peff\n"},{"id":"198712","messageId":"7vhar5oemu.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"20120910171954.GA15583@sigill.intra.peff.net","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-10T19:35:05Z","receivedAt":"2012-09-10T19:35:05Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> I would argue the opposite; if it is about a specific point, then put it\n> with the point. Otherwise, you are asking the reader to remember back to\n> an earlier point (that they may not even have read; in reference\n> documentation, the point of a list is often to let readers skip from\n> bullet to bullet easily).\n\nYou need to follow all the rules when composing your command line.\nYou cannot simply ignore ones that are inconvenient for you and pick\nonly the one you like.\n\nThe second and the third one are related in the \"sides of the same\ncoin\" sense; you either have \"--\" in which case no disambiguation\nchecks are done, or don't in which case your command line may get an\nambiguity error, so in that sense, you could say \"I am writing '--',\nso point C does not apply to me and I skip\". But whether you do or\ndo not say '--', you have to have your revs before pathspecs, so you\ncannot skip point A.\n\nSo I do not think a bullet list is designed to let the readers skip\nand forget (or \"may not even have read\"). If that is the case,\nperhaps we would need to use something else to give the set of rules\nthat apply to the command line here.\n\n> I don't think that makes it any better. You went from:\n>\n> * A\n> * B\n> * C\n> * D\n>\n> By the way, B and C imply BC.\n>\n> to:\n> ...\n> I think it would make more sense to do:\n>\n> * A\n> * B\n> * C\n>\n> By the way, B and C imply BC.\n>\n> Also, D.\n\nI think the following is probably the best.\n\n * A (revs and then paths)\n * B (with \"--\", no dwim is done).\n * C (without \"--\", disambiguation kicks in. By the way, this\n means your script had better avoid this form; make sure you\n use \"--\").\n * D (pathspecs are patterns).\n\nwithout the trailing paragraph, which is meant only for people who\nwrite their script without using \"--\" by mistake, i.e. it only\nbelongs to point C.\n"},{"id":"198714","messageId":"1347306840-14007-1-git-send-email-gitster@pobox.com","threadId":"31417","inReplyTo":"7vhar5oemu.fsf@alter.siamese.dyndns.org","subject":"[PATCH 1/2] gitcli: formatting fix","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-10T19:53:59Z","receivedAt":"2012-09-10T19:53:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"The paragraph to encourage use of \"--\" in scripts belongs to the\nbullet point that describes the behaviour for a command line without\nthe explicit \"--\" disambiguation, not a supporting explanation for\nthe entire bulletted list.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/gitcli.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex ea17f7a..c4edf04 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -37,7 +37,7 @@ arguments. Here are the rules:\n file called HEAD in your work tree, `git diff HEAD` is ambiguous, and\n you have to say either `git diff HEAD --` or `git diff -- HEAD` to\n disambiguate.\n-\n++\n When writing a script that is expected to handle random user-input, it is\n a good practice to make it explicit which arguments are which by placing\n disambiguating `--` at appropriate places.\n-- \n1.7.12.322.g2c7d289\n"},{"id":"198713","messageId":"1347306840-14007-2-git-send-email-gitster@pobox.com","threadId":"31417","inReplyTo":"1347306840-14007-1-git-send-email-gitster@pobox.com","subject":"[PATCH 2/2] gitcli: contrast wildcard given to shell and to git","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-10T19:54:00Z","receivedAt":"2012-09-10T19:54:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"People who are not used to working with shell may intellectually\nunderstand how the command line argument is massaged by the shell\nbut still have a hard time visualizing the difference between\nletting the shell expand fileglobs and having Git see the fileglob\nto use as a pathspec.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/gitcli.txt | 17 +++++++++++++++++\n 1 file changed, 17 insertions(+)\n\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex c4edf04..00b8403 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -42,6 +42,23 @@ When writing a script that is expected to handle random user-input, it is\n a good practice to make it explicit which arguments are which by placing\n disambiguating `--` at appropriate places.\n \n+ * Many commands allow wildcards in paths, but you need to protect\n+ them from getting globbed by the shell. These two mean different\n+ things:\n++\n+--------------------------------\n+$ git checkout -- *.c\n+$ git checkout -- \\*.c\n+--------------------------------\n++\n+The former lets your shell expand the fileglob, and you are asking\n+the dot-C files in your working tree to be overwritten with the version\n+in the index. The latter passes the `*.c` to Git, and you are asking\n+the paths in the index that match the pattern to be checked out to your\n+working tree. After running `git add hello.c; rm hello.c`, you will _not_\n+see `hello.c` in your working tree with the former, but with the latter\n+you will.\n+\n Here are the rules regarding the \"flags\" that you should follow when you are\n scripting git:\n \n-- \n1.7.12.322.g2c7d289\n"},{"id":"198718","messageId":"20120910201115.GB32437@sigill.intra.peff.net","threadId":"31417","inReplyTo":"7vhar5oemu.fsf@alter.siamese.dyndns.org","subject":"Re: checkout extra files","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-09-10T20:11:15Z","receivedAt":"2012-09-10T20:11:15Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Sep 10, 2012 at 12:35:05PM -0700, Junio C Hamano wrote:\n\n> Jeff King writes:\n> \n> > I would argue the opposite; if it is about a specific point, then put it\n> > with the point. Otherwise, you are asking the reader to remember back to\n> > an earlier point (that they may not even have read; in reference\n> > documentation, the point of a list is often to let readers skip from\n> > bullet to bullet easily).\n> \n> You need to follow all the rules when composing your command line.\n> You cannot simply ignore ones that are inconvenient for you and pick\n> only the one you like.\n\nOf course. But note that I said \"reference documentation\". It is quite\nfrequent that you have read it a long time ago, or understand already\nmost of what it is saying, and you are re-reading it again looking for\nrules about a _specific_ element (say, wildcards). You might not have\njust now read the bit about disambiguation, but you do not need to; you\nalready know it, or it might not be relevant to what you are doing.\n\n> The second and the third one are related in the \"sides of the same\n> coin\" sense; you either have \"--\" in which case no disambiguation\n> checks are done, or don't in which case your command line may get an\n> ambiguity error, so in that sense, you could say \"I am writing '--',\n> so point C does not apply to me and I skip\". But whether you do or\n> do not say '--', you have to have your revs before pathspecs, so you\n> cannot skip point A.\n\nI think we need to be realistic about the readers of our documentation.\nSometimes people will sit down and read all the way through, and we need\nthe text to flow and make sense for that case. But just as often, they\nwill be curious about one specific point, and we need to make it as easy\nas possible for them to see when a new point is being made, and when\nthey can stop reading because they have wandered into a new point that\nthey may already know.\n\nWhich is why I think the best thing we can do for such a casual reader\nis make sure that the typography helps group related text together. In\nthis specific example, imagine I am a seasoned Unix user and a new git\nuser. If I were reading about \"--\" and revs versus paths, that would be\nnews to me, because it is about git. When I see the next bullet is about\nquoting \"*\" to pass it through the shell to git, I say \"Of course. That\nis how Unix shells work\" and stop reading. It seems like a disservice to\nthe reader to include more on the \"--\" disambiguation _after_ that\nbullet point.\n\n> So I do not think a bullet list is designed to let the readers skip\n> and forget (or \"may not even have read\"). If that is the case,\n> perhaps we would need to use something else to give the set of rules\n> that apply to the command line here.\n\nI think it is OK here. As a tool for people reading the whole text, I\nthink the list is a bad format, since the elements do not follow a good\nparallel structure (as you said, the second and third are much more\nrelated than the first and fourth).\n\nSo I was tempted to suggest removing the list altogether and turning it\ninto paragraphs.\n\nBut as I said, I think breaking the points with whitespace helps the\ncasual reader using it as a reference. I'm not sure you agree, but maybe\nwhat I've written above will change that. If not, I think I've said as\nmuch as is useful on the matter and I'll stop talking. :)\n\n> I think the following is probably the best.\n> \n> * A (revs and then paths)\n> * B (with \"--\", no dwim is done).\n> * C (without \"--\", disambiguation kicks in. By the way, this\n> means your script had better avoid this form; make sure you\n> use \"--\").\n> * D (pathspecs are patterns).\n> \n> without the trailing paragraph, which is meant only for people who\n> write their script without using \"--\" by mistake, i.e. it only\n> belongs to point C.\n\nHmph. Isn't that what I suggested in my first email? :P\n\nI am fine with the series you sent.\n\n-Peff\n"},{"id":"198724","messageId":"7vr4q9mxc2.fsf@alter.siamese.dyndns.org","threadId":"31417","inReplyTo":"20120910201115.GB32437@sigill.intra.peff.net","subject":"Re: checkout extra files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-09-10T20:34:05Z","receivedAt":"2012-09-10T20:34:05Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> Hmph. Isn't that what I suggested in my first email? :P\n\nUntil I read the current text I did not realize the trailing\nparagraph was to apply only to point C (no \"--\" disambiguates and\nthrows errors) but somehow thought it was covering both point B\n(with \"--\" you are strict) and C, and I didn't think of a good way\nto incorporate it into both. But yes, the final patch ended up to\nbe exactly what you suggested to handle the issue ;-)\n\nThanks.\n"}]}