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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 7, 2026, 16:43 UTC
Message-ID: <xmqqik3da2bs.fsf@gitster.g>
In-Reply-To: <pull.2250.git.1791384721919.gitgitgadget@gmail.com>

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

Show 11 quoted lines

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

> +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.

> +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.

Show 5 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.

Show 5 quoted lines

> +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.

> +3. `git checkout origin/main`, where `origin/main` is
> +   a remote-tracking branch

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.

> +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.

Correct.

> +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.

Show 6 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.

Show 9 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.

Show 16 quoted lines

> diff --git a/Documentation/gitdetachedhead.adoc b/Documentation/gitdetachedhead.adoc
> new file mode 100644
> index 0000000000..0aeecd159c
> --- /dev/null
> +++ b/Documentation/gitdetachedhead.adoc
> @@ -0,0 +1,14 @@
> +gitdetachedhead(7)
> +===============
> +
> +NAME
> +----
> +gitdetachedhead - How detached HEAD state works
> +
> +DESCRIPTION
> +-----------
> +include::detached-head.adoc[]

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.

Show 30 quoted lines

> +
> +GIT
> +---
> +Part of the linkgit:git[1] suite
> diff --git a/advice.c b/advice.c
> index 401d047391..43f86c2eaf 100644
> --- a/advice.c
> +++ b/advice.c
> @@ -291,6 +291,7 @@ void detach_advice(const char *new_name)
>  	"\n"
>  	"  git switch -\n"
>  	"\n"
> +	"Run `git help detachedhead` to learn more.\n"
>  	"Turn off this advice by setting config variable advice.detachedHead to false\n\n");
>  
>  	fprintf(stderr, fmt, new_name);
> diff --git a/command-list.txt b/command-list.txt
> index 63ae2a67c9..313689335f 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -218,6 +218,7 @@ gitcore-tutorial                        guide
>  gitcredentials                          guide
>  gitcvs-migration                        guide
>  gitdatamodel                            guide
> +gitdetachedhead                         guide
>  gitdiffcore                             guide
>  giteveryday                             guide
>  gitfaq                                  guide
>
> base-commit: 5a7d1e8045ce66c908f62598e26cbb8df7b39a90