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

[Patrick Steinhardt <ps@pks.im>]

On Sun, Oct 13, 2024 at 09:57:23PM +0200, Kristoffer Haugsbakk wrote:
> 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