Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation
- From
Julia Evans <julia@jvns.ca>
- Date
- Nov 9, 2026, 21:48 UTC
- Message-ID
- <f7d4600b-909f-4dd7-94da-d525649a9546@app.fastmail.com>
- In-Reply-To
- <xmqq7bio6jb4.fsf@gitster.g>
On Sat, Nov 7, 2026, at 11:25 PM, Junio C Hamano wrote:
Show 24 quoted lines
> "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.
I think it's reasonable to try to explain that in both cases there's something in common.
Here's an idea for how to do that:
In Git, you can always use `HEAD` to refer to the current commit.
But `HEAD` isn't just your current commit: it's also where Git
stores the name of your current branch. `HEAD` can either be:
1. A branch, which is your current branch.
The current commit 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 be a commit ID, because...Show 19 quoted lines
>> 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.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?