Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation
- From
Julia Evans <julia@jvns.ca>
- Date
- Nov 10, 2026, 13:13 UTC
- Message-ID
- <ce9fcde0-2181-4773-9133-f39ea1ebf7bf@app.fastmail.com>
- In-Reply-To
- <xmqqfqx9uqsn.fsf@gitster.g>
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:
Show 13 quoted lines
> * `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.
Show 11 quoted lines
>> 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.