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

From: Julia Evans <julia@jvns.ca>
Date: Nov 5, 2025, 16:26 UTC
Message-ID: <7217ae44-5ad5-468c-b76b-c485247fb2f4@app.fastmail.com>
In-Reply-To: <7E8706EF-6C15-43AD-A847-5C896D9235AA@gmail.com>

On Tue, Nov 4, 2025, at 10:21 PM, Ben Knoble wrote:

Show 35 quoted lines

>> Le 4 nov. 2025 à 19:02, Julia Evans <julia@jvns.ca> a écrit :
>> 
>> 
>> 
>>> On Tue, Nov 4, 2025, at 6:45 PM, Junio C Hamano wrote:
>>> "Julia Evans" <julia@jvns.ca> 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.