What's the definition of a valid Git symbolic reference?

Hello,

I'm one of the contributors of libgit2 (http://libgit2.github.com/).
I'm currently working on the handling of refs and I'd like to get a
better understanding of git symbolic references.

In order to avoid polluting this list with an easy to answer noob
question, I firsty asked this question on stackoverflow
(http://stackoverflow.com/q/4986000). However, I do not have the
feeling that I'm getting some definite "carved-in-stone" answers.
This explains why I'm posting it here today.

The following shell code correctly creates a chain of symbolic references

  git symbolic-ref "first" "refs/heads/master"
  git symbolic-ref "second" "first"
  git symbolic-ref "nested/third" "second"
  git symbolic-ref "refs/heads/fourth" "nested/third"

And the following shell code correctly resolves the latest created
symbolic reference to the tip of master.

  git show-ref "refs/heads/fourth"


None of these use cases are described in the official documentation
(git-symbolic-ref doc, git-show-ref doc).

However, the following doesn't work

  git check-ref-format --print "first"


So, my questions are:

 - Is it ok to store a symbolic reference within the refs/heads directory ?
 - Is it ok to chain symbolic references ?
 - As check-ref-format fails when being passed "first", does this mean
that it's not recommended to create a symbolic reference at the same
level than "HEAD"? Or maybe this command is not intended to deal with
symbolic links ?

My intent is to get a clear understanding of what is being supported
and that I'm not working around anything or benefiting from a bug.


Thanks in advance for any help you could provide me with.

Cheers,
Em.


Em.

On Feb 14, 2011, at 12:58 PM, Emeric Fermas wrote:

- As check-ref-format fails when being passed "first", does this mean
that it's not recommended to create a symbolic reference at the same
level than "HEAD"? Or maybe this command is not intended to deal with
symbolic links ?

I don't know about the rest of your question, but check-ref-format
explicitly states in the manpage that the refname must have at least
one /, to enforce the presence of a category (such as heads/) in the
refname.

-Kevin Ballard

Thanks a lot for this answer.

I've also read the man page of check-ref-format. However, there may be
some not up-to-date documentation or some "non guarded against"
command usage in git.

This explains the second part of my question ("Or maybe this command
(ie. check-ref-format) is not intended to deal with symbolic links
?").

Another possibility would be that only git internal symbolic
references are allowed to live under the ".git" dir (HEAD, FETCH_HEAD,
...) and that user defined symrefs should live under refs/. In this
case, maybe "git symbolic-ref" should also prevent the user from
creating a reference which doesn't contains a forward slash.

Once again, by reading at the code I can understand how those commands
currently work. What I'm trying to achieve is to understand what
should be their recommended usage.

Of course, I'll be glad to contribute any code/doc patch once the
"voice of the git community" has spoken :-)


Em.



On Tue, Feb 15, 2011 at 4:19 AM, Kevin Ballard [off-list ref] wrote:

On Feb 14, 2011, at 12:58 PM, Emeric Fermas wrote:

quoted

- As check-ref-format fails when being passed "first", does this mean
that it's not recommended to create a symbolic reference at the same
level than "HEAD"? Or maybe this command is not intended to deal with
symbolic links ?

I don't know about the rest of your question, but check-ref-format
explicitly states in the manpage that the refname must have at least
one /, to enforce the presence of a category (such as heads/) in the
refname.

-Kevin Ballard

  On 2/15/11 4:49 AM, Emeric Fermas wrote:

Another possibility would be that only git internal symbolic
references are allowed to live under the ".git" dir (HEAD, FETCH_HEAD,
...) and that user defined symrefs should live under refs/. In this

All refs should live under refs/ (except the special ones like HEAD 
etc). It's usually a mistake if someone manages to create one outside of 
refs/. The plumbing commands allow you to do that, but users usually 
shouldn't use those.

tom

On 02/14/2011 11:02 PM, Tomas Carnecky wrote:

On 2/15/11 4:49 AM, Emeric Fermas wrote:

quoted

Another possibility would be that only git internal symbolic
references are allowed to live under the ".git" dir (HEAD, FETCH_HEAD,
...) and that user defined symrefs should live under refs/. In this

All refs should live under refs/ (except the special ones like HEAD
etc). It's usually a mistake if someone manages to create one outside of
refs/. The plumbing commands allow you to do that, but users usually
shouldn't use those.

Being able to manually point HEAD at a ref is actually useful; when I've 
created repos that start out with a 'vendor branch', I want to do the 
initial import into a branch called 'upstream', not 'master'. Using 'git 
symbolic-ref HEAD refs/heads/upstream' in a brand-new repo allows that 
to happen, and works quite well.

Please don't take it away :-)

-- 
Kevin P. Fleming
Digium, Inc. | Director of Software Technologies
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
skype: kpfleming | jabber: kfleming@digium.com
Check us out at www.digium.com & www.asterisk.org