From: Julia Evans Date: Tue, 04 Nov 2025 15:45:25 GMT Subject: Re: [PATCH v5] doc: add an explanation of Git's data model Message-ID: <9ff9d97e-2fae-488c-990b-cb574fbe8c71@app.fastmail.com> In-Reply-To: On Mon, Nov 3, 2025, at 8:34 PM, Junio C Hamano wrote: > "Julia Evans" writes: > >>>> +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". > >>>> +[[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/`:: >>>> + 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. I agree the ID of a commit is not the same as the commit itself. The reason I said "refers to a commit ID" is that it's a very concise explanation and I don't see any risk that the reader will be confused by it. Unlike with my name, commit IDs uniquely identify commits, so I think it will be clear to the reader that the commit ID is going to be used to retrieve the commit object. The problem with "A branch refers to a commit object (by its ID)." is that it introduces some more potential for confusion: it makes it sound like there might be other ways to refer to a commit object than by its ID. Maybe there's another option? To me this introduces the potential for more confusion and does not solve any specific problem.