From: Julia Evans Date: Fri, 13 Nov 2026 12:45:22 GMT Subject: Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation Message-ID: <36e73720-287f-47a5-bd3f-dc53629ac968@jvns.ca> In-Reply-To: On 2026-11-12 9:25 p.m., Junio C Hamano wrote: > Julia Evans writes: > >>> I think the central difference is that you >>> seem to consider detached HEAD state is only about pure sightseeing >>> while it was designed to allow touching and breaking. If the user >>> is not making any changes, of course it does not make sense to talk >>> about "your current changes" or "next commit". But detached HEAD is >>> not limited to such a world view. >> We say very clearly that you can make commits while in detached HEAD >> state so I don't think there's any danger of readers not realizing >> that's possible. >> >>   But it's important to know that if you create new commits while in >>   detached HEAD state, those commits won't be on a branch. > Yeah, but that isn't the purpose of mentioning "next commit" etc. to > make readers realize that. So I am not sure what you want to say > with that. > > The mention of "your current work" (started at the HEAD) and "next > commit" is to lay groundwork to explain what happens when they make > that commit, and how it is different when they are on detached HEAD, > in contrast to when they are on a branch. After all, what we were > discusssing is an improved explanation on detached HEAD, and your > commits not affecting any of your branch *is* the most important > aspect of what detached HEAD gives you I read this a few times and it's hard for me to tell what the issue being raised is. Are you saying that we're not explaining all the details from "`HEAD` can store either a branch or commit ID" to "if you create new commits while in detached HEAD state, those commits won't be on a branch"? That's intentional, and I can explain the reasons for it if you'd like. I don't think this is the appropriate document for that information. Here's an idea to resolve this: 1. Add something to the commit message explaining why we're not giving a full detailed explanation anymore 2. Add some extra info to gitdatamodel.adoc to make sure the information is incldued there, since I think that's the appropriate document. 3. Add a "see also gitdatamodel..." to the end of the section for folks who want more information about how HEAD and branches work together.