Stefan Sperling <stsp@stsp.name> 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 <https://bsdbox.org>
GPG: F2FF 13DE 6A06 C471 CA80  E6E2 2930 DC66 86EE CF68