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, 12:54 UTC
Message-ID
<31f8c254-328b-405f-bc26-b077fa57b5ef@app.fastmail.com>
In-Reply-To
<xmqqik3da2bs.fsf@gitster.g>

Thanks for the review. I'm going to mark comments that I feel are about style issues (like "could this be explained in a more clear way?") as just "style comment" to deal with later.

In general if we really want to make sure that this is as clear as possible, I think it would be most effective to do a second revision later (after merging this) where we get feedback from users and find out what folks are confused by.

On Wed, Oct 7, 2026, at 12:43 PM, Junio C Hamano wrote:
Show 15 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?
Style comment. Probably this is the one I'd prioritize the highest.
Show 15 quoted lines
>     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")
>> +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`).
>
> To "look at" an older state is more versatile than simply running
> 'git show COMMIT_ID:path', as it allows you to do anything you can
> do on a branch, such as building and testing.  Thus,
>
>  	A detached HEAD is useful when you want to tentatively visit
> 	an old state with 'git checkout --detach v0.1', without
> 	having to create a dedicated branch for it.
Style comment.
Show 8 quoted lines
>> +The only problem is that if you create new commits while in detached
>> +HEAD state, those commits won't be on a branch.
>
> I would suggest rephrasing "The only problem" to "One caveat is" or
> something.  When sightseeing and experimenting, the ability to
> create throw-away commits without the need to clean them up later,
> or to invent a unique name for a temporary branch, is not a problem.
> It is an advantage.
Style comment.
Show 23 quoted lines
>> 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.
>
> Correct.
>
> Perhaps it is better to clarify this by adding "after you leave
> the detached HEAD state" after "to find later".  While you are in
> the detached HEAD state, you can run 'git log' to find the commits
> you created there, as you can do everything you normally can on a
> branch, or use 'git reflog @{now}' for that matter.
>
>> +There are 3 main ways you can end up in detached HEAD state
>> +unintentionally:
>> +
>> +1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID
>> +2. `git checkout v1.3`, where v1.3 is a tag name
>
> These I wouldn't call "unintentionally".  They are documented and
> supported ways to do so, and will remain to be so.  "unknowingly"
> may be a more fair way to call these gotchas, though.
Thanks, removed "unintentionally".
Show 9 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.
>
> Correct, but the motivation to 'avoid accidentally ending up' may
> want to be spelled out.  Most often checking out a tag is to go
> sightseeing, where you do not want to 'avoid' detached HEAD.
Style comment.
Show 28 quoted lines
>> +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.
>
> Very good.
>
>> +If you create commits in detached HEAD state that aren't on a branch,
>> +you can find them later using linkgit:git-reflog[1].
>
> This, as you already said, is "much harder to find later" option.
> There should be a better recovery option described here before
> resorting to "git reflog HEAD" after you switched back.  E.g.,
>
>     If you have created commits in detached HEAD state and then
>     switched away from the state, all is not lost.  "git checkout"
>     would have give you a warning message, like this:
>
> 	Warning: you are leaving 2 commits behind, not connected to
> 	any of your branches
>
> 	c816689 typofix the previous
> 	8e1bff5 decsribe detached HEAD state better
>
>     You can create branches to keep them, e.g., "git branch saved c816689",
>     by using the commit object names left there.

Thanks, added a mention of this warning. It's a really nice example of the ways Git helps avoid issues.

Show 22 quoted lines
>> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
>> index 2aefea0228..4e9e94e24d 100644
>> --- a/Documentation/git-checkout.adoc
>> +++ b/Documentation/git-checkout.adoc
>> @@ -376,135 +376,8 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
>>  [[DETACHED_HEAD]]
>>  DETACHED HEAD
>>  -------------
>> +include::detached-head.adoc[]
>
> Losing the diagrams is a bit concerning.  However, if the intention
> is to have readers learn how HEAD refers to a branch pointing at a
> commit with history structured as a DAG elsewhere in a more basic
> concepts guide, I suspect that it would actually work better.  This
> could even be reduced to a simple "see also" pointer to that other
> guide.
>
> If an existing user only uses 'switch' and never reads 'git help
> checkout', they are already not seeing these diagrams, or perhaps
> they learned the concepts elsewhere.  They still manage to
> understand Git well enough to make use of it, so perhaps this
> approach is OK.  I dunno.

Thanks, good idea to give people a pointer to more info about HEAD. I'll try adding a pointer to `git help datamodel`.

I'm not against adding diagrams, but I think if we want to add diagrams that should be a separate project where we actually get feedback from users. Similarly for explaining `HEAD` in more detail.

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