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

[Patrick Steinhardt <ps@pks.im>]

[-- Attachment #1: Type: text/plain, Size: 2364 bytes --]

On Fri, Dec 15, 2023 at 12:32:41PM -0800, Junio C Hamano wrote:
> The introductory text in "git help git" that describes HEAD called
> it "a special ref".  It is special compared to the more regular refs
> like refs/heads/master and refs/tags/v1.0.0, but not that special,
> unlike truly special ones like FETCH_HEAD.
> 
> Rewrite a few sentences to also introduce the distinction between a
> regular ref that contain the object name and a symbolic ref that
> contain the name of another ref.  Update the description of HEAD
> that point at the current branch to use the more correct term, a
> "symbolic ref".
> 
> This was found as part of auditing the documentation and in-code
> comments for uses of "special ref" that refer merely a "pseudo ref".
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/git.txt | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 2535a30194..880cdc5d7f 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -1025,10 +1025,11 @@ When first created, objects are stored in individual files, but for
>  efficiency may later be compressed together into "pack files".
>  
>  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.

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

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]