From: Mark Jamsek Subject: Re: got.1: avoid work tree "HEAD" terminology To: Stefan Sperling Cc: gameoftrees@openbsd.org Date: Mon, 17 Jul 2023 20:25:31 +1000 Stefan Sperling wrote: > 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? :tip has the advantage of being shorter too. However, given its behaviour you noted as resolving to the repository's HEAD when not in a work tree, I think it is slightly better to keep it as :head. In addition, "head" is generally used in git-speak to refer to the branch's head meaning tip commit, so it will be familiar to that demographic. OTOH, "tip" is used in fossil. I wouldn't object to the change; just expressing why I think :head is better suited. > In any case, I want to apply the wording change below: ok for the diff > 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. -- Mark Jamsek GPG: F2FF 13DE 6A06 C471 CA80 E6E2 2930 DC66 86EE CF68