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

[Junio C Hamano <gitster@pobox.com>]

Junio C Hamano <gitster@pobox.com> writes:

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

The above two points should probably be trivial to address.  I've
already squashed in the xml validation fixes to [v6], so let's
finish the rest quickly.

I have no more words to offer somebody, who says she does not know
why saying "branch records ID of the commit it refers to" is an
improvement over "branch refers to ID of the commit", when she
already accepts that "The *ID* of the object it references" is a
better way than "The object *ID* it references" to describe one of
the fields in an annotated tag object.  So I wouldn't mind if v7
still said "branch refers to commit id".  We can update it with
follow-up series as needed, and it is not worth blocking the rest of
the document.

Refs (including branches), refer to objects exactly the same way an
annotated tag refers to another object, or a tree entry in a tree
object refers to a blob, tree, or a commit object.  Recording the
hexadecimal hash is an implementation detail of the way how they
reference the object, and the phrasing used for the tag field in an
annotated tag reflects that by clearly distinguishing 

 - recording the ID 
 - referring to the object

as two separate things.  The former is merely a means to the end
which is the latter, i.e. the purpose of refs, tree-entry in a tree,
tag field in a tag object, and all other things that refer to an
object by recording its ID.