Pinned references?

Pinned references?

[Erik Östlund]

I'd like to be able to express a reference together with an expected
object ID, for example with strawman syntax like:

refs/tags/v1.2.3?oid=a1b2c3d4

The intended semantics would be that both the reference and object ID
must exist, and Git should fail if the reference does not resolve to the
specified object ID.

Tags are nice because they convey human meaning. Object IDs are nice
because they are immutable. As it is, I often have to choose between the
two, or represent them separately in external tooling.

Is there existing terminology, prior discussion, or an accepted Git-native
approach for this kind of "ref plus expected OID" invariant? I
searched both the Git reference documentation and the mailing list
archives, but couldn't find what I was looking for.

Thanks,
Erik

Re: Pinned references?

[Patrick Steinhardt]

On Thu, Jun 18, 2026 at 08:37:26PM +0200, Erik Östlund wrote:
> I'd like to be able to express a reference together with an expected
> object ID, for example with strawman syntax like:
> 
> refs/tags/v1.2.3?oid=a1b2c3d4
> 
> The intended semantics would be that both the reference and object ID
> must exist, and Git should fail if the reference does not resolve to the
> specified object ID.
> 
> Tags are nice because they convey human meaning. Object IDs are nice
> because they are immutable. As it is, I often have to choose between the
> two, or represent them separately in external tooling.
> 
> Is there existing terminology, prior discussion, or an accepted Git-native
> approach for this kind of "ref plus expected OID" invariant? I
> searched both the Git reference documentation and the mailing list
> archives, but couldn't find what I was looking for.

You can already kind of do this:

    $ git rev-parse v2.54.0
    0b13e48a3a30cdfa94e8ef842e24d6045ab3d015

    $ git rev-parse v2.54.0-0-g0b13e48a3
    0b13e48a3a30cdfa94e8ef842e24d6045ab3d015

    $ git rev-parse v2.54.0-0-g95e20213f
    95e20213faefeb95df29277c58ac1980ab68f701

This is described under gitrevisions(7), `<describeOutput>`. The only
gotcha is that this format will not verify that the tag and the object
ID actually match. But other than that it gives you the ability to have
both the human-readable name and the machine-readable commit ID in
there.

As said, we don't verify that those two revisions actually match. So in
the case where they don't the result is certainly going to be lots of
confusion. It certainly is one of the more surprising syntaxes that we
have in Git.

Patrick

Re: Pinned references?

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> You can already kind of do this:
>
>     $ git rev-parse v2.54.0
>     0b13e48a3a30cdfa94e8ef842e24d6045ab3d015
>
>     $ git rev-parse v2.54.0-0-g0b13e48a3
>     0b13e48a3a30cdfa94e8ef842e24d6045ab3d015
>
>     $ git rev-parse v2.54.0-0-g95e20213f
>     95e20213faefeb95df29277c58ac1980ab68f701
>
> This is described under gitrevisions(7), `<describeOutput>`. The only
> gotcha is that this format will not verify that the tag and the object
> ID actually match. But other than that it gives you the ability to have
> both the human-readable name and the machine-readable commit ID in
> there.
>
> As said, we don't verify that those two revisions actually match. So in
> the case where they don't the result is certainly going to be lots of
> confusion. It certainly is one of the more surprising syntaxes that we
> have in Git.

It is very unlikely we would change this, but it is a fun thought
experiment to imagine what would have happened if we insisted (i.e.,
verified and then died if it does not hold true) on the presence of
v2.54.0 tag and when the "hop" count is "-0-", we also insisted that
the hexadecimal part exactly matched the contents of v2.54.0 tag, or
when the "hop" count is not zero, we insisted that the hexadecimal
part names a commit that is descendant of the commit v2.54.0 names.