From: Stefan Sperling <stsp@stsp.name>
Subject: got.1: avoid work tree "HEAD" terminology
To: gameoftrees@openbsd.org
Date: Mon, 17 Jul 2023 12:06:44 +0200

The term "HEAD" has a special meaning in the context of a Git repository,
indicating a specific well-known symbolic reference.

The documentation of the new keyword feature introduced the concept of
a work tree HEAD, which doesn't exist as such in Got's user interface.
The documentation tweak below avoids the term HEAD in the context of a
work tree to prevent potential confusion.

In the Got work tree the term "head" only exists in the implementation
as variable names and the file .got/head-ref. In retrospect I wish I
had called this file and related variables 'branch-tip' instead.

I am considering whether we should rename the :head keyword to :tip.
However, outside of a work tree the :head keyword does indeed resolve
to the repository's HEAD, so perhaps the keyword :head is fine as it is?

In any case, I want to apply the wording change below:

diff /home/stsp/src/got
commit - 19a7924f3e98de860b409b8480b10b57ce16914e
path + /home/stsp/src/got
blob - 149fcba8cbdc4b369202dd5851e3e3aa63ed24d4
file + got/got.1
--- got/got.1
+++ got/got.1
@@ -707,7 +707,7 @@ and HEAD reference, respectively.
 and
 .Qq :head
 can also be used to represent the work tree's base commit
-and HEAD reference, respectively.
+and branch head, respectively.
 Keywords and reference names may be appended with
 .Qq :+
 or
@@ -716,7 +716,7 @@ denotes the HEAD reference's 2nd generation ancestor, 
 Nth descendant or antecedent, respectively, by first parent traversal;
 for example,
 .Sy :head:-2
-denotes the HEAD reference's 2nd generation ancestor, and
+denotes the work tree branch head's 2nd generation ancestor, and
 .Sy :base:+4
 denotes the 4th generation descendant of the work tree's base commit.
 Similarly,
@@ -903,7 +903,7 @@ and HEAD reference, respectively.
 and
 .Qq :head
 can also be used to represent the work tree's base commit
-and HEAD reference, respectively.
+and branch head, respectively.
 The former is only valid if invoked in a work tree, while the latter will
 resolve to the tip of the work tree's current branch if invoked in a
 work tree, otherwise it will resolve to the repository's HEAD reference.
@@ -1067,7 +1067,7 @@ and HEAD reference, respectively.
 and
 .Qq :head
 can also be used to represent the work tree's base commit
-and HEAD reference, respectively.
+and branch head, respectively.
 The former is only valid if invoked in a work tree, while the latter will
 resolve to the tip of the work tree's current branch if invoked in a
 work tree, otherwise it will resolve to the repository's HEAD reference.