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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 11, 2025, 10:13 UTC
Message-ID: <xmqqfrakyj0w.fsf@gitster.g>
In-Reply-To: <150f3442-93a6-4469-9c25-5bca24accc80@app.fastmail.com>

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

> Like you noticed in the tag object section, I think saying that the tag
> object "refers to an object" works well in that context, but in the context
> of explaining what a branch is it makes the text more confusing.

Sorry, but I do not understand your objection, as I cannot see what confusion it would bring in in saying "a ref refers to an object" (or "a branch refers to a commit object"). A ref refers to an object, just like a tag field in a tag object or a tree-entry in a tree object refer to another object. They do so by recording the name of the object they refer to. So what's so confusing if we said that straight?

Are you saying that the noun "reference" (or "ref") is a sufficient clue to readers that their objective is to "refer to" something, so "refers to" is a redundant thing to say?

Maybe its just me, but I find it a quite roundabout thing to say that a ref refers to an object name (or "ID" if you like), simply because name or ID *is* a way to refer to the thing that is assigned that name, so you are making a ref to refer to something ("name") that refers to what it ("ref") originally wanted to refer to ("object").

That is what I find the most strange in the construction "A branch refers to ID" at the conceptual level. I am much less unhappy with "A branch records an ID", but stopping at that may make readers ask the obvious question "what goal does that design aim to achieve?" (whose answer is of course "to refer to the object that is assigned that ID").

"A branch refers to a commit object by recording its object name", "A branch records the ID of a commit it refers to", "A branch records the ID of the commit at the tip of its history". Any of the phrasing that does not make "ID" the object/target of the verb "refer to" would work to avoid that strange construction.

By the way, Ben used a word "unwelcome", but the words that are more appropriate to describe my reaction were "frustrated" (for not being able to explain what I know to be true clearly to make others understand) and "disappointed".