From: Julia Evans Date: Mon, 09 Nov 2026 21:48:36 GMT Subject: Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation Message-ID: In-Reply-To: On Sat, Nov 7, 2026, at 11:25 PM, Junio C Hamano wrote: > "D. Ben Knoble" 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... >> 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?