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

From: Julia Evans <julia@jvns.ca>
Date: Nov 11, 2025, 15:24 UTC
Message-ID: <2474339d-67bc-4a68-9f26-fe7edd172ec4@app.fastmail.com>
In-Reply-To: <xmqqfrakyj0w.fsf@gitster.g>

(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:

Show 9 quoted lines

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

Show 5 quoted lines

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

Show 10 quoted lines

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

Show 17 quoted lines

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