Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation
- From
D. Ben Knoble <ben.knoble@gmail.com>
- Date
- Nov 7, 2026, 20:06 UTC
- Message-ID
- <CALnO6CBGcG42NxtpuPaJVrzAMC=J8iVstsHCSi6vDQhDmFJ-Kw@mail.gmail.com>
- In-Reply-To
- <xmqqh5ile4h4.fsf@gitster.g>
Hi all,
I've read through this thread a few times, and I'm still interested in seeing the detached HEAD manual land. It seems like the following need to happen?
1. We are waiting on a reroll from Julia with the SQUASH??? commit or something like it applied (https://lore.kernel.org/git/xmqqse25cni7.fsf@gitster.g/) 2. The discussion about how to describe HEAD needs resolved.
On Fri, Oct 16, 2026 at 5:11 PM Junio C Hamano <gitster@pobox.com> wrote:
Show 13 quoted lines
> > Just to leave a record, so that we have better chance remembering > the suggested improved text, here are what I think the first two > paragraphs should be replaced with. > > HEAD records the state from which your current changes started. > This can be a branch (the "current branch"), or it be a commit, > (in which case HEAD is "detached"). > > In the detached HEAD state, you can safely build, run, and > experiment with any historical version of your codebase, without > having to worry about clobbering your branches, and you do not > have to clutter your repository with temporary branches.
Here's what Junio suggested^, and here's what v4 has
+`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.
I do not personally think it's worth focusing on "the state from which your current changes started" (even leaving aside the "what if I have no changes?" moment), in part because I don't think that's how most users conceive of HEAD. Other than that detail, I think the first paragraphs of each option coincide.
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? It might be distracting, and could make its way into some kind of admonition/aside if need be?
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
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. 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.
> Having said all that, the changes between v3 and v4 look OK to me, > so let me update the previous copy I have with this version.
Otherwise, we're approaching a finish here?
-- D. Ben Knoble