patchdoc: checkout: rewrite detached HEAD state explanation

From: Julia Evans <julia@jvns.ca>

The current explanation has the following issues:

- Says detached HEAD state is useful but doesn't explain why
- Takes many paragraphs before explaining what detached HEAD state is
- It's common for users to accidentally end up in detached HEAD state,
  but it doesn't explain why that might happen
- One of the UI improvements in `git switch` is to make it harder
  to detach accidentally, but that isn't advertised.
  See 7968bef06b (switch: only allow explicit detached HEAD, 2019-03-29)
- Too many confusing diagrams

Write a new explanation addressing these issues, and put it in a standalone guide so that we can easily reference it from advice ("see `git help detachedhead`"). The result is a shorter guide that covers more material.

The framing that "Git considers commits that aren't on a branch/other reference to be garbage" is taken from Steve Klabnik's tutorial https://steveklabnik.github.io/jujutsu-tutorial/branching-merging-and-conflicts/anonymous-branches.html. It's funny and it's consistent with the way Git uses the term "garbage collection".

Co-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
Signed-off-by: Julia Evans <julia@jvns.ca>
---
    doc: checkout: rewrite detached HEAD state explanation
    
    Often when rewriting these explanations I go through a process where I
    ask users' feedback on the old explanation. Here I didn't do that
    basically because that process takes a long time and I'm working on a
    bunch of other time consuming docs projects so I did a quick rewrite
    based on my previous experience explaining detached HEAD state to folks.
    
    I thought this could be a nice quick docs win on a topic which many
    users find quite confusing. If the changes here are too controversial I
    can drop it for now.
    
    Also if folks object to making a separate git help detachedhead guide
    I'm happy to drop that too. Personally I'm excited about the idea of
    being able to reference the guides in our advice (which is one of our
    best tools for getting users info about how to use Git!), but it's not
    possible to let users jump to a subsection, so this is sort of a hack
    around that.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2250%2Fjvns%2Fdetached-head-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2250/jvns/detached-head-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2250

 Documentation/detached-head.adoc   |  43 ++++++++++
 Documentation/git-checkout.adoc    | 129 +----------------------------
 Documentation/gitdetachedhead.adoc |  14 ++++
 advice.c                           |   1 +
 command-list.txt                   |   1 +
 5 files changed, 60 insertions(+), 128 deletions(-)
 create mode 100644 Documentation/detached-head.adoc
 create mode 100644 Documentation/gitdetachedhead.adoc

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

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").

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.

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.

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.

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.

This can happen when the user forgets to say "-t" ('git checkout -t origin/main' dwims to 'git checkout -t -b main origin/main'), so it is closer to 'unintentionally' than the above two.

Correct.

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.

Very good.

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.

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.

This may be good as a first step, but we may want to have more here than what we show in "git help checkout" later. If we miss the pictures we lost from "git help checkout", it can be moved here.

Thanks.

This change adds a standalone guide as well. The subject “just” make it sound like you are rewriting the text where it is.

On Wed, Oct 7, 2026, at 16:52, Julia Evans via GitGitGadget wrote:

Why in one word instead of hyphenating `detached-head`? (gitdetached-head(7))

This is missing meson/Makefile changes in order to make gitdetachedhead(7).

I see that this is similar to gitdatamodel(7). Except it adds “, if there is a current branch”:

    HEAD is where Git stores your current branch, if there is a current
    branch. HEAD can either be: [...]

But a potential problem with that is:

A: What is HEAD?
B: It stores the current branch, if there is a current branch.
A: Oh so it is *empty* if there is no current branch?
B: No. Then it stores a commit.

This is of course revealed later here. But I wonder if starting with current-branch can set someone up for a double take.

One could go in the other direction: you are almost always on a commit. For most people the exception will be the unborn branch state after `git init`. That commit is stored in the thing called `HEAD`. And if you are on branch it also points to that branch. (It doesn’t point at two things at the same time but instead at the branch, which is in turn points at the commit for the branch, but conceptually it’s the same difference).

Maybe go straight to `git switch --detached COMMIT_ID` here.

It is very useful to describe detached `HEAD` as something that you can fall into by accident. It is very much perenially needed. And this paragraph explains a legitimate, intentional use.

But a dedicated guide is also an opportunity to not only acknowledge hey there is a use here but to explain actively why it is convenient. Because one thing is “detached `HEAD`” as a conceptual, scary blind alley where my work might get garbage collected. But only thinking in terms of branches and tags can lead to a dead end of only thinking of Git as:

1. The state of our collective work right now (“main”)
2. Our important waypoints (tags)

So before you lead them out of the maw of the garbage incinerator, you can help level up their use of Git by explaining why checking out commits freely is useful with an example of why they would do that.

1. Finding buggy commits manually (this would probably end with a
   mention of git-bisect(1))
2. Testing that each commit on a branch (forked from `main`) passes the
   test suite
3. Browsing an interesting commit manually instead of pointing `git
   grep` at the commit (or something)
4. Just being on `origin/main` instead of having a `main`. I never
   update “main”. So why would I go to the trouble of keeping it up to
   date? I can just “be on” `origin/main` (detached on whatever that
   points to).

   See also StackOverflow questions about how to update hundreds of
   local branches with git-pull(1) or something. Why? They do not have
   hundreds of local branches that they are authoring. They just want
   those branches by other people to be updated. But that is not
   necessary for anything. You just need the remote-tracking
   branches. Including if you want to check them out (on detached
   `HEAD`).

This conceptual dead end (of no “detached `HEAD`) could manifest itself like this:

• “I must always be on a branch”
• “Therefore I can only check out old commits by first creating a
  branch”
• “Every interesting commit must have a tag for posteriety so we can
  name it” (you just need the hash, even abbreviated)
• “We must tag this commit for the build so we can name the build” (you
  can just use the hash or use part-of-the-hash with git-describe(1))

Maybe this is where you should mention git-reflog(1) (and git-log(1) maybe (see later)).

Maybe this about garbage collection could be tempered with a mention of the however-many default days for reflog expiry. It’s such a long time that if any of my commits get garbage collected... I probably didn’t need them.

I would say “typical” instead of “main”. As in these things are the typical gateways to this state (unintentionally).

Nice.

Okay, but it’s more immediate and obvious to use `git log`. Say you created three commits by accident while not on a branch. Then they will be immediately um logged.

git-reflog(1) is excellent too of course, mostly because you are likely to find all of them if you did a lot of weird checkouts in one session.

I didn’t read the rest here.