Re: [PATCH v5] doc: add an explanation of Git's data model

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 4, 2025, 20:53 UTC
Message-ID: <xmqq346tpliw.fsf@gitster.g>
In-Reply-To: <9ff9d97e-2fae-488c-990b-cb574fbe8c71@app.fastmail.com>

"Julia Evans" <julia@jvns.ca> writes:

> The problem with "A branch refers to a commit object (by its ID)." is

Ah, I didn't mean to say "you must use exactly that phrase".

But branch refers to a commit object, it does not refer to the name of a commit object.

Perhaps "a branch ref records the object name of a commit object", would be better? The untold implication of the phrasing is that anybody who reads what is recorded by that ref can then use the result to refer to (find) the commit object.

> it introduces some more potential for confusion: it makes it
> sound like there might be other ways to refer to a commit object
> than by its ID.

Yes, there are unbound number of ways to refer to a commit object.

 $ git show-ref refs/heads/maint
 bb5c624209fcaebd60b9572b2cc8c61086e39b57 refs/heads/maint

The branch ref let you refer to a commit object by recording its commit object name bb5c6242, but for humans, it is much easier to refer to the same commit as "v2.51.2^{commit}", which is far more memorable. Of course I can use master~32^2 to call the same commit object, which is less memorable gives us a hint that the tip of master fully contains that maintenance release. What's more useful depends on how the name will be used, and the hexadecimal object names happen to be how refs record the objects they refer to.