Pinned references?

4 messages between Jun 18, 2026 and Jun 21, 2026, from Erik Östlund, Patrick Steinhardt, Junio C Hamano, Jeff King.

Plain Markdown or JSON for tools and agents.

Erik ÖstlundJun 18, 2026, 18:37 UTC on lore

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

Patrick SteinhardtJun 19, 2026, 07:38 UTC in reply to Erik Östlund on lore

Re: Pinned references?

On Thu, Jun 18, 2026 at 08:37:26PM +0200, Erik Östlund wrote:

Show 17 quoted lines

> 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

Junio C HamanoJun 19, 2026, 16:25 UTC in reply to Patrick Steinhardt on lore

Re: Pinned references?

Patrick Steinhardt <ps@pks.im> writes:

Show 21 quoted lines

> 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.

Jeff KingJun 21, 2026, 21:53 UTC in reply to Junio C Hamano on lore

Re: Pinned references?

On Fri, Jun 19, 2026 at 09:25:19AM -0700, Junio C Hamano wrote:

Show 31 quoted lines

> 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.

This is somewhat related to the thread here:

  https://lore.kernel.org/git/CAFb48S8LDz4kiWsKSCBn8J=AHyQ5SVPFH4GY=z+8=DntT=PyAw@mail.gmail.com/

The problem there was the opposite. A name "foo-gcc14" was taken as a describe name (for object "cc14") when it was not. But one thing I noted there is that you probably can't be too picky about having "foo" when you see "foo-g1234abcd". Part of the point of putting the hash in the described name is that the receiver does not necessarily have your same refs!

So insisting that "v2.54.0-0-g1234abcd" have both "v2.54.0" and "1234abcd" locally is probably going to cause some regressions. We could quietly accept it as "1234abcd" if your "v2.54.0" ref is missing entirely, though that is perhaps missing the point of the original request.

The discussion around this patch series might also be relevant:

  https://lore.kernel.org/git/xmqqed1i4pga.fsf@gitster.g/

-Peff