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

From: "Julia Evans" <[email-masked]>
Date: Wed, 05 Nov 2025 11:26:42 -0500

On Tue, Nov 4, 2025, at 10:21 PM, Ben Knoble wrote:
>> Le 4 nov. 2025 à 19:02, Julia Evans <[email-masked]> a écrit :
>> 
>> 
>> 
>>> On Tue, Nov 4, 2025, at 6:45 PM, Junio C Hamano wrote:
>>> "Julia Evans" <[email-masked]> writes:
>>>> I do not see the point of implying that the commit ID is not "special", or that
>>>> it's only one of many ways to find a commit because to me it seems very special,
>>>> since there is no way I know of to retrieve a commit that doesn't ultimately
>>>> end up using the commit ID at some point. (though that ID might not be encoded
>>>> in hexadecimal)
>>> That is not what I am trying to say.  The hexadecimal name is the
>>> most neutral way to refer to a commit object, and in that sense it
>>> is special.  It is the way ref subsystem uses to record the name of
>>> objects, and that makes it special enough.
>>> But that does not mean that the name _is_ the object.  The
>>> hexadecimal name is a way you use to name the object, but is not the
>>> object itself, and the special-ness of that name does not change it.
>> 
>> Okay. I still do not understand at all why this is so important to you
>> (for the reasons I mentioned before) but I'll see if there's anything I can do.
>
> Perhaps one way to look at is, what diagram would I draw given 
> different textual explanations?
>
> The diagram we _want_ folks to draw (?) is the one where a branch 
> points at a commit [a circle, perhaps], which points to a tree 
> [triangle] and recursively blobs [squares], like I’ve seen Stolee draw 
> for GitHub blogs.
>
> We might also want folks to label the arrows with names, or not.
>
> One way to interpret the “branch refers to a commit ID” might be to 
> draw a diagram where the branch points to an ID label, and to find the 
> circle you have to separately consult a different part of the diagram.

Yes, the most common type of Git diagram I see is something like this:
https://git-scm.com/book/en/v2/images/head-to-master.png
which only includes references, commits, and HEAD. 

That's the diagram I have in mind when writing this text, and I think it's
a useful and accurate diagram to keep in mind, and it's one that you see
very often when using Git tools, including in `git log --graph`. (it's not
a _complete_ diagram of every type of object, but diagrams do not need to be
complete to be accurate)

I personally would not use a graph diagram to explain how commits relate to
trees and blobs (normally I use `git cat-file -p` instead, like I did in this
`gitdatamodel` document. You can see this comic for a "visual" example of how
I've approached discussing trees and blobs in the past with `git cat-file -p`
https://wizardzines.com/comics/explore-a-commit/).

> Both seem useful to me, though as the former has fewer moving pieces 
> might be better for the model this document describes? I dunno.