{"thread":{"id":"32920","subject":"git clone tag shallow","startedAt":"2013-02-17T19:13:30Z","lastAt":"2013-02-18T21:49:24Z","messageCount":6,"participants":["Thibault Kruse","Duy Nguyen","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"209607","messageId":"CAByu6UWEF48XvTmRnVDb2Bqxy1dNdUSXpTuy804215Vgs_KJxw@mail.gmail.com","threadId":"32920","inReplyTo":null,"subject":"git clone tag shallow","fromName":"Thibault Kruse","fromEmail":"tibokruse@googlemail.com","sentAt":"2013-02-17T19:13:30Z","receivedAt":"2013-02-17T19:13:30Z","isPatch":false,"sender":{"key":"tibokruse@googlemail.com","avatar":"https://gravatar.com/avatar/68c46b980bae1554690b4e334db8e5102b7fc25afae6bba2fdf48ce1243cc0c6?d=mp&s=160"},"body":"Hi all,\n\nI notice that using git 1.8.3, I can call\ngit clone repo1 repo2 --branch tagname\nwith a tag, not a branch. Is this going to be a stable and documented feature?\n\ncheers,\n Thibault\n"},{"id":"209644","messageId":"CACsJy8Dso-g7foyJhpY20DNrY11PA8ZZUmP6JXxsiJ_Ggbt_KA@mail.gmail.com","threadId":"32920","inReplyTo":"CAByu6UWEF48XvTmRnVDb2Bqxy1dNdUSXpTuy804215Vgs_KJxw@mail.gmail.com","subject":"Re: git clone tag shallow","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2013-02-18T06:49:52Z","receivedAt":"2013-02-18T06:49:52Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Mon, Feb 18, 2013 at 2:13 AM, Thibault Kruse\n wrote:\n> Hi all,\n>\n> I notice that using git 1.8.3, I can call\n> git clone repo1 repo2 --branch tagname\n> with a tag, not a branch. Is this going to be a stable and documented feature?\n\nThere is a test for --branch=tag in t5601, so I say it's supported. If\nthe document is not clear, patches are welcome.\n-- \nDuy\n"},{"id":"209646","messageId":"CAByu6UWO=kUOvJ_YcPG9bo+XVZ5hSxRQpyEaUMcVxa=sXt_EMw@mail.gmail.com","threadId":"32920","inReplyTo":"CACsJy8Dso-g7foyJhpY20DNrY11PA8ZZUmP6JXxsiJ_Ggbt_KA@mail.gmail.com","subject":"Re: git clone tag shallow","fromName":"Thibault Kruse","fromEmail":"tibokruse@googlemail.com","sentAt":"2013-02-18T08:26:43Z","receivedAt":"2013-02-18T08:26:43Z","isPatch":false,"sender":{"key":"tibokruse@googlemail.com","avatar":"https://gravatar.com/avatar/68c46b980bae1554690b4e334db8e5102b7fc25afae6bba2fdf48ce1243cc0c6?d=mp&s=160"},"body":"Hi Duy,\n\nLooking closer at the rest of the docs, I guess it is consistent, but\nnot terribly helpful.\nThroughout the docs (--help and man), it is never very clear what\nobjects a command\nmay accept or not. here is what I get from it:\n\nWhenever a command description involves \"\" this can, depending\non the command, refer to\n1) a name that, when prepended with \"refs/heads/\", is a valid ref,\n2) a name that, when prepended with \"refs/heads/\" or \"refs/tags\", is a\nvalid ref,\n3) a name that, when prepended with \"refs/[heads|tags]/\", or unique in\n\"refs/remotes/*/\" is a valid ref\n\nNow in the docu I don't see a nice distinction between 1), 2) and 3).\nI could work on a patch if someone\ntells me how to clearly distinguish those cases.\n\nExample for 1)\ngit clone --branch in git 1.7.x\nExample for 2)\ngit clone --branch in git 1.8.x\nExample for 3)\ngit checkout in git 1.8.x\n\nI would like the docs to relate to those e.g. as\n1) git clone --branch \n2) git clone --branch \n3) git checkout \nor something similar, in the future. But I wont create a patch before\nhaving some blessing on the labels to use.\n\n\nOn a related note, what would help my use-case would be an extension\nto git clone such\nthat git clone [--deep] accepted also most other kinds of commit\nreferences, such as SHA-IDs.\n\nSuch that\ngit clone --deep --branch 2h134vjvbc\nwould work. Is there a plan to introduce that as well?\n\ncheers,\n Thibault\n\n\nOn Mon, Feb 18, 2013 at 7:49 AM, Duy Nguyen wrote:\n> On Mon, Feb 18, 2013 at 2:13 AM, Thibault Kruse\n> wrote:\n>> Hi all,\n>>\n>> I notice that using git 1.8.3, I can call\n>> git clone repo1 repo2 --branch tagname\n>> with a tag, not a branch. Is this going to be a stable and documented feature?\n>\n> There is a test for --branch=tag in t5601, so I say it's supported. If\n> the document is not clear, patches are welcome.\n> --\n> Duy\n"},{"id":"209654","messageId":"7vliamascv.fsf@alter.siamese.dyndns.org","threadId":"32920","inReplyTo":"CAByu6UWO=kUOvJ_YcPG9bo+XVZ5hSxRQpyEaUMcVxa=sXt_EMw@mail.gmail.com","subject":"Re: git clone tag shallow","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-02-18T09:22:56Z","receivedAt":"2013-02-18T09:22:56Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thibault Kruse writes:\n\n> Whenever a command description involves \"\" this can, depending\n> on the command, refer to\n> 1) a name that, when prepended with \"refs/heads/\", is a valid ref,\n> 2) a name that, when prepended with \"refs/heads/\" or \"refs/tags\", is a\n> valid ref,\n> 3) a name that, when prepended with \"refs/[heads|tags]/\", or unique in\n> \"refs/remotes/*/\" is a valid ref\n>\n> Now in the docu I don't see a nice distinction between 1), 2) and 3).\n> I could work on a patch if someone\n> tells me how to clearly distinguish those cases.\n\nIt is _very_ true that we do not give strict distinction in many\ncases in the SYNOPSIS section.\n\nIt is clear that (1) should use or even .\n\"git checkout master\" and \"git checkout head/master\" mean very\ndifferent things. The former is the \"git checkout \"\ncase---checkout the named branch and prepare to grow the history of\nthat branch. The latter is \"git checkout \"---detach the\nHEAD at that commit, and even when the committish was named using\nthe name of an existing branch (e.g. \"master^0\" or \"heads/master\"),\nprevent future commits made in that state from affecting the branch.\n\nI am not sure why you meant to treat (2) and (3) differently,\nthough. Care to elaborate?\n\nAnd there is (4) that is not in your list.\n\nA name that is not a local branch name (i.e. no refs/heads/$name)\nand that there is only one ref that matches refs/remotes/*/$name,\nsuch a name is special-cased in \"git checkout $name\". But I do not\nknow it is worth giving a name to such a narrow concept that is only\nused for a single hacky special case. Whatever word you invent and\ncall such a name (perhaps \"remote branch name\"?), you would need to\nrepeat the first three lines of this paragraph in the description to\ndefine that word anyway.\n\nOutside \"git checkout\", we historically deliberately stayed loose in\nan attempt to help beginners by avoiding or , when\nmost people are expected to feed branch names to the command and\nused . I am not sure if it is a good idea to break such a\nwhite lie just to be technically more correct in the first place.\nIt needs to be done with care to avoid making the resulting text\nharder to approach for beginners.\n"},{"id":"209668","messageId":"CAByu6UVfArRXGLTKgM=nw0fzij1urcVdzxx6xdoHihODD-LtRA@mail.gmail.com","threadId":"32920","inReplyTo":"7vliamascv.fsf@alter.siamese.dyndns.org","subject":"Re: git clone tag shallow","fromName":"Thibault Kruse","fromEmail":"tibokruse@googlemail.com","sentAt":"2013-02-18T10:11:25Z","receivedAt":"2013-02-18T10:11:25Z","isPatch":false,"sender":{"key":"tibokruse@googlemail.com","avatar":"https://gravatar.com/avatar/68c46b980bae1554690b4e334db8e5102b7fc25afae6bba2fdf48ce1243cc0c6?d=mp&s=160"},"body":"Hi Junio,\n\nOn Mon, Feb 18, 2013 at 10:22 AM, Junio C Hamano wrote:\n> Thibault Kruse writes:\n>\n>> Whenever a command description involves \"\" this can, depending\n>> on the command, refer to\n>> 1) a name that, when prepended with \"refs/heads/\", is a valid ref,\n>> 2) a name that, when prepended with \"refs/heads/\" or \"refs/tags\", is a\n>> valid ref,\n>> 3) a name that, when prepended with \"refs/[heads|tags]/\", or unique in\n>> \"refs/remotes/*/\" is a valid ref\n>>\n>> Now in the docu I don't see a nice distinction between 1), 2) and 3).\n>> I could work on a patch if someone\n>> tells me how to clearly distinguish those cases.\n>\n> It is _very_ true that we do not give strict distinction in many\n> cases in the SYNOPSIS section.\n>\n> It is clear that (1) should use or even .\n> \"git checkout master\" and \"git checkout head/master\" mean very\n> different things. The former is the \"git checkout \"\n> case---checkout the named branch and prepare to grow the history of\n> that branch. The latter is \"git checkout \"---detach the\n> HEAD at that commit, and even when the committish was named using\n> the name of an existing branch (e.g. \"master^0\" or \"heads/master\"),\n> prevent future commits made in that state from affecting the branch.\n>\n> I am not sure why you meant to treat (2) and (3) differently,\n> though. Care to elaborate?\n\nAs in my example, git clone --branch does not accept all of (3).\n\nI now see that indeed the options section for git clone --branch has\nbeen changed to inlude the information that tags are also allowed, so that's\nin order.\n\n> Outside \"git checkout\", we historically deliberately stayed loose in\n> an attempt to help beginners by avoiding or , when\n> most people are expected to feed branch names to the command and\n> used . I am not sure if it is a good idea to break such a\n> white lie just to be technically more correct in the first place.\n\nThat's fair enough, I guess, I am not sure either. If I understand you\nright, the Synopsis and\ndescription are supposed to explain the non-hackish usage of commands,\nwhereas documentation after the OPTIONS headline is supposed to be\nmore of a complete description. Hence e.g. the synopsis of git-checkout\ndoes not mention the --t,--track,--no-track options, and takes a liberal\napproach to option syntaxes (listing '[-p|--patch]', but only '-m',\nbut not '[-m|--merge]'),\nsimilar git-clone help does not mention the '--branch' option in the synopsis\nfor that reason, I guess. Do I get this right?\n\nDoes this also extend to the (bash) tab completion?\nE.g. hitting tab after \"git clone --\", offers me (Ubuntu precise, git 1.7.9.5):\n--bare --local --no-checkout --origin\n--reference --template=\n--depth --mirror --no-hardlinks --quiet\n--shared --upload-pack\n\nmissing:\n---recursive --recurse-submodules (--[no-]single-branch)\n--separate-git-dir --verbose --progress --branch\n\nIs this also intentional?\n\ncheers,\n Thibault\n"},{"id":"209742","messageId":"7vobfh9tsr.fsf@alter.siamese.dyndns.org","threadId":"32920","inReplyTo":"CAByu6UVfArRXGLTKgM=nw0fzij1urcVdzxx6xdoHihODD-LtRA@mail.gmail.com","subject":"Re: git clone tag shallow","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-02-18T21:49:24Z","receivedAt":"2013-02-18T21:49:24Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thibault Kruse writes:\n\n>> I am not sure why you meant to treat (2) and (3) differently,\n>> though. Care to elaborate?\n>\n> As in my example, git clone --branch does not accept all of (3).\n\nThat is a prime example of outside \"checkout\" we give a white lie to\nshow the most common to help beginners, I think.\n\n> That's fair enough, I guess, I am not sure either. If I understand you\n> right, the Synopsis and\n> description are supposed to explain the non-hackish usage of commands,\n> whereas documentation after the OPTIONS headline is supposed to be\n> more of a complete description.\n\nIt would go more like\n\n\tSYNOPSIS\n \tgit foo \n\tDESCRIPTION\n \t\"git foo\" distims doshes in .\n\tARGUMENTS\n\t\t* : the branch to distim doshes in.\n\t\t While it is most common to name a branch, you\n can give any to it.\n\nif and only if use is is the most common and using\narbitrary commit is a rare case. In other cases, we would be better\nto say on the SYNOPSIS part. That commonness/rareness\nis a case-by-case matter, I would think.\n"}]}