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

Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation

From
D. Ben Knoble <ben.knoble@gmail.com>
Date
Nov 7, 2026, 20:06 UTC
Message-ID
<CALnO6CBGcG42NxtpuPaJVrzAMC=J8iVstsHCSi6vDQhDmFJ-Kw@mail.gmail.com>
In-Reply-To
<xmqqh5ile4h4.fsf@gitster.g>
Hi all,

I've read through this thread a few times, and I'm still interested in seeing the detached HEAD manual land. It seems like the following need to happen?

1. We are waiting on a reroll from Julia with the SQUASH??? commit or
something like it applied
(https://lore.kernel.org/git/xmqqse25cni7.fsf@gitster.g/)
2. The discussion about how to describe HEAD needs resolved.
On Fri, Oct 16, 2026 at 5:11 PM Junio C Hamano <gitster@pobox.com> wrote:
Show 13 quoted lines
>
> Just to leave a record, so that we have better chance remembering
> the suggested improved text, here are what I think the first two
> paragraphs should be replaced with.
>
>     HEAD records the state from which your current changes started.
>     This can be a branch (the "current branch"), or it be a commit,
>     (in which case HEAD is "detached").
>
>     In the detached HEAD state, you can safely build, run, and
>     experiment with any historical version of your codebase, without
>     having to worry about clobbering your branches, and you do not
>     have to clutter your repository with temporary branches.
Here's what Junio suggested^, and here's what v4 has
+`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".
+
+It can sometimes be useful for `HEAD` to be a commit ID, because
+it lets you easily check out an old version of your project. For
+example, a data scientist could use this to run an old version of a
+data pipeline or a programmer could use this to figure out when a bug
+was introduced.

I do not personally think it's worth focusing on "the state from which your current changes started" (even leaving aside the "what if I have no changes?" moment), in part because I don't think that's how most users conceive of HEAD. Other than that detail, I think the first paragraphs of each option coincide.

There are some quotes which use the "it's the parent of the next commit" mental model, though, so we could include a comment on that? It might be distracting, and could make its way into some kind of admonition/aside if need be?

The second paragraphs differ a bit, with Junio's containing some bits about clobbering extant branches and not needing temporary branches. I think we could work something in there, like

    It can sometimes be useful for `HEAD` to be a commit ID,
    because it lets you easily check out an old version of your
    project. For example, a data scientist could use this to run
    an old version of a data pipeline or a programmer could use
    this to figure out when a bug was introduced. By detaching
    `HEAD`, you don't need to worry about clobbering an existing
    branch or creating a temporary branch.

? I suppose we could also be more explicit ("build, run, and experiment"), if we wanted, but this is a good example to start from.

> Having said all that, the changes between v3 and v4 look OK to me,
> so let me update the previous copy I have with this version.
Otherwise, we're approaching a finish here?
-- 
D. Ben Knoble
Previous: Junio C HamanoNext: Junio C Hamano
Message 24 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.