git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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
Previous: Kristoffer HaugsbakkNext: Kristoffer Haugsbakk
Message 9 of 53 in “doc: checkout: rewrite detached HEAD state explanation”
  1. doc: checkout: rewrite detached HEAD state explanationJulia Evans via GitGitGadget, Oct 7, 2026
  2. Junio C HamanoOct 7, 2026
  3. Julia EvansOct 13, 2026
  4. Julia EvansOct 19, 2026
  5. Junio C HamanoOct 19, 2026
  6. Julia EvansOct 20, 2026
  7. Julia EvansOct 20, 2026
  8. Kristoffer HaugsbakkOct 7, 2026
  9. Julia EvansOct 13, 2026
  10. Kristoffer HaugsbakkOct 13, 2026
  11. Julia EvansOct 13, 2026
  12. Julia EvansOct 13, 2026
  13. doc: checkout: rewrite detached HEAD state explanationJulia Evans via GitGitGadget, Oct 13, 2026
  14. Junio C HamanoOct 14, 2026
  15. Julia EvansOct 14, 2026
  16. doc: checkout: rewrite detached HEAD state explanationJulia Evans via GitGitGadget, Oct 15, 2026
  17. Junio C HamanoOct 15, 2026
  18. Julia EvansOct 16, 2026
  19. Junio C HamanoOct 16, 2026
  20. Julia EvansOct 16, 2026
  21. Junio C HamanoOct 16, 2026
  22. doc: checkout: rewrite detached HEAD state explanationJulia Evans via GitGitGadget, Oct 16, 2026
  23. Junio C HamanoOct 16, 2026
  24. D. Ben KnobleNov 7, 2026
  25. Junio C HamanoNov 8, 2026
  26. Julia EvansNov 9, 2026
  27. Junio C HamanoNov 10, 2026
  28. Julia EvansNov 10, 2026
  29. Julia EvansNov 11, 2026
  30. Ben KnobleNov 12, 2026
  31. Junio C HamanoNov 12, 2026
  32. Julia EvansNov 12, 2026
  33. Junio C HamanoNov 12, 2026
  34. Julia EvansNov 12, 2026
  35. Junio C HamanoNov 13, 2026
  36. Julia EvansNov 13, 2026
  37. Junio C HamanoNov 13, 2026
  38. Julia EvansNov 13, 2026
  39. Julia EvansNov 13, 2026
  40. Junio C HamanoNov 14, 2026
  41. Julia EvansNov 14, 2026
  42. Julia EvansNov 13, 2026
  43. Junio C HamanoNov 13, 2026
  44. Julia EvansNov 13, 2026
  45. Junio C HamanoNov 14, 2026
  46. Junio C HamanoOct 16, 2026
  47. doc: checkout: rewrite detached HEAD state explanationJulia Evans via GitGitGadget, Nov 11, 2026
  48. Junio C HamanoNov 11, 2026
  49. Julia EvansNov 12, 2026
  50. Junio C HamanoNov 12, 2026
  51. doc: checkout: rewrite detached HEAD state explanationJulia Evans via GitGitGadget, Nov 12, 2026
  52. doc: add new detached HEAD state guideJulia Evans via GitGitGadget, Nov 16, 2026
  53. Junio C HamanoNov 16, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.