From: Junio C Hamano Date: Tue, 10 Nov 2026 06:46:48 GMT Subject: Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation Message-ID: In-Reply-To: "Julia Evans" writes: > 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". > ... > 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? Yes, I find it highly misleading, and otherwise I wouldn't be discussing this patch. I think the part I find it problematic the most in HEAD is a branch vs HEAD is a commit ID is that HEAD *IS NOT* either of these things. HEAD may record one of these kinds of things but it never is a branch or an commit object name. And HEAD records one of these kinds of things to either directly or indirectly refer to a commit that is currently checked out. That is why I want to see the first description of the above to serve as a solid base to convey these points, with later descriptions we build on top: * `HEAD` can record either (1) a branch, or (2) a commit object name. * The purpose of HEAD doing so is to refer to a commit that is currently checked out, either directly or indirectly. * The latter (i.e., the direct reference) may be unfamiliar to users. It is called "detached HEAD" state. * The commit referred to by the HEAD will become the parent of the commit you create. When your HEAD records a branch, its tip is advanced. Otherwise no branch is affected. Either case, HEAD now refers to the commit you newly created. And I find that saying "HEAD is a branch" or "HEAD is a commit" is misleading and does not help that goal. HTH.