Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation
- From
Julia Evans <julia@jvns.ca>
- Date
- Oct 13, 2026, 11:48 UTC
- Message-ID
- <5dad29e9-24e6-494a-9b0f-701af856ae69@app.fastmail.com>
- In-Reply-To
- <cb482e6d-0c76-4f34-b72c-03b5234d4f37@app.fastmail.com>
To make this process easier, I'm going to first deal with factual issues (like any mistakes or ideas for more information content to include). I'll mark comments that are suggestions for how to make the wording more clear with "style comment" to potentially address later.
On Wed, Oct 7, 2026, at 3:02 PM, Kristoffer Haugsbakk wrote:
>> Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation > > This change adds a standalone guide as well. The subject “just” make it > sound like you are rewriting the text where it is.
Yes. I ran out of space while writing the subject line. Happy to make changes to how the commit is structured if that would be better.
Show 6 quoted lines
>> Documentation/detached-head.adoc | 43 ++++++++++ >> Documentation/git-checkout.adoc | 129 +---------------------------- >> Documentation/gitdetachedhead.adoc | 14 ++++ > > Why in one word instead of hyphenating `detached-head`? > (gitdetached-head(7))
Currently the guides are all one word with no hyphens. Happy to use a different style if folks think we shouldn't use the current naming convention for the guides
Show 5 quoted lines
>> advice.c | 1 + >> command-list.txt | 1 + > > This is missing meson/Makefile changes in order to make > gitdetachedhead(7).
Thanks, will fix.
Show 24 quoted lines
>> 5 files changed, 60 insertions(+), 128 deletions(-) >> create mode 100644 Documentation/detached-head.adoc >> create mode 100644 Documentation/gitdetachedhead.adoc >> >> diff --git a/Documentation/detached-head.adoc >> b/Documentation/detached-head.adoc >> new file mode 100644 >> index 0000000000..1e00712124 >> --- /dev/null >> +++ b/Documentation/detached-head.adoc >> @@ -0,0 +1,43 @@ >> +`HEAD` is where Git stores your current branch. `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. >> +For example, it lets you look at an old version of your code >> +(with `git checkout COMMIT_ID`). > > Maybe go straight to `git switch --detached COMMIT_ID` here.
Style comment.
Show 28 quoted lines
> It is very useful to describe detached `HEAD` as something that you can > fall into by accident. It is very much perenially needed. And this > paragraph explains a legitimate, intentional use. > > But a dedicated guide is also an opportunity to not only acknowledge hey > there is a use here but to explain actively why it is > convenient. Because one thing is “detached `HEAD`” as a conceptual, > scary blind alley where my work might get garbage collected. But only > thinking in terms of branches and tags can lead to a dead end of only > thinking of Git as: > > 1. The state of our collective work right now (“main”) > 2. Our important waypoints (tags) > > So before you lead them out of the maw of the garbage incinerator, you > can help level up their use of Git by explaining why checking out > commits freely is useful with an example of why they would do that. > > 1. Finding buggy commits manually (this would probably end with a > mention of git-bisect(1)) > 2. Testing that each commit on a branch (forked from `main`) passes the > test suite > 3. Browsing an interesting commit manually instead of pointing `git > grep` at the commit (or something) > 4. Just being on `origin/main` instead of having a `main`. I never > update “main”. So why would I go to the trouble of keeping it up to > date? I can just “be on” `origin/main` (detached on whatever that > points to).
This is a nice list of reasons being in detached head state, thanks. Not sure if it will be helpful to include or not though.
Show 33 quoted lines
> See also StackOverflow questions about how to update hundreds of > local branches with git-pull(1) or something. Why? They do not have > hundreds of local branches that they are authoring. They just want > those branches by other people to be updated. But that is not > necessary for anything. You just need the remote-tracking > branches. Including if you want to check them out (on detached > `HEAD`). > > This conceptual dead end (of no “detached `HEAD`) could manifest itself > like this: > > • “I must always be on a branch” > • “Therefore I can only check out old commits by first creating a > branch” > • “Every interesting commit must have a tag for posteriety so we can > name it” (you just need the hash, even abbreviated) > • “We must tag this commit for the build so we can name the build” (you > can just use the hash or use part-of-the-hash with git-describe(1)) > >> +The only problem is that if you create new commits while in detached >> +HEAD state, those commits won't be on a branch. This makes those new >> +commits much harder to find later. Also, Git considers commits that >> +aren't on any branch (or a tag or other reference) to be garbage. >> +Git will eventually permanently delete those "garbage" commits during >> +garbage collection. > > Maybe this is where you should mention git-reflog(1) (and git-log(1) > maybe (see later)). > > Maybe this about garbage collection could be tempered with a mention of > the however-many default days for reflog expiry. It’s such a long time > that if any of my commits get garbage collected... I probably didn’t > need them.
Good idea, will mention it's 90 days by default.
Show 6 quoted lines
>> + >> +There are 3 main ways you can end up in detached HEAD state >> +unintentionally: > > I would say “typical” instead of “main”. As in these things are the > typical gateways to this state (unintentionally).
Style comment
Show 23 quoted lines
>> + >> +The easiest way to avoid accidentally ending up in detached HEAD state >> +is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to >> +switch branches. `git switch` won't let you detach unless you >> explicitly >> +pass the `--detach` argument. >> + >> +To get back onto a branch, you can: >> + >> +1. Switch to the branch you want to be on, with `git switch BRANCHNAME`. >> +2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`. >> + You might want to do this if you've created new commits, so that you can >> + find the commit later and so that it won't be garbage collected. >> + >> +If you create commits in detached HEAD state that aren't on a branch, >> +you can find them later using linkgit:git-reflog[1]. > > Okay, but it’s more immediate and obvious to use `git log`. Say you > created three commits by accident while not on a branch. Then they will > be immediately um logged. > > git-reflog(1) is excellent too of course, mostly because you are likely > to find all of them if you did a lot of weird checkouts in one session.
Going to deal with this another way