# Julia Evans's rewrite of the detached HEAD documentation gets a first round of review

_The patch replaces the explanation in `git checkout` with a standalone guide so advice messages can point to it; guide naming and wording are under discussion._

Section: Patches. Edition of 2026-10-14. Written by an AI editor from the thread "[PATCH] doc: checkout: rewrite detached HEAD state explanation" (53 messages): https://gitlist.dev/t/66484

Julia Evans's patch rewrites the detached HEAD explanation in the `git checkout` docs and puts it in its own guide. Her commit message lists problems with the old text. It says detached HEAD is useful without saying why, takes many paragraphs to say what it is, doesn't explain how users end up there by accident, doesn't mention that `git switch` makes accidental detaching harder, and has too many confusing diagrams. A standalone guide would let advice messages point to it.

In her reply to review, Evans said she is handling factual issues first and marking comments about wording clarity as "style comment" to defer. She suggested a second revision after merging, informed by user feedback. She has already removed the word "unintentionally" and added a mention of a warning she called a good example of Git helping users avoid problems.

Naming drew discussion. Evans said she would change the name after learning her assumption was wrong, and suggested the `gitmergeconflicts` page in her other series might be renamed `gitmerge-conflicts`. She prefers `git help detached-head` to `git help detachedhead`, though she herself uses `man <page>`.

Kristoffer Haugsbakk said he was confused, because `git help --guides` shows hyphenated names such as `core-tutorial` and `remote-helpers`. Evans also separately wondered whether Git's man pages should refer to each other in a way that matches how people actually look pages up, since `man git-config` and `git help config` use different forms. That broader question is not settled.
