Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation

["Julia Evans" <julia@jvns.ca>]

I'm going to reply to this email a bit out of order because I want to say
this is a great list first:

> That is why I want to see the first description of the above to
> serve as a solid base to convey these points, with later
> descriptions we build on top:

>  * `HEAD` can record either (1) a branch, or (2) a commit object
>     name.
>
>  * The purpose of HEAD doing so is to refer to a commit that is
>    currently checked out, either directly or indirectly.
>
>  * The latter (i.e., the direct reference) may be unfamiliar to
>    users.  It is called "detached HEAD" state.
>
>  * The commit referred to by the HEAD will become the parent of the
>    commit you create.  When your HEAD records a branch, its tip is
>    advanced.  Otherwise no branch is affected.  Either case, HEAD
>    now refers to the commit you newly created.

I'm not sure if we need to communicate the last point here, but
definitely the goal is to communicate the first 3 points.

> ... And HEAD records one of these kinds of things to either directly or
> indirectly refer to a commit that is currently checked out.

now back to the beginning:

> And I find that saying "HEAD is a branch" or "HEAD is a commit" is
> misleading and does not help that goal.

>> Saying "it's a commit ID" is a simple way to say that it directly refers
>> to a commit in a small number of words. I'm not sure what your goal is
>> here, do you think that statement is somehow misleading to users?
>
> Yes, I find it highly misleading, and otherwise I wouldn't be
> discussing this patch.
>
> I think the part I find it problematic the most in
>
>     HEAD is a branch vs HEAD is a commit ID
> is that HEAD *IS NOT* either of these things. 

The all caps "IS NOT" doesn't help me understand why it's misleading
but it does tell me you feel strongly about this so I assume it's important :)
It might help to give an example of something a user might believe about
HEAD that is not true as a result of reading this.
I'll try a different suggestion and see if that helps though.

Often I approach this issue by talking about Git's implementation directly,
like ".git/HEAD is a file that can contain either a branch name or commit ID".
Usually I think it's not good to talk about the implementation that way,
but I think HEAD might be an exception because in practice I've found that
users find the explanation of the implementation helpful.

Here's a version which handles the issue by talking about `.git/HEAD`.

  In Git, you can always use `HEAD` to refer to the commit you have
  checked out. But HEAD is also where Git stores the name of your current
  branch. Internally, `.git/HEAD` is a file that contains either:
  
  1. A branch name, which is your current branch.
     The commit you have checked out is the latest commit on that branch.
  2. A commit ID, when you don't have a current branch.
     This is called "detached HEAD state".
  
  It can sometimes be useful for `HEAD` to refer to a commit directly
  because it lets you easily check out an old version of your project.
  ...

But talking about the implementation in this way isn't a good idea (even though
it might have been okay 10 years ago) because immediately as soon as we make the
reftable backend the default, users will try to look at `.git/HEAD` and it won't
be there, which will cause confusion.

We could talk about `git symbolic-ref HEAD` but that introduces a whole
other can of worms of "what is a symbolic ref" and I don't know is helpful.

> HEAD may record one
> of these kinds of things but it never is a branch or an commit
> object name.

What does the verb "record" mean to you? I've seen you and other folks in the
Git project use a lot but I've never totally understood what it's intended to
mean. I haven't seen it used in this way outside of the Git project.

Like I said before in this thread, it's important to use verbs that
users themselves might use to describe a concept (references, points to, etc).
Does "records" mean the same thing as "references" or "points to" from your
perspective? My guess is no, because "references" and "points to" can also refer
to indirect references, and I think "records" may mean something more specific.
Maybe it means something like "there's an abstract key-value store in Git where
the key is 'HEAD' and the value is a branch name or commit ID"?

"Records" is not a good word to use to communicate with users about
this topic because the meaning of the verb won't be understood.