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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 4, 2025, 01:34 UTC
Message-ID: <xmqqpl9yshrr.fsf@gitster.g>
In-Reply-To: <8b70796e-b5a4-4f70-8b27-c0ed80d1fc4d@app.fastmail.com>

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

Show 15 quoted lines

>>> +tree::
>>> +    A tree is how Git represents a directory.
>>> +    It can contain files or other trees (which are subdirectories).
>>> +    It lists, for each item in the tree:
>>> ++
>>> +1. The *filename*, for example `hello.py`
>>> +2. The *file mode*. Git has these file modes. which are only
>>
>> "has these" -> "uses only these" to clarify that this is an
>> exhaustive enumeration and users cannot invent 100664 and others,
>> which is a mistake Git itself used to make/allow.
>
> I like the idea to make it more explicit that this is an exhaustive
> enumeration. I'll try changing it to this instead: "These are all of the file
> modes in Git (which are only spiritually related to Unix file modes):"

The primary reason why I suggested "uses only these" was because I thought it would strongly hint that random additions beyond the set is unwelcome. As long as that implication is not lost, I do not have strong preference between "we only use these and nothing else" and your "these are all that we use".

Show 30 quoted lines

>>> +[[tag-object]]
>>> +tag object::
>>> +    Tag objects contain these required fields
>>> +    (though there are other optional fields):
>>> ++
>>> +1. The object *ID* it references
>>> +2. The object *type*
>>
>> I would rephrase these to
>>
>>     1. The *ID* of the object it references
>>     2. The *type* of the object it references
>>
>> because (1) a tag object references another object, not ID.  To name
>> the object it reference, it uses the object name of it, but just
>> like your name is not you, object name is not the object (it merely
>> is *one* way to refer to it). (2) unless it is very clear to readers
>> that "The object" in 1. and 2. refer to the same object, 2. invites
>> a question "type of which object?".
>
> That makes sense to me, will change it to that.
>
>>> +[[branch]]
>>> +branches: `refs/heads/<name>`::
>>> +    A branch refers to a commit ID.
>>
>> A branch refers to a commit object (by its ID).  Ditto for tags.
>
> What's the goal of this? I can't tell what misconception you're
> trying to avoid here.

This comes from the same place as the suggestion for the tag object above, i.e. "a tag object references another object, not ID.".

Exactly the same reasoning applies here. A branch refers to a commit, and to name the object it references, it uses the object name of it, but just like your name is not you, object name is not the object itself.

Thanks.