Subject: Re: [PATCH 1/5] git.txt: HEAD is not that special

From: Junio C Hamano <[email-masked]>
Date: Mon, 18 Dec 2023 08:26:40 -0800

Patrick Steinhardt <[email-masked]> writes:

>>  Named pointers called refs mark interesting points in history.  A ref
>> -may contain the SHA-1 name of an object or the name of another ref.  Refs
>> -with names beginning `ref/head/` contain the SHA-1 name of the most
>> +may contain the SHA-1 name of an object or the name of another ref (the
>> +latter is called a "symbolic ref").
>
> On a tangent: While we have a name for symbolic refs, do we also have a
> name for non-symbolic refs? I often use the term "direct ref" to clearly
> distinguish them from symbolic refs, but it's of course not defined in
> our glossary.

You may find me saying "normal ref", "regular ref", or somesuch when
it is not clear from the context if you dig the list archive.
"direct" is a nice word, especially it would give us a good pair of
terms if we are to change "symbolic" to "indirect", but since we are
not going to do so, I am not sure the contrast between "direct" and
"symbolic" would make such a good pair.

But quite honestly I rarely felt a need for a specific term, as it
is fairly clear from the context, e.g.

 * "From a ref, we locate an object using the object name it
   records and use the object"

   A statement written from the point of view of the consumer of
   object name, it does not matter if the object name is directly
   found in the ref, or indirection is involved to find such a
   concrete ref that records an object name by following the
   original symbolic ref.

 * "A ref usually stores an object name, but it can also be a
   symbolic ref that points at another ref, in which case, asking
   what object such a symbolic ref points at would yield the object
   the other ref points at".

So I dunno.

>> +Refs with names beginning `ref/head/` contain the SHA-1 name of the most
>>  recent commit (or "head") of a branch under development.  SHA-1 names of
>> -tags of interest are stored under `ref/tags/`.  A special ref named
>> +tags of interest are stored under `ref/tags/`.  A symbolic ref named
>>  `HEAD` contains the name of the currently checked-out branch.
>
> I was briefly wondering whether we also want to replace SHA-1 with
> "object hash" while at it, but it's certainly out of the scope of this
> patch series.

Yup, there still are too many reference to SHA-1 (and "sha1", which
is even worse), and it is not a focus of this series.

Thanks.