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

From: Julia Evans <julia@jvns.ca>
Date: Nov 7, 2025, 21:40 UTC
Message-ID: <07cca81a-10fd-49aa-b175-17b49e4f1116@app.fastmail.com>
In-Reply-To: <xmqqseepedue.fsf@gitster.g>

On Fri, Nov 7, 2025, at 4:23 PM, Junio C Hamano wrote:

Show 22 quoted lines

> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>>     changes in v6:
>>     
>>      * Make punctuation more consistent (from Patrick's review)
>
> Good.
>
>>      * Explain more about when exactly amended commits will get deleted
>>        (when their reflog entry expires), from Junio's review
>
> Looked good.
>
>>      * Be more explicit that there are only 5 file modes in Git (from
>>        Junio's review)
>
> I find "These are all of the file modes in Git" hard to read and
> understand, and more importantly, does not imply that we won't be
> adding any others strongly enough, than something like "Git uses
> only the following modes to represent the objects it stores".
>
>>      * Make tag object description clearer (from Junio's review)

I wonder if it would help to de-emphasize the octal representation of the file modes, and instead give them names since (from a data model section Git's file modes are really more like an enum with 5 values than )

Something like this:

	Git has 5 file modes:

	  - *regular file* (with <<object,object type>> `blob`)
	  - *executable file* (with type `blob`)
	  - *symbolic link* (with type `blob`)
	  - *directory* (with type `tree`)
	  - *gitlink*, for use with submodules (with type `commit`)

	NOTE: Git normally displays file modes in the same format as Unix file modes
	(100644, 100755, 120000, 040000, and 160000 respectively), but file modes are
	only spiritually related to Unix file modes.

Show 9 quoted lines

> OK.
>
>>      * We had a long discussion about the phrasing of "A branch refers to a
>>        commit ID" but I didn't come up with any ideas for how to improve the
>>        phrasing so I left it as is.
>
> I gave you something that is clearly an improvement there, though.
> Just like a tag object records "the ID of the object it references",
> a branch records "the ID of the commit it references".

To me an "improvement" is something that helps the reader understand how Git's data model, and I do not understand in what way this rephrasing helps the reader, or how you think the current phrasing might cause confusion for the reader.

From my point of view "a branch refers to a commit ID" clearly means the exact same thing as "a branch records the ID of the commit it references" and "a branch records the ID of the commit it references" is just a less clear and more indirect way to communicate that.

Show 5 quoted lines

> Another thing we discussed and a better alternative offered during
> the last round was "base directory", to which Patrick mentioned 
> "we rather consistently use 'root tree'"
>
>  cf. https://lore.kernel.org/git/aQhcbHJjiI5GtV6Y@pks.im/

I think it would be better to stick with "directory" here, because I've gotten several reader comments saying that they do not understand the term "tree" when it is used as a synonym for "directory".

Maybe "root directory"?

> Other than a few minor points I pointed out above, and the broken
> xml id/idref that does not validate, this round looks good to me.

Will fix the broken XML.