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 20, 2026, 12:52 UTC
Message-ID
<1AA9F133-4B0C-4AAC-B296-5C2543C642F2@jvns.ca>
In-Reply-To
<xmqqcxt52xkn.fsf@gitster.g>
Show 19 quoted lines
> On Oct 19, 2026, at 5:24 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> "Julia Evans" <julia@jvns.ca> writes:
> 
>> Let me know if this is a helpful way for you to bring some user perspectives
>> into the conversation. Like I said earlier I don't really think it's possible to
>> discuss how to explain HEAD in a vacuum so maybe these quotes will help!
> 
> It surely is more helpful than "I think it is not better" that is
> not backed by anything.
> 
>> Also if you could give me any ideas for how to reply in a "shorter" way than
>> "I don't think this is clearer" let me know, I can't bring you quotes from user
>> research to justify every single wording choice :)
> 
> IOW, "Trust me" ;-)
> 
> It is often good enough among those who have worked together for
> some time, and you certainly do qualify.
That’s good to hear!
Show 6 quoted lines
>> -  "HEAD is a mysterious thing I never need to know about unless something has
>> g-one wrong, eg. merge conflicts."
> 
> Somebody may have said so, but how does bringing it (together with
> many other examples) up in _this_ discussion help us find a better
> way to explain it to users?
Show 9 quoted lines
> Somebody is clueless about HEAD and does not feel the need to
> understand it until they really need to.  This fact alone, that they
> can get going with such a sketchy understanding and make use of Git
> sufficiently well may be a great thing by itself.  It may support an
> argument that we do not really have to explain what HEAD is to our
> readers.  Is that the argument you are making?
> 
> I won't comment on each and every one of them, but is your point
> that many potential readers do not understand HEAD and doing fine?
I do think that’s true yes.
Show 10 quoted lines
> Of course there are a handful of examples that they do get it, like
> this one.
> 
>> - "HEAD is a reference to a commit, either directly or indirectly. A direct
>> commit is just in detached state, where HEAD is looking at the commit itself.
>> An indirect reference would be the case you’ve shown above, where HEAD is a
>> reference to a reference."
> 
> But what did you want to illustrate again?  I am little bit fuzzy on
> what you wanted to achieve by dumping these at me.

Mostly to give an idea of the kind of language users are using when talking about Git, to explain why saying “records” isn’t appropriate and why more generally it might not be possible for me to accept your suggested wordings for how to explain things verbatim. For example elsewhere in this thread you suggested another wording and seemed to find it hard to understand why I wouldn't replace what Marie and I had written with your suggested “better” wording.

Also I have the impression that our assumptions about what Git users know and what users need are quite different, and I thought it might help illustrate why I might have a different point of view.

I agree these kinds of comments can be a little unsettling to read when some of them are “wrong”. I believe that these comments are from folks who are quite a bit more knowledgeable than the average Git user.

It’s my job to sort through them and figure out how to write the docs with them in mind and I’m definitely not asking you to do that :) I do need some trust though.

Previous: Junio C HamanoNext: Julia Evans
Message 6 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.