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

[Emeric Fermas <emeric.fermas@gmail.com>]

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.