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

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

From
Julia Evans <julia@jvns.ca>
Date
Nov 13, 2026, 12:45 UTC
Message-ID
<36e73720-287f-47a5-bd3f-dc53629ac968@jvns.ca>
In-Reply-To
<xmqqfqx5foxd.fsf@gitster.g>
On 2026-11-12 9:25 p.m., Junio C Hamano wrote:
Show 25 quoted lines
> Julia Evans <julia@jvns.ca> writes:
>
>>> I think the central difference is that you
>>> seem to consider detached HEAD state is only about pure sightseeing
>>> while it was designed to allow touching and breaking.  If the user
>>> is not making any changes, of course it does not make sense to talk
>>> about "your current changes" or "next commit".  But detached HEAD is
>>> not limited to such a world view.
>> We say very clearly that you can make commits while in detached HEAD
>> state so I don't think there's any danger of readers not realizing
>> that's possible.
>>
>>     But it's important to know that if you create new commits while in
>>     detached HEAD state, those commits won't be on a branch.
> Yeah, but that isn't the purpose of mentioning "next commit" etc. to
> make readers realize that.  So I am not sure what you want to say
> with that.
>
> The mention of "your current work" (started at the HEAD) and "next
> commit" is to lay groundwork to explain what happens when they make
> that commit, and how it is different when they are on detached HEAD,
> in contrast to when they are on a branch.  After all, what we were
> discusssing is an improved explanation on detached HEAD, and your
> commits not affecting any of your branch *is* the most important
> aspect of what detached HEAD gives you
I read this a few times and it's hard for me to tell what the issue being raised is.
Are you saying that we're not explaining all the details from "`HEAD` can store either a branch or commit ID" to "if you create new commits while in detached HEAD state, those commits won't be on a branch"?
That's intentional, and I can explain the reasons for it if you'd like. I don't think this is the appropriate document for that information.
Here's an idea to resolve this:
1. Add something to the commit message explaining why we're not giving a full detailed explanation anymore
2. Add some extra info to gitdatamodel.adoc to make sure the information is incldued there, since I think that's the appropriate document.
3. Add a "see also gitdatamodel..." to the end of the section for folks who want more information about how HEAD and branches work together.
Previous: Junio C HamanoNext: Junio C Hamano
Message 36 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.