{"thread":{"id":"26503","subject":"What's the definition of a valid Git symbolic reference?","startedAt":"2011-02-14T20:58:14Z","lastAt":"2011-02-19T13:10:50Z","messageCount":8,"participants":["Emeric Fermas","Kevin Ballard","Tomas Carnecky","Junio C Hamano","Jeff King","Kevin P. Fleming"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"161101","messageId":"AANLkTinsJkzYggMtNrLRv-qNxRncrXSe6A46Z=d8xkw7@mail.gmail.com","threadId":"26503","inReplyTo":null,"subject":"What's the definition of a valid Git symbolic reference?","fromName":"Emeric Fermas","fromEmail":"emeric.fermas@gmail.com","sentAt":"2011-02-14T20:58:14Z","receivedAt":"2011-02-14T20:58:14Z","isPatch":false,"sender":{"key":"emeric.fermas@gmail.com","avatar":"https://gravatar.com/avatar/c3d93659cd1a16d860c12c287d70af221ec792afaaa61799bc06cf011c060be7?d=mp&s=160"},"body":"Hello,\n\nI'm one of the contributors of libgit2 (http://libgit2.github.com/).\nI'm currently working on the handling of refs and I'd like to get a\nbetter understanding of git symbolic references.\n\nIn order to avoid polluting this list with an easy to answer noob\nquestion, I firsty asked this question on stackoverflow\n(http://stackoverflow.com/q/4986000). However, I do not have the\nfeeling that I'm getting some definite \"carved-in-stone\" answers.\nThis explains why I'm posting it here today.\n\nThe following shell code correctly creates a chain of symbolic references\n\n git symbolic-ref \"first\" \"refs/heads/master\"\n git symbolic-ref \"second\" \"first\"\n git symbolic-ref \"nested/third\" \"second\"\n git symbolic-ref \"refs/heads/fourth\" \"nested/third\"\n\nAnd the following shell code correctly resolves the latest created\nsymbolic reference to the tip of master.\n\n git show-ref \"refs/heads/fourth\"\n\n\nNone of these use cases are described in the official documentation\n(git-symbolic-ref doc, git-show-ref doc).\n\nHowever, the following doesn't work\n\n git check-ref-format --print \"first\"\n\n\nSo, my questions are:\n\n - Is it ok to store a symbolic reference within the refs/heads directory ?\n - Is it ok to chain symbolic references ?\n - As check-ref-format fails when being passed \"first\", does this mean\nthat it's not recommended to create a symbolic reference at the same\nlevel than \"HEAD\"? Or maybe this command is not intended to deal with\nsymbolic links ?\n\nMy intent is to get a clear understanding of what is being supported\nand that I'm not working around anything or benefiting from a bug.\n\n\nThanks in advance for any help you could provide me with.\n\nCheers,\nEm.\n\n\nEm.\n"},{"id":"161144","messageId":"F624322D-359A-48ED-A241-622042F77CDA@sb.org","threadId":"26503","inReplyTo":"AANLkTinsJkzYggMtNrLRv-qNxRncrXSe6A46Z=d8xkw7@mail.gmail.com","subject":"Re: What's the definition of a valid Git symbolic reference?","fromName":"Kevin Ballard","fromEmail":"kevin@sb.org","sentAt":"2011-02-15T03:19:40Z","receivedAt":"2011-02-15T03:19:40Z","isPatch":false,"sender":{"key":"kevin@sb.org","avatar":"https://avatars.githubusercontent.com/u/714?v=4"},"body":"On Feb 14, 2011, at 12:58 PM, Emeric Fermas wrote:\n\n> - As check-ref-format fails when being passed \"first\", does this mean\n> that it's not recommended to create a symbolic reference at the same\n> level than \"HEAD\"? Or maybe this command is not intended to deal with\n> symbolic links ?\n\nI don't know about the rest of your question, but check-ref-format\nexplicitly states in the manpage that the refname must have at least\none /, to enforce the presence of a category (such as heads/) in the\nrefname.\n\n-Kevin Ballard\n"},{"id":"161146","messageId":"AANLkTi=FKXqu_psoT+gvyq2c_o8Mej+DgpccecOpQd8H@mail.gmail.com","threadId":"26503","inReplyTo":"F624322D-359A-48ED-A241-622042F77CDA@sb.org","subject":"Re: What's the definition of a valid Git symbolic reference?","fromName":"Emeric Fermas","fromEmail":"emeric.fermas@gmail.com","sentAt":"2011-02-15T03:49:31Z","receivedAt":"2011-02-15T03:49:31Z","isPatch":false,"sender":{"key":"emeric.fermas@gmail.com","avatar":"https://gravatar.com/avatar/c3d93659cd1a16d860c12c287d70af221ec792afaaa61799bc06cf011c060be7?d=mp&s=160"},"body":"Thanks a lot for this answer.\n\nI've also read the man page of check-ref-format. However, there may be\nsome not up-to-date documentation or some \"non guarded against\"\ncommand usage in git.\n\nThis explains the second part of my question (\"Or maybe this command\n(ie. check-ref-format) is not intended to deal with symbolic links\n?\").\n\nAnother possibility would be that only git internal symbolic\nreferences are allowed to live under the \".git\" dir (HEAD, FETCH_HEAD,\n...) and that user defined symrefs should live under refs/. In this\ncase, maybe \"git symbolic-ref\" should also prevent the user from\ncreating a reference which doesn't contains a forward slash.\n\nOnce again, by reading at the code I can understand how those commands\ncurrently work. What I'm trying to achieve is to understand what\nshould be their recommended usage.\n\nOf course, I'll be glad to contribute any code/doc patch once the\n\"voice of the git community\" has spoken :-)\n\n\nEm.\n\n\n\nOn Tue, Feb 15, 2011 at 4:19 AM, Kevin Ballard wrote:\n> On Feb 14, 2011, at 12:58 PM, Emeric Fermas wrote:\n>\n>> - As check-ref-format fails when being passed \"first\", does this mean\n>> that it's not recommended to create a symbolic reference at the same\n>> level than \"HEAD\"? Or maybe this command is not intended to deal with\n>> symbolic links ?\n>\n> I don't know about the rest of your question, but check-ref-format\n> explicitly states in the manpage that the refname must have at least\n> one /, to enforce the presence of a category (such as heads/) in the\n> refname.\n>\n> -Kevin Ballard\n>\n"},{"id":"161147","messageId":"4D5A0901.7080202@dbservice.com","threadId":"26503","inReplyTo":"AANLkTi=FKXqu_psoT+gvyq2c_o8Mej+DgpccecOpQd8H@mail.gmail.com","subject":"Re: What's the definition of a valid Git symbolic reference?","fromName":"Tomas Carnecky","fromEmail":"tom@dbservice.com","sentAt":"2011-02-15T05:02:57Z","receivedAt":"2011-02-15T05:02:57Z","isPatch":false,"sender":{"key":"tom@dbservice.com","avatar":"https://gravatar.com/avatar/900a300bdd1a8bbe086008ad78210bbee2ad2803b7d50a5cba04c1e9404bd6d2?d=mp&s=160"},"body":" On 2/15/11 4:49 AM, Emeric Fermas wrote:\n> Another possibility would be that only git internal symbolic\n> references are allowed to live under the \".git\" dir (HEAD, FETCH_HEAD,\n> ...) and that user defined symrefs should live under refs/. In this\n\nAll refs should live under refs/ (except the special ones like HEAD \netc). It's usually a mistake if someone manages to create one outside of \nrefs/. The plumbing commands allow you to do that, but users usually \nshouldn't use those.\n\ntom\n"},{"id":"161148","messageId":"7vsjvpq0jk.fsf@alter.siamese.dyndns.org","threadId":"26503","inReplyTo":"AANLkTi=FKXqu_psoT+gvyq2c_o8Mej+DgpccecOpQd8H@mail.gmail.com","subject":"Re: What's the definition of a valid Git symbolic reference?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-02-15T06:22:55Z","receivedAt":"2011-02-15T06:22:55Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Emeric Fermas writes:\n\n> Once again, by reading at the code I can understand how those commands\n> currently work. What I'm trying to achieve is to understand what\n> should be their recommended usage.\n\nThere are only two valid kinds of symrefs right now:\n\n - .git/HEAD, pointing at somewhere under refs/heads/ hierarchy;\n\n - .git/refs/remotes//HEAD, pointing at somewhere under\n refs/remotes// hierarchy.\n\nThe code may be prepared to resolve recursive symrefs, symrefs other than\nthe above two kinds, symrefs that point at elsewhere, but all of them are\noutside of the design scope of what the mechanism was intended to support.\nWhat the code do to them (without crashing) is not the design, but simply\nan undefined behaviour.\n\nThis won't change very much if we decide to reorganize the remote tracking\nhierarchies in 1.8.0. The former won't change at all, and the latter will\nstart pointing at refs/remotes//heads hierarchy\ninstead.\n\nI vaguely recall tg abused the symref mechanism to point .git/HEAD at\nfunny locations; it may still be doing so, and if that is the case we\nshould extend the above list to cover that usage.\n"},{"id":"161149","messageId":"AANLkTimaYFbDsAooSuP+BBMA8mJYwupPCgJUj8UGqrQx@mail.gmail.com","threadId":"26503","inReplyTo":"7vsjvpq0jk.fsf@alter.siamese.dyndns.org","subject":"Re: What's the definition of a valid Git symbolic reference?","fromName":"Emeric Fermas","fromEmail":"emeric.fermas@gmail.com","sentAt":"2011-02-15T06:32:11Z","receivedAt":"2011-02-15T06:32:11Z","isPatch":false,"sender":{"key":"emeric.fermas@gmail.com","avatar":"https://gravatar.com/avatar/c3d93659cd1a16d860c12c287d70af221ec792afaaa61799bc06cf011c060be7?d=mp&s=160"},"body":"Thanks a lot for this very clear explanation. All my questions have\nfound an answer.\n\nCheers,\nEm.\n\n\n\nOn Tue, Feb 15, 2011 at 7:22 AM, Junio C Hamano wrote:\n> Emeric Fermas writes:\n>\n>> Once again, by reading at the code I can understand how those commands\n>> currently work. What I'm trying to achieve is to understand what\n>> should be their recommended usage.\n>\n> There are only two valid kinds of symrefs right now:\n>\n>  - .git/HEAD, pointing at somewhere under refs/heads/ hierarchy;\n>\n>  - .git/refs/remotes//HEAD, pointing at somewhere under\n>   refs/remotes// hierarchy.\n>\n> The code may be prepared to resolve recursive symrefs, symrefs other than\n> the above two kinds, symrefs that point at elsewhere, but all of them are\n> outside of the design scope of what the mechanism was intended to support.\n> What the code do to them (without crashing) is not the design, but simply\n> an undefined behaviour.\n>\n> This won't change very much if we decide to reorganize the remote tracking\n> hierarchies in 1.8.0.  The former won't change at all, and the latter will\n> start pointing at refs/remotes//heads hierarchy\n> instead.\n>\n> I vaguely recall tg abused the symref mechanism to point .git/HEAD at\n> funny locations; it may still be doing so, and if that is the case we\n> should extend the above list to cover that usage.\n>\n"},{"id":"161154","messageId":"20110215070939.GB28634@sigill.intra.peff.net","threadId":"26503","inReplyTo":"7vsjvpq0jk.fsf@alter.siamese.dyndns.org","subject":"Re: What's the definition of a valid Git symbolic reference?","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-02-15T07:09:39Z","receivedAt":"2011-02-15T07:09:39Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Feb 14, 2011 at 10:22:55PM -0800, Junio C Hamano wrote:\n\n> Emeric Fermas writes:\n> \n> > Once again, by reading at the code I can understand how those commands\n> > currently work. What I'm trying to achieve is to understand what\n> > should be their recommended usage.\n> \n> There are only two valid kinds of symrefs right now:\n> \n> - .git/HEAD, pointing at somewhere under refs/heads/ hierarchy;\n> \n> - .git/refs/remotes//HEAD, pointing at somewhere under\n> refs/remotes// hierarchy.\n\nNit: the notes merge code uses NOTES_MERGE_REF as a symref to a notes\nref. See the create_symref call in builtin/notes.c.\n\nI don't think that changes your point much, though.\n\n> The code may be prepared to resolve recursive symrefs, symrefs other than\n> the above two kinds, symrefs that point at elsewhere, but all of them are\n> outside of the design scope of what the mechanism was intended to support.\n> What the code do to them (without crashing) is not the design, but simply\n> an undefined behaviour.\n\nI was always under the impression that you could generally use symbolic\nrefs to point wherever you wanted inside the refs hierarchy as a\nreplacement for symlinks (I don't know how the latter would deal with\nref packing, though). But I think that was just my assumption rather\nthan anything that was ever communicated officially.\n\n-Peff\n"},{"id":"161606","messageId":"4D5FC15A.30309@digium.com","threadId":"26503","inReplyTo":"4D5A0901.7080202@dbservice.com","subject":"Re: What's the definition of a valid Git symbolic reference?","fromName":"Kevin P. Fleming","fromEmail":"kpfleming@digium.com","sentAt":"2011-02-19T13:10:50Z","receivedAt":"2011-02-19T13:10:50Z","isPatch":false,"sender":{"key":"kpfleming@digium.com","avatar":null},"body":"On 02/14/2011 11:02 PM, Tomas Carnecky wrote:\n> On 2/15/11 4:49 AM, Emeric Fermas wrote:\n>> Another possibility would be that only git internal symbolic\n>> references are allowed to live under the \".git\" dir (HEAD, FETCH_HEAD,\n>> ...) and that user defined symrefs should live under refs/. In this\n>\n> All refs should live under refs/ (except the special ones like HEAD\n> etc). It's usually a mistake if someone manages to create one outside of\n> refs/. The plumbing commands allow you to do that, but users usually\n> shouldn't use those.\n\nBeing able to manually point HEAD at a ref is actually useful; when I've \ncreated repos that start out with a 'vendor branch', I want to do the \ninitial import into a branch called 'upstream', not 'master'. Using 'git \nsymbolic-ref HEAD refs/heads/upstream' in a brand-new repo allows that \nto happen, and works quite well.\n\nPlease don't take it away :-)\n\n-- \nKevin P. Fleming\nDigium, Inc. | Director of Software Technologies\n445 Jan Davis Drive NW - Huntsville, AL 35806 - USA\nskype: kpfleming | jabber: kfleming@digium.com\nCheck us out at www.digium.com & www.asterisk.org\n"}]}