Can a symbolic-ref in git reference the current upstream branch?

Question

I can do this with git:

echo "ref: HEAD" > .git/h

and then I can use “h” in place of head in every place that accepts a commit-ish, e.g. git log h or git show-branch h origin/master.

Is it possible to do the same for the upstream branch of HEAD? It is represented by @{u} (or HEAD@{upstream} in the long form), say git log @{u}, git rebase --onto @{u} or git show-branch HEAD @{u}.

Trying to put any of these as a symbolic-ref like this:

echo "ref: HEAD@{upstream}" > .git/u

will result in an error:

$ git show u
warning: ignoring dangling symref u.
warning: ignoring dangling symref u.
fatal: ambiguous argument 'u': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'

Answer 1

Don't do that; use git symbolic-ref to create symbolic references. For instance, git symbolic-ref u HEAD is the "correct" command to create .git/u as a symbolic reference to HEAD (which is in turn a symbolic reference to the current branch, unless HEAD is detached).

As things work now, though, you can't make a symbolic reference point to something that requires additional parsing. This means you can't get what you want: specifically, no variant of HEAD@{upstream} will work here. The content of a symbolic ref has to be the name of another reference, so that git can resolve it easily, without any of the fancy "peeling" process that git rev-parse performs on user-supplied names (including names that are themselves indirect, like HEAD). This is probably because symbolic references are something of an orphan step-child, as the saying goes: they've had enough work put in to them to make them work for HEAD to contain a branch-name, but little additional work.

Answer 2

Not only using git symbolic-ref is preferable (as detailed in torek's answer), its code has been optimized with Git 2.36 (Q2 2022):

See commit 0a7b387, commit 1553f5e, commit cd475b3, commit 8e55634, commit 4de6562 (01 Mar 2022) by Patrick Steinhardt (pks-t).
See commit 3436340 (01 Mar 2022) by Junio C Hamano (gitster).
^{(Merged by Junio C Hamano -- gitster -- in commit 6969ac6, 16 Mar 2022)}

refs: add ability for backends to special-case reading of symbolic refs

^{Signed-off-by: Patrick Steinhardt}

Reading of symbolic and non-symbolic references is currently treated the same in reference backends: we always call refs_read_raw_ref() and then decide based on the returned flags what type it is.

This has one downside though: symbolic references may be treated different from normal references in a backend from normal references.
The packed-refs backend for example doesn't even know about symbolic references, and as a result it is pointless to even ask it for one.

There are cases where we really only care about whether a reference is symbolic or not, but don't care about whether it exists at all or may be a non-symbolic reference.
But it is not possible to optimize for this case right now, and as a consequence we will always first check for a loose reference to exist, and if it doesn't, we'll query the packed-refs backend for a known-to-not-be-symbolic reference.
This is inefficient and requires us to search all packed references even though we know to not care for the result at all.

Introduce a new function refs_read_symbolic_ref() which allows us to fix this case.

This function will only ever return symbolic references and can thus optimize for the scenario layed out above.
By default, if the backend doesn't provide an implementation for it, we just use the old code path and fall back to read_raw_ref().
But in case the backend provides its own, more efficient implementation, we will use that one instead.

Note that this function is explicitly designed to not distinguish between missing references and non-symbolic references.
If it did, we'd be forced to always search the packed-refs backend to see whether the symbolic reference the user asked for really doesn't exist, or if it exists as a non-symbolic reference.