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

[Junio C Hamano <gitster@pobox.com>]

"D. Ben Knoble" <ben.knoble@gmail.com> writes:

> +`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:
> +
> +1. A branch, which is your current 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 be a commit ID, because
> +it lets you easily check out an old version of your project. For
> +example, a data scientist could use this to run an old version of a
> +data pipeline or a programmer could use this to figure out when a bug
> +was introduced.
> ...
> There are some quotes which use the "it's the parent of the next
> commit" mental model, though, so we could include a comment on that?

"From which your current changes started" is exactly that.  HEAD is
where you started from (and can come back to, if you get lost after
botching your working tree state).  Your next commit is built on top
of it, and then that new commit becomes your current commit.

This is why it is useful for users to realize that HEAD is simply
where you started from, regardless of where you are going.

> The second paragraphs differ a bit, with Junio's containing some bits
> about clobbering extant branches and not needing temporary branches. I
> think we could work something in there, like
> ...
>     this to figure out when a bug was introduced. By detaching
>     `HEAD`, you don't need to worry about clobbering an existing
>     branch or creating a temporary branch.
>
> ? I suppose we could also be more explicit ("build, run, and
> experiment"), if we wanted, but this is a good example to start from.

I assume you mean the last two lines?  I do appreciate that addition.

However, we should avoid saying "useful for HEAD to be a commit ID".
Being a commit ID is not the notable characteristic of a detached
HEAD; the fact that it directly refers to a commit is what gives us
these useful features.  Recording a hexadecimal commit object name
(instead of a refname of a branch) is a mere implementation detail
of that direct reference.

Since Julia's introductory paragraph already established the term
"detached HEAD" very well, there is no need to resort to a roundabout
phrasing like "useful for HEAD to be a commit ID".  I suggest
rewriting the beginning of that paragraph to start with:

    It can be useful for the HEAD to be directly refering to a
    commit (instead of indirectly referring to a commit by naming
    the current branch).

This introduces the remainder of her paragraph much better, and
makes your addition about not needing to worry about clobbering
existing branches or consuming temporary refs easier to understand.

> Otherwise, we're approaching a finish here?

I hope so.  The document overall is moving in the right direction,
and I just want to see these minor technical descriptions improved.