24

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.

Kirk Broadhurst
  • 27,836
  • 16
  • 104
  • 169
nulltoken
  • 64,429
  • 20
  • 138
  • 130

3 Answers3

20

I've eventually posted this question to the git development mailing list.

Junio C Hamano, the lead git maintainer (+8700 commits) provided me with the following answers.

There are only two valid kinds of symrefs right now:

  • .git/HEAD, pointing at somewhere under refs/heads/ hierarchy;

  • .git/refs/remotes/{some remote name}/HEAD, pointing at somewhere under refs/remotes/{the same remote name}/ hierarchy.

The code may be prepared to resolve recursive symrefs, symrefs other than the above two kinds, symrefs that point at elsewhere, but all of them are outside of the design scope of what the mechanism was intended to support. What the code do to them (without crashing) is not the design, but simply an undefined behaviour.

This won't change very much if we decide to reorganize the remote tracking hierarchies in 1.8.0. The former won't change at all, and the latter will start pointing at refs/remotes/{the same remote name}/heads hierarchy instead.

I vaguely recall tg abused the symref mechanism to point .git/HEAD at funny locations; it may still be doing so, and if that is the case we should extend the above list to cover that usage.

nulltoken
  • 64,429
  • 20
  • 138
  • 130
  • link to said mailing list thread: http://git.661346.n2.nabble.com/What-s-the-definition-of-a-valid-Git-symbolic-reference-tt6025154.html#a6026446 – Magicmaaan Jan 23 '17 at 13:02
  • It's interesting, we are at version 2.28 or so, but the remote hierarchy seems to not have been changed. Maybe the idea had been dropped. – Martini Bianco Oct 15 '20 at 09:54
3

Normally, symrefs live under refs/ — at least, this is what the git suite does (for example when using git filter-tree, you get refs/original/...). Some tools may choose to ignore refs that do not have the refs/ prefix.

$ git symbolic-ref refs/first refs/heads/master
$ git check-ref-format --print refs/first
refs/first
user611775
  • 1,323
  • 7
  • 11
  • So, your understanding is that I'm benefiting from a loophole ? Have you got any idea about the symref chaining ? Is it valid or am I also exploiting a "non-guarded-against" usage ? – nulltoken Feb 13 '11 at 20:48
  • "Normally" - except for the one symref that everyone has, `HEAD`. – Cascabel Feb 13 '11 at 23:16
  • 1
    Refs are possible outside .git/refs/ - you can call `git log` on them - such as FETCH_HEAD, HEAD, ORIG_HEAD, RENAMED-REF. But gitk won't show them except HEAD, for example. – user611775 Feb 14 '11 at 22:10
  • the git source explicitly allows chained symrefs, up to a depth of 5 (4 including `HEAD`) – iCodeSometime Mar 05 '19 at 16:49
2

It would be desirable that symbolic links can be used more transparently and can be pushed as well. They could be a powerful tool for new workflows. Currently, if I create a symbolic link and then push is the server will have the hash not the link in the corresponding reference.

user3622450
  • 135
  • 1
  • 3