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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 7, 2025, 21:23 UTC
Message-ID: <xmqqseepedue.fsf@gitster.g>
In-Reply-To: <pull.1981.v6.git.1762545177204.gitgitgadget@gmail.com>

"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)

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".

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/

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.

Thanks.