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.