threads / discuss / 62328

What’s the intended/reasonable usage patterns for symrefs?

Subject: What’s the intended/reasonable usage patterns for symrefs?

## tl;dr

5 messages between Oct 13, 2024 and Jun 20, 2025.

replies: 4people: 3as markdown or json

Kristoffer Haugsbakk· Oct 13, 2024, 19:57 UTC · lore
This was posted in 2011:
“What's the definition of a valid Git symbolic reference?”
https://lore.kernel.org/git/AANLkTinsJkzYggMtNrLRv-qNxRncrXSe6A46Z=d8xkw7@mail.gmail.com/
And the answer said that:
Show 27 quoted lines
> Emeric Fermas <emeric.fermas@gmail.com> writes:
>
> >  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.
>
> 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.
https://lore.kernel.org/git/7vsjvpq0jk.fsf@alter.siamese.dyndns.org/

This was motivated by a StackOverflow[1] question/thread. Which should maybe get an update if this thread reveals some new information.

🔗 1: https://stackoverflow.com/a/5000668/1725151
This seems overly restrictive for this day and age though? No?
I only know that
1. Symref manipulation is a plumbing command
2. That means that you can do weird stuff without getting slapped on the
   wrist
3. The plumbing man pages sometimes feel inert, like they either don’t
   fit into a greater whole or they don’t want to tell you
   (git-rev-list(1) is apparently the plumbing dual to git-log(1) but
   all I can see is some references at the bottom like “see also the
   porcelain git-log(1)” (in a 1200 line page)

In conclusion: I might end up doing things which I’m not really supposed to. Because these commands are unopinionated.

What I’ve done lately that might give *weird* results:
• Create a one-level symref (one-level “because it’s short”)
• Then you might get “ambigious” warnings if some branch ref has the
  same name
But what seems fine so far:
• Create a `refs/heads/<symref>` which points to a remote-tracking branch
This is so that I can
• Have a short name for some long-living branches (sometimes they live
  longer than we would have planned for)
• So that I can rebase and set upstream on the remote-tracking branch.
  That way I don’t need to maintain a branch which just follows the
  remote-tracking one

Is this okay? And what can you reasonably do in general terms with symrefs?

Just as an example of something that is probably not fine: I’ve read that symrefs are dereferenced only to a depth of four. And then you don’t want to create some contraption which relies on many levels of dereferencing.

Thanks!
-- 
Kristoffer
Patrick Steinhardt· Oct 14, 2024, 10:16 UTC · re: Kristoffer Haugsbakk · lore

Re: What’s the intended/reasonable usage patterns for symrefs?

On Sun, Oct 13, 2024 at 09:57:23PM +0200, Kristoffer Haugsbakk wrote:
Show 44 quoted lines
> This was posted in 2011:
> 
> “What's the definition of a valid Git symbolic reference?”
> 
> https://lore.kernel.org/git/AANLkTinsJkzYggMtNrLRv-qNxRncrXSe6A46Z=d8xkw7@mail.gmail.com/
> 
> And the answer said that:
> 
> > Emeric Fermas <emeric.fermas@gmail.com> writes:
> >
> > >  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.
> >
> > 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.
> 
> https://lore.kernel.org/git/7vsjvpq0jk.fsf@alter.siamese.dyndns.org/
> 
> This was motivated by a StackOverflow[1] question/thread.  Which should
> maybe get an update if this thread reveals some new information.
> 
> 🔗 1: https://stackoverflow.com/a/5000668/1725151
> 
> This seems overly restrictive for this day and age though? No?

There at least is no technical reason to restrict this from the ref backend's point of view. Neither the "files" nor the "reftable" backend enforce any restrictions except the restrictions we have in place for any other reference: a ref is either a root ref, a pseudoref or it must start with "refs/".

Now the only reason why I'd say that you maybe shouldn't create weird symrefs is that tooling isn't prepared to handle them. But that is not sufficient reason for me to say that you mustn't create them.

[snip]
> Is this okay?  And what can you reasonably do in general terms with
> symrefs?

From my point of view it is. As said, though, depending on what tooling you run in those repos you may run into bugs if that tooling does not expect symrefs at all. It's basically the exact same issue as you have with symbolic links: they work mostly fine, until they don't because something isn't prepared for them.

> Just as an example of something that is probably not fine: I’ve read
> that symrefs are dereferenced only to a depth of four.  And then you
> don’t want to create some contraption which relies on many levels of
> dereferencing.

SYMREF_MAXDEPTH is defined as 5, so yes, there is a limit to the level of recursiveness we allow.

Patrick
Kristoffer Haugsbakk· Oct 16, 2024, 17:23 UTC · re: Patrick Steinhardt · lore

Re: What’s the intended/reasonable usage patterns for symrefs?

On Mon, Oct 14, 2024, at 12:16, Patrick Steinhardt wrote:
Show 13 quoted lines
> On Sun, Oct 13, 2024 at 09:57:23PM +0200, Kristoffer Haugsbakk wrote:
>> […]
>> This seems overly restrictive for this day and age though? No?
>
> There at least is no technical reason to restrict this from the ref
> backend's point of view. Neither the "files" nor the "reftable" backend
> enforce any restrictions except the restrictions we have in place for
> any other reference: a ref is either a root ref, a pseudoref or it must
> start with "refs/".
>
> Now the only reason why I'd say that you maybe shouldn't create weird
> symrefs is that tooling isn't prepared to handle them. But that is not
> sufficient reason for me to say that you mustn't create them.
Thanks.  This makes sense. :)
❦
I discovered/re-discovered a pitfall with the following approach:
> Create a `refs/heads/<symref>` which points to a remote-tracking
> branch

Again, so tempting to do for me because you get a shorthand via `refs/heads`. And this is indeed fine for read-only operations (effectively).

But don’t be careless and do something like commit while checked out here. Because you are checked out on an ostensibly “proper branch” (not detached HEAD) and the remote-tracking branch will move forward with a commit.

So I’ve gone back to using one-level (root-level) symrefs with all-capital names. Because git-symbolic-ref(1) allows that and I haven’t gotten any weird warnings from it. (I would presumably get warnings if I then defined a ref named e.g. `refs/heads/M` if `M` was my top-level symref.)

Kristoffer Haugsbakk· Nov 4, 2024, 10:45 UTC · re: Kristoffer Haugsbakk · lore

Re: What’s the intended/reasonable usage patterns for symrefs?

On Wed, Oct 16, 2024, at 19:23, Kristoffer Haugsbakk wrote:
Show 26 quoted lines
> On Mon, Oct 14, 2024, at 12:16, Patrick Steinhardt wrote:
> > […]
>
> Thanks.  This makes sense. :)
>
> ❦
>
> I discovered/re-discovered a pitfall with the following approach:
>
>> Create a `refs/heads/<symref>` which points to a remote-tracking
>> branch
>
> Again, so tempting to do for me because you get a shorthand via
> `refs/heads`.  And this is indeed fine for read-only operations
> (effectively).
>
> But don’t be careless and do something like commit while checked out
> here.  Because you are checked out on an ostensibly “proper branch” (not
> detached HEAD) and the remote-tracking branch will move forward with a
> commit.
>
> So I’ve gone back to using one-level (root-level) symrefs with
> all-capital names.  Because git-symbolic-ref(1) allows that and I
> haven’t gotten any weird warnings from it.  (I would presumably get
> warnings if I then defined a ref named e.g. `refs/heads/M` if `M` was my
> top-level symref.)
Another newbie mistake.

I used e.g. `H` (root level). But then I was in a worktree and discovered that these root-level refs are per worktree.

But this works across worktress:

``` git symbolic-ref refs/H HEAD ```

(Or `refs/h`)
-- 
Kristoffer Haugsbakk
Kristoffer Haugsbakk· Jun 20, 2025, 15:29 UTC · re: Kristoffer Haugsbakk · lore

Re: What’s the intended/reasonable usage patterns for symrefs?

On Mon, Nov 4, 2024, at 11:45, Kristoffer Haugsbakk wrote:
Show 40 quoted lines
> On Wed, Oct 16, 2024, at 19:23, Kristoffer Haugsbakk wrote:
>> On Mon, Oct 14, 2024, at 12:16, Patrick Steinhardt wrote:
>> > […]
>>
>> Thanks.  This makes sense. :)
>>
>> ❦
>>
>> I discovered/re-discovered a pitfall with the following approach:
>>
>>> Create a `refs/heads/<symref>` which points to a remote-tracking
>>> branch
>>
>> Again, so tempting to do for me because you get a shorthand via
>> `refs/heads`.  And this is indeed fine for read-only operations
>> (effectively).
>>
>> But don’t be careless and do something like commit while checked out
>> here.  Because you are checked out on an ostensibly “proper branch” (not
>> detached HEAD) and the remote-tracking branch will move forward with a
>> commit.
>>
>> So I’ve gone back to using one-level (root-level) symrefs with
>> all-capital names.  Because git-symbolic-ref(1) allows that and I
>> haven’t gotten any weird warnings from it.  (I would presumably get
>> warnings if I then defined a ref named e.g. `refs/heads/M` if `M` was my
>> top-level symref.)
>
> Another newbie mistake.
>
> I used e.g. `H` (root level).  But then I was in a worktree and
> discovered that these root-level refs are per worktree.
>
> But this works across worktress:
>
> ```
> git symbolic-ref refs/H HEAD
> ```
>
> (Or `refs/h`)
I’ve been using some shorthands for over half a year now:

``` git symbolic-ref refs/C refs/heads/<longer branch name> git symbolic-ref refs/O refs/remotes/origin/<longer branch name> ```

E.g. I find the latter convenient for referring to some long-living branch that is also long-named. I use the remote-tracking branch directly to use as the upstream-tracking ref and to rebase on top of.

I haven’t had any problems yet.
-- 
Kristoffer Haugsbakk

← back to recent threads