From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 07 Nov 2025 23:07:59 GMT
Subject: Re: [PATCH v6] doc: add an explanation of Git's data model
Message-ID: <xmqqo6pde90w.fsf@gitster.g>
In-Reply-To: <07cca81a-10fd-49aa-b175-17b49e4f1116@app.fastmail.com>

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

> 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.

Then, I would suggest further deemphasize the "file modes" even
more.  

    * Git stores/tracks 5 different file types, which are
      non-executable files, executable files, symbolic links,
      directories, and gitlinks.

    * Git uses one bitpattern each to mark these 5 different kinds
      of things in tree objects.  These bitpatterns were loosely
      modelled after UNIX file mode bits.

The first half entirely avoids saying "mode" and that is very
deliberate.

> ... 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.

A branch (or any ref) does *not* *REFERENCE* an ID.  They refer to
objects by *recording* an ID.  The distinction is not clear with
your wording.

>> 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"?

I am OK with "root" but that is conditional; only if it is not used
together with the word "directory".  We are not talking about "root
directory" where common directories like /usr, /etc, /dev and /tmp
hang immediately below.  If we use the word "directory", I'd
strongly prefer to see it with adjective like "top-level" that
implies that it is something different from "root directory" but is
relative to the project in question.

Thanks.