From: "Julia Evans" <julia@jvns•ca>
To: "Junio C Hamano" <gitster@pobox•com>
Cc: "Julia Evans" <gitgitgadget@gmail•com>,
git@vger•kernel.org,
"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com>,
"D. Ben Knoble" <ben.knoble@gmail•com>,
"Patrick Steinhardt" <ps@pks•im>
Subject: Re: [PATCH v5] doc: add an explanation of Git's data model
Date: Tue, 04 Nov 2025 10:45:25 -0500 [thread overview]
Message-ID: <9ff9d97e-2fae-488c-990b-cb574fbe8c71@app.fastmail.com> (raw)
In-Reply-To: <xmqqpl9yshrr.fsf@gitster.g>
On Mon, Nov 3, 2025, at 8:34 PM, Junio C Hamano wrote:
> "Julia Evans" <julia@jvns•ca> writes:
>
>>>> +tree::
>>>> + A tree is how Git represents a directory.
>>>> + It can contain files or other trees (which are subdirectories).
>>>> + It lists, for each item in the tree:
>>>> ++
>>>> +1. The *filename*, for example `hello.py`
>>>> +2. The *file mode*. Git has these file modes. which are only
>>>
>>> "has these" -> "uses only these" to clarify that this is an
>>> exhaustive enumeration and users cannot invent 100664 and others,
>>> which is a mistake Git itself used to make/allow.
>>
>> I like the idea to make it more explicit that this is an exhaustive
>> enumeration. I'll try changing it to this instead: "These are all of the file
>> modes in Git (which are only spiritually related to Unix file modes):"
>
> The primary reason why I suggested "uses only these" was because I
> thought it would strongly hint that random additions beyond the set
> is unwelcome. As long as that implication is not lost, I do not
> have strong preference between "we only use these and nothing else"
> and your "these are all that we use".
>
>>>> +[[tag-object]]
>>>> +tag object::
>>>> + Tag objects contain these required fields
>>>> + (though there are other optional fields):
>>>> ++
>>>> +1. The object *ID* it references
>>>> +2. The object *type*
>>>
>>> I would rephrase these to
>>>
>>> 1. The *ID* of the object it references
>>> 2. The *type* of the object it references
>>>
>>> because (1) a tag object references another object, not ID. To name
>>> the object it reference, it uses the object name of it, but just
>>> like your name is not you, object name is not the object (it merely
>>> is *one* way to refer to it). (2) unless it is very clear to readers
>>> that "The object" in 1. and 2. refer to the same object, 2. invites
>>> a question "type of which object?".
>>
>> That makes sense to me, will change it to that.
>>
>>>> +[[branch]]
>>>> +branches: `refs/heads/<name>`::
>>>> + A branch refers to a commit ID.
>>>
>>> A branch refers to a commit object (by its ID). Ditto for tags.
>>
>> What's the goal of this? I can't tell what misconception you're
>> trying to avoid here.
>
> This comes from the same place as the suggestion for the tag object
> above, i.e. "a tag object references another object, not ID.".
>
> Exactly the same reasoning applies here. A branch refers to a
> commit, and to name the object it references, it uses the object
> name of it, but just like your name is not you, object name is not
> the object itself.
I agree the ID of a commit is not the same as the commit itself.
The reason I said "refers to a commit ID" is that it's a very concise
explanation and I don't see any risk that the reader will be
confused by it.
Unlike with my name, commit IDs uniquely identify commits, so
I think it will be clear to the reader that the commit ID is going to
be used to retrieve the commit object.
The problem with "A branch refers to a commit object (by its ID)." is
that it introduces some more potential for confusion: it makes it
sound like there might be other ways to refer to a commit object
than by its ID.
Maybe there's another option? To me this introduces the potential
for more confusion and does not solve any specific problem.
next prev parent reply other threads:[~2025-11-04 15:45 UTC|newest]
Thread overview: 89+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-10-03 17:34 [PATCH] doc: add a explanation of Git's data model Julia Evans via GitGitGadget
2025-10-03 21:46 ` Kristoffer Haugsbakk
2025-10-06 19:36 ` Julia Evans
2025-10-06 21:44 ` D. Ben Knoble
2025-10-06 21:46 ` Julia Evans
2025-10-06 21:55 ` D. Ben Knoble
2025-10-09 13:20 ` Julia Evans
2025-10-08 9:59 ` Kristoffer Haugsbakk
2025-10-06 3:32 ` Junio C Hamano
2025-10-06 19:03 ` Julia Evans
2025-10-07 12:37 ` Kristoffer Haugsbakk
2025-10-07 16:38 ` Junio C Hamano
2025-10-07 14:32 ` Patrick Steinhardt
2025-10-07 17:02 ` Junio C Hamano
2025-10-07 19:30 ` Julia Evans
2025-10-07 20:01 ` Junio C Hamano
2025-10-07 18:39 ` D. Ben Knoble
2025-10-07 18:55 ` Julia Evans
2025-10-08 4:18 ` Patrick Steinhardt
2025-10-08 15:53 ` Junio C Hamano
2025-10-08 19:06 ` Julia Evans
2025-10-08 13:53 ` [PATCH v2] " Julia Evans via GitGitGadget
2025-10-10 11:51 ` Patrick Steinhardt
2025-10-13 14:48 ` Junio C Hamano
2025-10-14 5:45 ` Patrick Steinhardt
2025-10-14 9:18 ` Julia Evans
2025-10-14 11:45 ` Patrick Steinhardt
2025-10-14 13:39 ` Junio C Hamano
2025-10-14 21:12 ` [PATCH v3] " Julia Evans via GitGitGadget
2025-10-15 6:24 ` Patrick Steinhardt
2025-10-15 15:34 ` Junio C Hamano
2025-10-15 17:20 ` Julia Evans
2025-10-15 20:42 ` Junio C Hamano
2025-10-16 14:21 ` Julia Evans
2025-10-15 19:58 ` Junio C Hamano
2025-10-16 15:19 ` Julia Evans
2025-10-16 16:54 ` Junio C Hamano
2025-10-16 18:59 ` Julia Evans
2025-10-16 20:48 ` Junio C Hamano
2025-10-16 15:24 ` Kristoffer Haugsbakk
2025-10-20 16:37 ` Kristoffer Haugsbakk
2025-10-20 18:01 ` Junio C Hamano
2025-10-27 19:32 ` [PATCH v4] doc: add an " Julia Evans via GitGitGadget
2025-10-27 21:54 ` Junio C Hamano
2025-10-28 20:10 ` Julia Evans
2025-10-28 20:31 ` Junio C Hamano
2025-10-30 20:32 ` [PATCH v5] " Julia Evans via GitGitGadget
2025-10-31 14:44 ` Junio C Hamano
2025-11-03 7:40 ` Patrick Steinhardt
2025-11-03 15:38 ` Junio C Hamano
2025-11-03 19:43 ` Julia Evans
2025-11-04 1:34 ` Junio C Hamano
2025-11-04 15:45 ` Julia Evans [this message]
2025-11-04 20:53 ` Junio C Hamano
2025-11-04 21:24 ` Julia Evans
2025-11-04 23:45 ` Junio C Hamano
2025-11-05 0:02 ` Julia Evans
2025-11-05 3:21 ` Ben Knoble
2025-11-05 16:26 ` Julia Evans
2025-11-06 3:07 ` Ben Knoble
2025-10-31 21:49 ` Junio C Hamano
2025-11-03 7:40 ` Patrick Steinhardt
2025-11-03 19:52 ` Julia Evans
2025-11-07 19:52 ` [PATCH v6] " Julia Evans via GitGitGadget
2025-11-07 21:03 ` Junio C Hamano
2025-11-07 21:23 ` Junio C Hamano
2025-11-07 21:40 ` Julia Evans
2025-11-07 23:07 ` Junio C Hamano
2025-11-08 19:43 ` Junio C Hamano
2025-11-09 0:48 ` Ben Knoble
2025-11-09 4:59 ` Junio C Hamano
2025-11-10 15:56 ` Julia Evans
2025-11-11 10:13 ` Junio C Hamano
2025-11-11 13:07 ` Ben Knoble
2025-11-11 15:24 ` Julia Evans
2025-11-12 19:16 ` Junio C Hamano
2025-11-12 22:49 ` Junio C Hamano
2025-11-13 19:50 ` Julia Evans
2025-11-13 20:07 ` Junio C Hamano
2025-11-13 20:18 ` Julia Evans
2025-11-13 20:34 ` Chris Torek
2025-11-13 23:11 ` Junio C Hamano
2025-11-12 19:53 ` [PATCH v7] " Julia Evans via GitGitGadget
2025-11-12 20:26 ` Junio C Hamano
2025-11-23 2:37 ` Junio C Hamano
2025-12-01 8:14 ` Patrick Steinhardt
2025-12-02 12:25 ` Junio C Hamano
2025-10-09 14:20 ` [PATCH] doc: add a " Julia Evans
2025-10-10 0:42 ` Ben Knoble
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=9ff9d97e-2fae-488c-990b-cb574fbe8c71@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=ben.knoble@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=gitster@pobox$(echo .)com \
--cc=kristofferhaugsbakk@fastmail$(echo .)com \
--cc=ps@pks$(echo .)im \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox