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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 28, 2025, 20:31 UTC
Message-ID: <xmqqldkubwfp.fsf@gitster.g>
In-Reply-To: <5b078fae-6fe9-4fde-ba84-1070761c168b@app.fastmail.com>

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

Show 10 quoted lines

> Agreed, I really like this idea. Came up with the following, which I'll put at
> the bottom of the "References" section if I don't come up with a better idea.
> (I don't feel strongly about where exactly it should go):
>
> NOTE: Objects will only be deleted if they aren't "reachable" from any reference.
> An object is "reachable" if we can find it by following tags to whatever
> they tag, commits to their parents or trees, and trees to the trees or
> blobs that they contain.
> For example, if you amend a commit, with `git commit --amend`,
> the old commit will usually not be reachable, so it may be deleted eventually.

Other reachability anchors exist, like the index and reflog entries, but we have to stop at somewhere. I am fine if we do not mention them explicitly for the sake of simplicity.

Show 25 quoted lines

>>> +Here's how each type of object is structured:
>>> +
>>> +[[commit]]
>>> +commit::
>>> +    A commit contains the full directory structure of every file
>>> +    in that version of the repository and each file's contents.
>>
>> What you are describing here is more of the property of a tree; a
>> commit is a bit richer.
>>
>>     A commit records a snapshot of the every file in the project at
>>     one point in time, records who contributed to create such a
>>     snapshot and why, and how that particular snapshot relates to
>>     other snapshots in the history.
>
> I don't understand the goal of explaining a commit in detail in
> paragraph form when we already explain everything in a commit right
> below this.
>
> My goal of this intro sentence is just to emphasize what I think is the
> least obvious point in that list, which is that commits contain every file. 
>
> Happy to change it to something shorter like
> "A commit records a snapshot of the every file in the project" if you
> prefer that wording.

Not really. Somebody who is skimming, who reads just the headline without reading enumeration, would not be able to tell differenes between a tree and a commit. Your enumeration lists _what_ is recorded, the headline I gave you above explains _what_ they are recorded _for_.

> I think the current phrasing is okay. I also didn't respond to some of the
> phrasing suggestions above if I didn't understand the goal of them.
> Hope that's okay.

If you do not understand, please ask ;-)