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 19, 2026, 14:05 UTC
Message-ID
<9c15d34e-406d-4702-b606-da102a340e71@app.fastmail.com>
In-Reply-To
<xmqqik3da2bs.fsf@gitster.g>
On Wed, Oct 7, 2026, at 12:43 PM, Junio C Hamano wrote:
Show 20 quoted lines
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> 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".
>
> HEAD is branch which can either be a branch or something else?
>
>     HEAD records the state from which your current changes started.
>     This can be a branch (the "current branch"), or it may not be
>     associated with any concrete branch (in which case HEAD is
>     "detached").

You asked for a more detailed explanation for why I don't think this is clearer, so here's my best attempt.

It's important to use the same words that users might themselves use to describe a concept, for example, "means", "is", "points at", "is a reference to", etc.

In March 2024 I asked experienced Git users to explain their impressions of what HEAD means, and I got a lot of really great replies. I've included a bunch of them at the end of this email. I think it's a really great example of how there are a lot of "technically wrong but useful" ideas about how things in Git work. When I think about how to explain HEAD, it's in the context of that research I did around March 2024.

Your suggestion ("HEAD records the state from which your current changes started." uses pretty different language ("records") from the language users are using in the quotes below. I think it would be great if we could make a correct statement that builds on the ideas that users already have about HEAD, using the kind of language that they themselves would use to describe the ideas.

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!

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 :)

-  "HEAD is a mysterious thing I never need to know about unless something has
g-one wrong, eg. merge conflicts."
-"the HEAD Commit in my Clone of our Repo is the Commit at the top of: git log"
- "Other than seeing "detached head" sometimes and panicking, I don't really know
what Head is. And I used git quite a bit over the years 😅"
- "HEAD points at the latest commit of the branch you're viewing. Except when it
doesn’t. There's attached and detached head situations and that's where it gets
somewhat confusing."
- "It is a… thing… which “points at”… the newest (?) commit that “”I”” am ¿on?"
- "it's a pointer to the latest commit on the currently checked out branch"
- "HEAD means (a pointer to) the (commit hash of the) checked-out branch"
- "HEAD is the reference to the current commit that's checked out."
- "The commit which will be the parent of the next commit you create, at least
using "git commit" command."
- "unless I am taking special pains to deliberately edit history, HEAD will
(1) become the first parent of whichever commit I write next AND (2) names the
branch where that commit will be appended".
- "it's where you "currently are" on a branch (or maybe in the whole repo? not
sure on head vs HEAD)"
- "the most recent commit on the branch you're working on"
- "Insertion point for new commits."
- "HEAD is a "commit-like"? that refers to the commit? that was used? to populate
the working directory?"
- "a file in .git that points to either a commit or a ref; git uses this as the
"current" commit for things like git status"
- "HEAD is a symbolic reference to another reference ... I don't have a mental
model for what happens if HEAD points at a tag ref"
- "my impression is that it's the commit I'm currently looking at. It's attached
if that commit is the tip of a branch (means I can make new commits), and it's
detached when that is not the case."
- "it's a file that contains the currently checked-out commit id or branch name?"
- "Sometimes I think I kinda understand. Then I remember the existence of the
phrase “detached HEAD”."
- "HEAD is what is going to be the parent of your next commit"
- "HEAD points at the latest commit in the branch you're currently in. So if
you're in main, it's the latest commit there. If you're in dev, it's the latest
commit in that branch.  ... But if you're in a branch and not on the latest
commit, HEAD still points at the latest commit."
- "HEAD is shorthand for "most recent commit on current branch"."
- "it means "the commit I have checked out at this very moment"."
- "I am quite unconfident as I only ever see it mentioned when running 'git
reset'. From that context, something like "the most recent 'saved' state of the
repo before you made any 'unsaved' modifications""
- "A pointer to the *latest* commit (not necessarily "current" commit) in
whatever I'm working on. ... the latest commit" is whatever is conceptually "at
the end" of the branch's timeline."
- "HEAD is used as a pointer to the current commit, while it is (usually) pointer
to the current branch, which head (lowercase) points to the current commit - one
layer of indirection."
- "I think of it as pointing to the next place where a commit would appear if I
made 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."
- "Its like... the thing at the end of the branch, right? Like... the current
commit."
- "I think in practice it is the last ref checked out. Sometimes it is the SHA of
the revision (detached head), sometimes it is a ref (branch or tag)."
- "HEAD means the head of a specific branch, which seems to be the default branch
in github?"
- "the git command that involves HEAD which I use most often is `git push origin
HEAD` ... I'd definitely struggle to articulate why this works the way that
it does"
Previous: Julia EvansNext: Junio C Hamano
Message 4 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.