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

From: Julia Evans <julia@jvns.ca>
Date: Oct 7, 2025, 19:30 UTC
Message-ID: <ede082ad-5031-4b55-8576-0a6315f16b70@app.fastmail.com>
In-Reply-To: <xmqq4isalk5g.fsf@gitster.g>

Show 5 quoted lines

>> I think this needs to be adapted to not single out SHA-1 as the only
>> hashing algorithm. We already support SHA-256, so we should definitely
>> say that the algorithm can be swapped. Maybe something like:
>
> Good point.  Also officially they are called "object name".

I hadn't realized that "object name" was the official name, it does seem to be used a lot in the docs. I'm going to try something like this:

1. an *ID* (aka "object name"), which is a cryptographic hash of its
  type and contents.

I think it's useful to refer this as an "ID", because usually we call it a "commit ID" or "tag ID" and not a "commit name" or "tag name" and it makes it more clear that "object name" and "commit ID" refer to the same identifier.

Show 17 quoted lines

>>> +tree 1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a
>>> +parent 4ccb6d7b8869a86aae2e84c56523f8705b50c647
>>> +author Maya <maya@example.com> 1759173425 -0400
>>> +committer Maya <maya@example.com> 1759173425 -0400
>>> +
>>> +Add README
>>> +----
>>
>> In practice, commits can have other headers that are ignored by Git. But
>> that's certainly not part of Git's core data model, so I don't think we
>> should mention that here.
>
> Third-party software can add truly garbage ones that do not have any
> meaning, and Git tolerates by ignoring them.  But there are others
> that Git does pay attention to, like encoding, gpgsig, etc., which
> may worth mention (in the form that "these four are what you typically
> see, but there may be others" without even naming any).

I didn't realize that there were other optional fields, will try to communicate this somehow.