From: Julia Evans Date: Wed, 11 Nov 2026 21:45:34 GMT Subject: Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation Message-ID: In-Reply-To: > 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? Yeah I agree the "it's the parent of the next commit" would be distracting unless there's a specific reason we need to include it. I agree "the state from which your current changes started" isn't right but I think if we reinterpret it as "the current commit you have checked out" (which I think has the same or a very similar meaning) then it'll seem familiar to folks and might even help. > 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. Thanks, I took this language. I left out "clobbering an existing branch" because I couldn't think of a reason why someone would clobber an existing branch to check out an old version of their code. - Julia