From: "Julia Evans" <julia@jvns•ca>
To: "Junio C Hamano" <gitster@pobox•com>,
"Julia Evans" <gitgitgadget@gmail•com>
Cc: git@vger•kernel.org,
"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com>,
"D. Ben Knoble" <ben.knoble@gmail•com>,
"Patrick Steinhardt" <ps@pks•im>
Subject: Re: [PATCH v6] doc: add an explanation of Git's data model
Date: Fri, 07 Nov 2025 16:40:08 -0500 [thread overview]
Message-ID: <07cca81a-10fd-49aa-b175-17b49e4f1116@app.fastmail.com> (raw)
In-Reply-To: <xmqqseepedue.fsf@gitster.g>
On Fri, Nov 7, 2025, at 4:23 PM, Junio C Hamano wrote:
> "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)
I wonder if it would help to de-emphasize the octal representation
of the file modes, and instead give them names since (from a
data model section Git's file modes are really more like an enum with
5 values than )
Something like this:
Git has 5 file modes:
- *regular file* (with <<object,object type>> `blob`)
- *executable file* (with type `blob`)
- *symbolic link* (with type `blob`)
- *directory* (with type `tree`)
- *gitlink*, for use with submodules (with type `commit`)
NOTE: Git normally displays file modes in the same format as Unix file modes
(100644, 100755, 120000, 040000, and 160000 respectively), but file modes are
only spiritually related to Unix file modes.
> 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".
To me an "improvement" is something that helps the reader understand how Git's
data model, and I do not understand in what way this rephrasing helps the
reader, or how you think the current phrasing might cause confusion for the
reader.
From my point of view "a branch refers to a commit ID" clearly means the exact
same thing as "a branch records the ID of the commit it references" and
"a branch records the ID of the commit it references" is just a less clear and
more indirect way to communicate that.
> 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/
I think it would be better to stick with "directory" here, because I've gotten
several reader comments saying that they do not understand the
term "tree" when it is used as a synonym for "directory".
Maybe "root directory"?
> 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.
Will fix the broken XML.
next prev parent reply other threads:[~2025-11-07 21:40 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
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 [this message]
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=07cca81a-10fd-49aa-b175-17b49e4f1116@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