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

From: "Julia Evans" <[email-masked]>
Date: Tue, 11 Nov 2025 10:24:38 -0500

(this message got a bit long but the tl;dr is: maybe
"a branch is a label for a commit ID" would work?)

On Tue, Nov 11, 2025, at 5:13 AM, Junio C Hamano wrote:
> "Julia Evans" <[email-masked]> 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?

My main strategy for figuring out if something is confusing or not is
to talk to a few different users of the software and to ask them what
they think. I have a pretty empirical approach to figuring out if an
explanation is clear or not, if people think it's clear, then it's clear.
(the question of "accuracy" is separate of course)

>From experience talking to people about references in Git I know
that this particular thing is extremely easy to get wrong, I used to
often try to explain branches by saying something like "A branch
to a commit" and I would get kind of a blank stare, which is why
I'm so cautious about the phrasing here.

The reason I started with "a branch is a name for a commit ID"
initially is that I've found that people respond well to that phrasing
in the past, and I don't think it gives a misleading impression about
what a branch is. But I thought your point that (in the context
of this document) the term "name" could perhaps be confused
with "object name" was reasonable, so I've been trying to
come up with an alternative.

It's always a little tricky to explain from first principles _why_
something is confusing, when I started working on explaining Git a
couple of years ago I would have thought that many of your suggested
phrasings would be an effective way to explain how Git branches work to
people and I was very surprised to see how careful I had to be around
the phrasing to get folks to understand how branches work.

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

My thought process is sort of like this: I have two descriptions of
"a Git branch" that people have responded well to in the past in
practice:

1. a branch is a name for a commit ID (you said that the use of
   "name" could be confused with "object name", which
   I thought was fair)
2. a branch is a file that contains a commit ID (people often
   respond very well to how concrete this is, but it refers to
   Git's implementation which we're trying to avoid in this context)

So I'm trying to find a different wording that's similar to one of these
two phrasings that I know are effective, but that doesn't have those
problems.

Some of the options we've discussed are:

- "a branch refers to a commit ID" (which as you've said has kind of a
  "type" issue since technically the branch refers to a commit, though
  when I've discussed it people they don't seem to think it's a problem
  in practice)
- "a branch refers to a commit, using its ID" (we had a long discussion
  about how "using its ID" can lead the reader to think "wait, how else
  could you refer to a commit", which in the context of trying to learn
  what a branch is an unproductive distraction)
- "a branch records a commit ID" (from my discussions I'm pretty sure the
  word "records" does not work, I think it's because introducing a new
  verb like "records" is always a bit dangerous)

One idea I just had is "a branch is a label for a commit ID", which
I think avoids the issue with "name" from earlier.

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