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

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

From
Junio C Hamano <gitster@pobox.com>
Date
Oct 15, 2026, 22:39 UTC
Message-ID
<xmqqecdqk2qr.fsf@gitster.g>
In-Reply-To
<pull.2250.v3.git.1792097882327.gitgitgadget@gmail.com>
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>     non-changes: Left these phrases alone because I don't think the proposed
>     changes would make it more clear.

Those who contributed their time to review this document did so believing they were suggesting improvements. Simply dismissing their feedback as "style" in 'v2' without explaining what you disliked about their suggestions is unhelpful. It is hard to know what to make of a dismissal that lacks any supporting reasoning, other than "I don't think".

Show 11 quoted lines
> diff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc
> new file mode 100644
> index 0000000000..d8e59e10c6
> --- /dev/null
> +++ b/Documentation/detached-head.adoc
> @@ -0,0 +1,57 @@
> +`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".

Differences between v1 and v3 did not make much improvement in this area, though. The phrase "branch or commit" highlights the distinction, but it fails to clarify what is common to both, which is equally important.

Perhaps restarting from something along this line
    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").

and polishing further may take us to a better end state. An important distinction that is not captured in the above (or your version) that we may want to cover is that when you are on a branch, your changes will grow that branch, and when you are not on a branch, your changes will not affect any branch and stay temporary.

> +It can sometimes be useful for `HEAD` to be a commit ID.
> +For example, it lets you easily look at an old version of your code
> +(with `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`).

We should use a verb stronger than "look at" to emphasize the primary advantage of having the entire state visible in the working tree. If a user merely wants to read or inspect a single historical file, they can do so easily without moving their HEAD by running 'git show COMMIT_ID:path/to/file'. Checking out a commit allows something much more powerful. It restores your entire working directory to that exact state.

    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.

I said "safely build, run" because you had "old version of your CODE" in the paragraph, but if you can give examples outside the programming area, that would be even better. E.g.,

- Writers may able to rebuild and locally preview a complete
  historical version of a book or documentation site to see how
  cross-references and formatting rendered at that time.
- Game Designers may open an entire historical scene in an editor
  (like Unity or Blender) where assets, textures, and coordinates
  must all exist in a precise, interconnected state to load
  correctly.
- Data Scientists may execute and reproduce a specific historical
  data pipeline or model run using the exact combination of scripts
  and datasets that existed on that day.
Show 10 quoted lines
> +There are 3 main ways you can end up in detached HEAD state:
> +
> +1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID
> +2. `git checkout v1.3`, where v1.3 is a tag name
> +3. `git checkout origin/main`, where `origin/main` is
> +   a remote-tracking branch
> +
> +Checking out a tag puts you in detached HEAD state because `HEAD` can
> +only be a branch or a commit, not a tag or any other reference.
> +So `git checkout TAG` will set HEAD to the commit for that tag.

A more standard phrase for "the commit for that tag" is "the tagged commit".

Because we will recommend "switch" to be a way to require to be more explicit when users mean to go into the detached HEAD state soon below, I think we would want to move the "checkout <COMMIT>" and "switch --detach <COMMIT>" description to here from the earlier "sometimes useful" paragraph, to complement the above list of ways to detach your HEAD.

Show 13 quoted lines
> +If you switch branches after making commits in detached HEAD state, Git
> +will warn you that you might be about to "lose" those commits and print
> +out the commit ID. You can also always find those commits later using
> +linkgit:git-reflog[1].
> +
> +Here's what that warning looks like:
> +
> +-------------------------
> +Warning: you are leaving 1 commit behind, not connected to
> +any of your branches:
> +
> +  48c09f6 3
> +-------------------------

Your readers can guess that the 7 digit hex may probably be the commit object name you are about to lose, but you should use a bit more realistic descriptive title, not "3", to avoid confusion. I know many users do not write a good log message, but even a single word "bugfix" is better than "3" ;-)

Previous: Julia Evans via GitGitGadgetNext: Julia Evans
Message 17 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.