Re: [PATCH v3] doc: add a explanation of Git's data model

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 15, 2025, 15:34 UTC
Message-ID: <xmqqsefkuqkv.fsf@gitster.g>
In-Reply-To: <aO8-NtJPNBAM2tVn@pks.im>

Patrick Steinhardt <ps@pks.im> writes:

Show 6 quoted lines

>> +Like all other objects, commits can never be changed after they're created.
>> +For example, "amending" a commit with `git commit --amend` creates a new
>> +commit with the same parent.
>
> Let's say "parents" instead of "parent" here so that it also works for
> root and merge commits.

I just found it amusing that parents can be 0 ;-)

Show 9 quoted lines

>> +NOTE: By default, Git references are stored as files in the `.git` directory.
>> +For example, the branch `main` is stored in `.git/refs/heads/main`.
>> +This means that you can't have branches named both `maya` and `maya/some-task`,
>> +because there can't be a file and a directory with the same name.
>
> Hm. I think mentioning this can help, but it may also creates questions
> when someone has a "main" branch but is unable find it in
> ".git/refs/heads/main" because it has either been packed, or because the
> repository uses reftables.

I had the same thought. The only thing we want to stress here is that the names of refs _behave_ like filesystem entities. So how about saying just

    Note: when you have a branch with <name>, you cannot have any
    branch whose name begins with "<name>/".

and stop at it? It may look like an arbitrary limitation, and once in a distant future ref-files gets retired, it will become one (as there is no inherent reason why reftable backend must retain it; it only enforces the same limitation to ensure that the names it stores interoperate with another clone that uses ref-files backend). At the data-model level (which is the theme of this document), it is just as immaterial as refnames may be case insensitive on some systems.

Mentioning the limitation may be good, but the data model document is not the right place to explain where this limitation comes from (i.e. to be compatible with and expressible in ref-files backend). We do not say "you may not be able to have 'maya' branch and 'mAYa' branch at the same time on some systems", either ;-).

>> +Git stores a history called a "reflog" for every branch, remote-tracking
>
> I think it's a bit unclear what "history" means here. Maybe:

"records of updates", perhaps?