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

From: Junio C Hamano <[email-masked]>
Date: Tue, 14 Oct 2025 06:39:01 -0700

"Julia Evans" <[email-masked]> writes:

>> Yeah, I don't necessarily think that we need to mention root refs here.
>> But what I think we need to avoid is the following sentence, as it is
>> misleading:
>>
>>     References are stored in a hierarchy, and Git handles references
>>     differently based on where they are in the hierarchy.
>>
>
> Why do you say that it’s misleading? (what do you think it’s
> implying that is not true?)
>
> What i’m trying to communicate is that branches, tags, etc are
> treated differently from each other and that Git knows how to
> handle them based on where they are in the hierarchy.

FWIW, I had the same reaction to what response you are responding to
said.  I think Patrick assumes that our target audiences would
assume the "hierarchy" begins at "refs/" and "root" things are
outside the hierarchy, but my mental model saw that the hierarchy
began at the root level, most of things are in "refs/", but one
level above it lives things like HEAD and ORIG_HEAD.  I think both
can be valid, but I do not know which views are more common.

Thanks.