{"thread":{"id":"66484","subject":"[PATCH] doc: checkout: rewrite detached HEAD state explanation","startedAt":"2026-10-07T14:52:01Z","lastAt":"2026-11-16T22:08:39Z","messageCount":53,"participants":["Julia Evans via GitGitGadget","Junio C Hamano","Kristoffer Haugsbakk","Julia Evans","D. Ben Knoble","Ben Knoble"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"554386","messageId":"pull.2250.git.1791384721919.gitgitgadget@gmail.com","threadId":"66484","inReplyTo":null,"subject":"[PATCH] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-07T14:52:01Z","receivedAt":"2026-10-07T14:52:01Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nThe current explanation has the following issues:\n\n- Says detached HEAD state is useful but doesn't explain why\n- Takes many paragraphs before explaining what detached HEAD state is\n- It's common for users to accidentally end up in detached HEAD state,\n  but it doesn't explain why that might happen\n- One of the UI improvements in `git switch` is to make it harder\n  to detach accidentally, but that isn't advertised.\n  See 7968bef06b (switch: only allow explicit detached HEAD, 2019-03-29)\n- Too many confusing diagrams\n\nWrite a new explanation addressing these issues, and put it in a\nstandalone guide so that we can easily reference it from advice\n(\"see `git help detachedhead`\").\nThe result is a shorter guide that covers more material.\n\nThe framing that \"Git considers commits that aren't on a branch/other\nreference to be garbage\" is taken from Steve Klabnik's tutorial\nhttps://steveklabnik.github.io/jujutsu-tutorial/branching-merging-and-conflicts/anonymous-branches.html.\nIt's funny and it's consistent with the way Git uses the term\n\"garbage collection\".\n\nCo-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n    doc: checkout: rewrite detached HEAD state explanation\n    \n    Often when rewriting these explanations I go through a process where I\n    ask users' feedback on the old explanation. Here I didn't do that\n    basically because that process takes a long time and I'm working on a\n    bunch of other time consuming docs projects so I did a quick rewrite\n    based on my previous experience explaining detached HEAD state to folks.\n    \n    I thought this could be a nice quick docs win on a topic which many\n    users find quite confusing. If the changes here are too controversial I\n    can drop it for now.\n    \n    Also if folks object to making a separate git help detachedhead guide\n    I'm happy to drop that too. Personally I'm excited about the idea of\n    being able to reference the guides in our advice (which is one of our\n    best tools for getting users info about how to use Git!), but it's not\n    possible to let users jump to a subsection, so this is sort of a hack\n    around that.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2250%2Fjvns%2Fdetached-head-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2250/jvns/detached-head-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/2250\n\n Documentation/detached-head.adoc   |  43 ++++++++++\n Documentation/git-checkout.adoc    | 129 +----------------------------\n Documentation/gitdetachedhead.adoc |  14 ++++\n advice.c                           |   1 +\n command-list.txt                   |   1 +\n 5 files changed, 60 insertions(+), 128 deletions(-)\n create mode 100644 Documentation/detached-head.adoc\n create mode 100644 Documentation/gitdetachedhead.adoc\n\ndiff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc\nnew file mode 100644\nindex 0000000000..1e00712124\n--- /dev/null\n+++ b/Documentation/detached-head.adoc\n@@ -0,0 +1,43 @@\n+`HEAD` is where Git stores your current branch. `HEAD` can either be:\n+\n+1. A branch, which is your current branch.\n+2. A commit ID, when you don't have a current branch.\n+   This is called \"detached HEAD state\".\n+\n+It can sometimes be useful for `HEAD` to be a commit ID.\n+For example, it lets you look at an old version of your code\n+(with `git checkout COMMIT_ID`).\n+\n+The only problem is that if you create new commits while in detached\n+HEAD state, those commits won't be on a branch. This makes those new\n+commits much harder to find later. Also, Git considers commits that\n+aren't on any branch (or a tag or other reference) to be garbage.\n+Git will eventually permanently delete those \"garbage\" commits during\n+garbage collection.\n+\n+There are 3 main ways you can end up in detached HEAD state\n+unintentionally:\n+\n+1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID\n+2. `git checkout v1.3`, where v1.3 is a tag name\n+3. `git checkout origin/main`, where `origin/main` is\n+   a remote-tracking branch\n+\n+Checking out a tag puts you in detached HEAD state because `HEAD` can\n+only be a branch or a commit, not a tag or any other reference.\n+So `git checkout TAG` will set HEAD to the commit for that tag.\n+\n+The easiest way to avoid accidentally ending up in detached HEAD state\n+is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to\n+switch branches. `git switch` won't let you detach unless you explicitly\n+pass the `--detach` argument.\n+\n+To get back onto a branch, you can:\n+\n+1. Switch to the branch you want to be on, with `git switch BRANCHNAME`.\n+2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`.\n+   You might want to do this if you've created new commits, so that you can\n+   find the commit later and so that it won't be garbage collected.\n+\n+If you create commits in detached HEAD state that aren't on a branch,\n+you can find them later using linkgit:git-reflog[1].\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 2aefea0228..4e9e94e24d 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -376,135 +376,8 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n [[DETACHED_HEAD]]\n DETACHED HEAD\n -------------\n-`HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each\n-branch refers to a specific commit. Let's look at a repo with three\n-commits, one of them tagged, and with branch `master` checked out:\n \n-------------\n-           HEAD (refers to branch 'master')\n-            |\n-            v\n-a---b---c  branch 'master' (refers to commit 'c')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-When a commit is created in this state, the branch is updated to refer to\n-the new commit. Specifically, `git commit` creates a new commit `d`, whose\n-parent is commit `c`, and then updates branch `master` to refer to new\n-commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers\n-to commit `d`:\n-\n-------------\n-$ edit; git add; git commit\n-\n-               HEAD (refers to branch 'master')\n-                |\n-                v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is sometimes useful to be able to checkout a commit that is not at\n-the tip of any named branch, or even to create a new commit that is not\n-referenced by a named branch. Let's look at what happens when we\n-checkout commit `b` (here we show two ways this may be done):\n-\n-------------\n-$ git checkout v2.0  # or\n-$ git checkout master^^\n-\n-   HEAD (refers to commit 'b')\n-    |\n-    v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-Notice that regardless of which checkout command we use, `HEAD` now refers\n-directly to commit `b`. This is known as being in detached `HEAD` state.\n-It means simply that `HEAD` refers to a specific commit, as opposed to\n-referring to a named branch. Let's see what happens when we create a commit:\n-\n-------------\n-$ edit; git add; git commit\n-\n-     HEAD (refers to commit 'e')\n-      |\n-      v\n-      e\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-There is now a new commit `e`, but it is referenced only by `HEAD`. We can\n-of course add yet another commit in this state:\n-\n-------------\n-$ edit; git add; git commit\n-\n-\t HEAD (refers to commit 'f')\n-\t  |\n-\t  v\n-      e---f\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-In fact, we can perform all the normal Git operations. But, let's look\n-at what happens when we then checkout `master`:\n-\n-------------\n-$ git checkout master\n-\n-               HEAD (refers to branch 'master')\n-      e---f     |\n-     /          v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is important to realize that at this point nothing refers to commit\n-`f`. Eventually commit `f` (and by extension commit `e`) will be deleted\n-by the routine Git garbage collection process, unless we create a reference\n-before that happens. If we have not yet moved away from commit `f`,\n-any of these will create a reference to it:\n-\n-------------\n-$ git checkout -b foo  # or \"git switch -c foo\"  <1>\n-$ git branch foo                                 <2>\n-$ git tag foo                                    <3>\n-------------\n-<1> creates a new branch `foo`, which refers to commit `f`, and then\n-    updates `HEAD` to refer to branch `foo`. In other words, we'll no longer\n-    be in detached `HEAD` state after this command.\n-<2> similarly creates a new branch `foo`, which refers to commit `f`,\n-    but leaves `HEAD` detached.\n-<3> creates a new tag `foo`, which refers to commit `f`,\n-    leaving `HEAD` detached.\n-\n-If we have moved away from commit `f`, then we must first recover its object\n-name (typically by using git reflog), and then we can create a reference to\n-it. For example, to see the last two commits to which `HEAD` referred, we\n-can use either of these commands:\n-\n-------------\n-$ git reflog -2 HEAD # or\n-$ git log -g -2 HEAD\n-------------\n+include::detached-head.adoc[]\n \n [[ARGUMENT_DISAMBIGUATION]]\n ARGUMENT DISAMBIGUATION\ndiff --git a/Documentation/gitdetachedhead.adoc b/Documentation/gitdetachedhead.adoc\nnew file mode 100644\nindex 0000000000..0aeecd159c\n--- /dev/null\n+++ b/Documentation/gitdetachedhead.adoc\n@@ -0,0 +1,14 @@\n+gitdetachedhead(7)\n+===============\n+\n+NAME\n+----\n+gitdetachedhead - How detached HEAD state works\n+\n+DESCRIPTION\n+-----------\n+include::detached-head.adoc[]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/advice.c b/advice.c\nindex 401d047391..43f86c2eaf 100644\n--- a/advice.c\n+++ b/advice.c\n@@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n \t\"\\n\"\n \t\"  git switch -\\n\"\n \t\"\\n\"\n+\t\"Run `git help detachedhead` to learn more.\\n\"\n \t\"Turn off this advice by setting config variable advice.detachedHead to false\\n\\n\");\n \n \tfprintf(stderr, fmt, new_name);\ndiff --git a/command-list.txt b/command-list.txt\nindex 63ae2a67c9..313689335f 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -218,6 +218,7 @@ gitcore-tutorial                        guide\n gitcredentials                          guide\n gitcvs-migration                        guide\n gitdatamodel                            guide\n+gitdetachedhead                         guide\n gitdiffcore                             guide\n giteveryday                             guide\n gitfaq                                  guide\n\nbase-commit: 5a7d1e8045ce66c908f62598e26cbb8df7b39a90\n-- \ngitgitgadget\n\n"},{"id":"554391","messageId":"xmqqik3da2bs.fsf@gitster.g","threadId":"66484","inReplyTo":"pull.2250.git.1791384721919.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-07T16:43:35Z","receivedAt":"2026-10-07T16:43:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> diff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc\n> new file mode 100644\n> index 0000000000..1e00712124\n> --- /dev/null\n> +++ b/Documentation/detached-head.adoc\n> @@ -0,0 +1,43 @@\n> +`HEAD` is where Git stores your current branch. `HEAD` can either be:\n> +\n> +1. A branch, which is your current branch.\n> +2. A commit ID, when you don't have a current branch.\n> +   This is called \"detached HEAD state\".\n\nHEAD is branch which can either be a branch or something else?\n\n    HEAD records the state from which your current changes started.\n    This can be a branch (the \"current branch\"), or it may not be\n    associated with any concrete branch (in which case HEAD is\n    \"detached\").\n\n> +It can sometimes be useful for `HEAD` to be a commit ID.\n> +For example, it lets you look at an old version of your code\n> +(with `git checkout COMMIT_ID`).\n\nTo \"look at\" an older state is more versatile than simply running\n'git show COMMIT_ID:path', as it allows you to do anything you can\ndo on a branch, such as building and testing.  Thus,\n\n \tA detached HEAD is useful when you want to tentatively visit\n\tan old state with 'git checkout --detach v0.1', without\n\thaving to create a dedicated branch for it.\n\n> +The only problem is that if you create new commits while in detached\n> +HEAD state, those commits won't be on a branch.\n\nI would suggest rephrasing \"The only problem\" to \"One caveat is\" or\nsomething.  When sightseeing and experimenting, the ability to\ncreate throw-away commits without the need to clean them up later,\nor to invent a unique name for a temporary branch, is not a problem.\nIt is an advantage.\n\n> This makes those new\n> +commits much harder to find later. Also, Git considers commits that\n> +aren't on any branch (or a tag or other reference) to be garbage.\n> +Git will eventually permanently delete those \"garbage\" commits during\n> +garbage collection.\n\nCorrect.\n\nPerhaps it is better to clarify this by adding \"after you leave\nthe detached HEAD state\" after \"to find later\".  While you are in\nthe detached HEAD state, you can run 'git log' to find the commits\nyou created there, as you can do everything you normally can on a\nbranch, or use 'git reflog @{now}' for that matter.\n\n> +There are 3 main ways you can end up in detached HEAD state\n> +unintentionally:\n> +\n> +1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID\n> +2. `git checkout v1.3`, where v1.3 is a tag name\n\nThese I wouldn't call \"unintentionally\".  They are documented and\nsupported ways to do so, and will remain to be so.  \"unknowingly\"\nmay be a more fair way to call these gotchas, though.\n\n> +3. `git checkout origin/main`, where `origin/main` is\n> +   a remote-tracking branch\n\nThis can happen when the user forgets to say \"-t\" ('git checkout -t\norigin/main' dwims to 'git checkout -t -b main origin/main'), so it\nis closer to 'unintentionally' than the above two.\n\n> +Checking out a tag puts you in detached HEAD state because `HEAD` can\n> +only be a branch or a commit, not a tag or any other reference.\n> +So `git checkout TAG` will set HEAD to the commit for that tag.\n\nCorrect.\n\n> +The easiest way to avoid accidentally ending up in detached HEAD state\n> +is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to\n> +switch branches. `git switch` won't let you detach unless you explicitly\n> +pass the `--detach` argument.\n\nCorrect, but the motivation to 'avoid accidentally ending up' may\nwant to be spelled out.  Most often checking out a tag is to go\nsightseeing, where you do not want to 'avoid' detached HEAD.\n\n> +To get back onto a branch, you can:\n> +\n> +1. Switch to the branch you want to be on, with `git switch BRANCHNAME`.\n> +2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`.\n> +   You might want to do this if you've created new commits, so that you can\n> +   find the commit later and so that it won't be garbage collected.\n\nVery good.\n\n> +If you create commits in detached HEAD state that aren't on a branch,\n> +you can find them later using linkgit:git-reflog[1].\n\nThis, as you already said, is \"much harder to find later\" option.\nThere should be a better recovery option described here before\nresorting to \"git reflog HEAD\" after you switched back.  E.g.,\n\n    If you have created commits in detached HEAD state and then\n    switched away from the state, all is not lost.  \"git checkout\"\n    would have give you a warning message, like this:\n\n\tWarning: you are leaving 2 commits behind, not connected to\n\tany of your branches\n\n\tc816689 typofix the previous\n\t8e1bff5 decsribe detached HEAD state better\n\n    You can create branches to keep them, e.g., \"git branch saved c816689\",\n    by using the commit object names left there.\n\n> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n> index 2aefea0228..4e9e94e24d 100644\n> --- a/Documentation/git-checkout.adoc\n> +++ b/Documentation/git-checkout.adoc\n> @@ -376,135 +376,8 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n>  [[DETACHED_HEAD]]\n>  DETACHED HEAD\n>  -------------\n> +include::detached-head.adoc[]\n\nLosing the diagrams is a bit concerning.  However, if the intention\nis to have readers learn how HEAD refers to a branch pointing at a\ncommit with history structured as a DAG elsewhere in a more basic\nconcepts guide, I suspect that it would actually work better.  This\ncould even be reduced to a simple \"see also\" pointer to that other\nguide.\n\nIf an existing user only uses 'switch' and never reads 'git help\ncheckout', they are already not seeing these diagrams, or perhaps\nthey learned the concepts elsewhere.  They still manage to\nunderstand Git well enough to make use of it, so perhaps this\napproach is OK.  I dunno.\n\n> diff --git a/Documentation/gitdetachedhead.adoc b/Documentation/gitdetachedhead.adoc\n> new file mode 100644\n> index 0000000000..0aeecd159c\n> --- /dev/null\n> +++ b/Documentation/gitdetachedhead.adoc\n> @@ -0,0 +1,14 @@\n> +gitdetachedhead(7)\n> +===============\n> +\n> +NAME\n> +----\n> +gitdetachedhead - How detached HEAD state works\n> +\n> +DESCRIPTION\n> +-----------\n> +include::detached-head.adoc[]\n\nThis may be good as a first step, but we may want to have more here\nthan what we show in \"git help checkout\" later.  If we miss the\npictures we lost from \"git help checkout\", it can be moved here.\n\nThanks.\n\n> +\n> +GIT\n> +---\n> +Part of the linkgit:git[1] suite\n> diff --git a/advice.c b/advice.c\n> index 401d047391..43f86c2eaf 100644\n> --- a/advice.c\n> +++ b/advice.c\n> @@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n>  \t\"\\n\"\n>  \t\"  git switch -\\n\"\n>  \t\"\\n\"\n> +\t\"Run `git help detachedhead` to learn more.\\n\"\n>  \t\"Turn off this advice by setting config variable advice.detachedHead to false\\n\\n\");\n>  \n>  \tfprintf(stderr, fmt, new_name);\n> diff --git a/command-list.txt b/command-list.txt\n> index 63ae2a67c9..313689335f 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -218,6 +218,7 @@ gitcore-tutorial                        guide\n>  gitcredentials                          guide\n>  gitcvs-migration                        guide\n>  gitdatamodel                            guide\n> +gitdetachedhead                         guide\n>  gitdiffcore                             guide\n>  giteveryday                             guide\n>  gitfaq                                  guide\n>\n> base-commit: 5a7d1e8045ce66c908f62598e26cbb8df7b39a90\n\n"},{"id":"554410","messageId":"cb482e6d-0c76-4f34-b72c-03b5234d4f37@app.fastmail.com","threadId":"66484","inReplyTo":"pull.2250.git.1791384721919.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-10-07T19:02:30Z","receivedAt":"2026-10-07T19:02:30Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"> Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation\n\nThis change adds a standalone guide as well. The subject “just” make it\nsound like you are rewriting the text where it is.\n\nOn Wed, Oct 7, 2026, at 16:52, Julia Evans via GitGitGadget wrote:\n> From: Julia Evans <julia@jvns.ca>\n>\n> The current explanation has the following issues:\n>\n> - Says detached HEAD state is useful but doesn't explain why\n> - Takes many paragraphs before explaining what detached HEAD state is\n> - It's common for users to accidentally end up in detached HEAD state,\n>   but it doesn't explain why that might happen\n> - One of the UI improvements in `git switch` is to make it harder\n>   to detach accidentally, but that isn't advertised.\n>   See 7968bef06b (switch: only allow explicit detached HEAD, 2019-03-29)\n> - Too many confusing diagrams\n>\n> Write a new explanation addressing these issues, and put it in a\n> standalone guide so that we can easily reference it from advice\n> (\"see `git help detachedhead`\").\n> The result is a shorter guide that covers more material.\n>\n> The framing that \"Git considers commits that aren't on a branch/other\n> reference to be garbage\" is taken from Steve Klabnik's tutorial\n> https://steveklabnik.github.io/jujutsu-tutorial/branching-merging-and-conflicts/anonymous-branches.html.\n> It's funny and it's consistent with the way Git uses the term\n> \"garbage collection\".\n>\n> Co-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n>     doc: checkout: rewrite detached HEAD state explanation\n>\n>     Often when rewriting these explanations I go through a process where I\n>     ask users' feedback on the old explanation. Here I didn't do that\n>     basically because that process takes a long time and I'm working on a\n>     bunch of other time consuming docs projects so I did a quick rewrite\n>     based on my previous experience explaining detached HEAD state to folks.\n>\n>     I thought this could be a nice quick docs win on a topic which many\n>     users find quite confusing. If the changes here are too controversial I\n>     can drop it for now.\n>\n>     Also if folks object to making a separate git help detachedhead guide\n>     I'm happy to drop that too. Personally I'm excited about the idea of\n>     being able to reference the guides in our advice (which is one of our\n>     best tools for getting users info about how to use Git!), but it's not\n>     possible to let users jump to a subsection, so this is sort of a hack\n>     around that.\n>\n> Published-As:\n> https://github.com/gitgitgadget/git/releases/tag/pr-2250%2Fjvns%2Fdetached-head-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git\n> pr-2250/jvns/detached-head-v1\n> Pull-Request: https://github.com/gitgitgadget/git/pull/2250\n>\n>  Documentation/detached-head.adoc   |  43 ++++++++++\n>  Documentation/git-checkout.adoc    | 129 +----------------------------\n>  Documentation/gitdetachedhead.adoc |  14 ++++\n\nWhy in one word instead of hyphenating `detached-head`?\n(gitdetached-head(7))\n\n>  advice.c                           |   1 +\n>  command-list.txt                   |   1 +\n\nThis is missing meson/Makefile changes in order to make\ngitdetachedhead(7).\n\n>  5 files changed, 60 insertions(+), 128 deletions(-)\n>  create mode 100644 Documentation/detached-head.adoc\n>  create mode 100644 Documentation/gitdetachedhead.adoc\n>\n> diff --git a/Documentation/detached-head.adoc\n> b/Documentation/detached-head.adoc\n> new file mode 100644\n> index 0000000000..1e00712124\n> --- /dev/null\n> +++ b/Documentation/detached-head.adoc\n> @@ -0,0 +1,43 @@\n> +`HEAD` is where Git stores your current branch. `HEAD` can either be:\n\nI see that this is similar to gitdatamodel(7). Except it adds “, if\nthere is a current branch”:\n\n    HEAD is where Git stores your current branch, if there is a current\n    branch. HEAD can either be: [...]\n\nBut a potential problem with that is:\n\nA: What is HEAD?\nB: It stores the current branch, if there is a current branch.\nA: Oh so it is *empty* if there is no current branch?\nB: No. Then it stores a commit.\n\nThis is of course revealed later here. But I wonder if starting with\ncurrent-branch can set someone up for a double take.\n\nOne could go in the other direction: you are almost always on a\ncommit. For most people the exception will be the unborn branch state\nafter `git init`. That commit is stored in the thing called `HEAD`. And\nif you are on branch it also points to that branch. (It doesn’t point at\ntwo things at the same time but instead at the branch, which is in turn\npoints at the commit for the branch, but conceptually it’s the same\ndifference).\n\n> +\n> +1. A branch, which is your current branch.\n> +2. A commit ID, when you don't have a current branch.\n> +   This is called \"detached HEAD state\".\n> +\n> +It can sometimes be useful for `HEAD` to be a commit ID.\n> +For example, it lets you look at an old version of your code\n> +(with `git checkout COMMIT_ID`).\n\nMaybe go straight to `git switch --detached COMMIT_ID` here.\n\nIt is very useful to describe detached `HEAD` as something that you can\nfall into by accident. It is very much perenially needed. And this\nparagraph explains a legitimate, intentional use.\n\nBut a dedicated guide is also an opportunity to not only acknowledge hey\nthere is a use here but to explain actively why it is\nconvenient. Because one thing is “detached `HEAD`” as a conceptual,\nscary blind alley where my work might get garbage collected. But only\nthinking in terms of branches and tags can lead to a dead end of only\nthinking of Git as:\n\n1. The state of our collective work right now (“main”)\n2. Our important waypoints (tags)\n\nSo before you lead them out of the maw of the garbage incinerator, you\ncan help level up their use of Git by explaining why checking out\ncommits freely is useful with an example of why they would do that.\n\n1. Finding buggy commits manually (this would probably end with a\n   mention of git-bisect(1))\n2. Testing that each commit on a branch (forked from `main`) passes the\n   test suite\n3. Browsing an interesting commit manually instead of pointing `git\n   grep` at the commit (or something)\n4. Just being on `origin/main` instead of having a `main`. I never\n   update “main”. So why would I go to the trouble of keeping it up to\n   date? I can just “be on” `origin/main` (detached on whatever that\n   points to).\n\n   See also StackOverflow questions about how to update hundreds of\n   local branches with git-pull(1) or something. Why? They do not have\n   hundreds of local branches that they are authoring. They just want\n   those branches by other people to be updated. But that is not\n   necessary for anything. You just need the remote-tracking\n   branches. Including if you want to check them out (on detached\n   `HEAD`).\n\nThis conceptual dead end (of no “detached `HEAD`) could manifest itself\nlike this:\n\n• “I must always be on a branch”\n• “Therefore I can only check out old commits by first creating a\n  branch”\n• “Every interesting commit must have a tag for posteriety so we can\n  name it” (you just need the hash, even abbreviated)\n• “We must tag this commit for the build so we can name the build” (you\n  can just use the hash or use part-of-the-hash with git-describe(1))\n\n> +\n> +The only problem is that if you create new commits while in detached\n> +HEAD state, those commits won't be on a branch. This makes those new\n> +commits much harder to find later. Also, Git considers commits that\n> +aren't on any branch (or a tag or other reference) to be garbage.\n> +Git will eventually permanently delete those \"garbage\" commits during\n> +garbage collection.\n\nMaybe this is where you should mention git-reflog(1) (and git-log(1)\nmaybe (see later)).\n\nMaybe this about garbage collection could be tempered with a mention of\nthe however-many default days for reflog expiry. It’s such a long time\nthat if any of my commits get garbage collected... I probably didn’t\nneed them.\n\n> +\n> +There are 3 main ways you can end up in detached HEAD state\n> +unintentionally:\n\nI would say “typical” instead of “main”. As in these things are the\ntypical gateways to this state (unintentionally).\n\n> +\n> +1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID\n> +2. `git checkout v1.3`, where v1.3 is a tag name\n> +3. `git checkout origin/main`, where `origin/main` is\n> +   a remote-tracking branch\n> +\n> +Checking out a tag puts you in detached HEAD state because `HEAD` can\n> +only be a branch or a commit, not a tag or any other reference.\n> +So `git checkout TAG` will set HEAD to the commit for that tag.\n\nNice.\n\n> +\n> +The easiest way to avoid accidentally ending up in detached HEAD state\n> +is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to\n> +switch branches. `git switch` won't let you detach unless you\n> explicitly\n> +pass the `--detach` argument.\n> +\n> +To get back onto a branch, you can:\n> +\n> +1. Switch to the branch you want to be on, with `git switch BRANCHNAME`.\n> +2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`.\n> +   You might want to do this if you've created new commits, so that you can\n> +   find the commit later and so that it won't be garbage collected.\n> +\n> +If you create commits in detached HEAD state that aren't on a branch,\n> +you can find them later using linkgit:git-reflog[1].\n\nOkay, but it’s more immediate and obvious to use `git log`. Say you\ncreated three commits by accident while not on a branch. Then they will\nbe immediately um logged.\n\ngit-reflog(1) is excellent too of course, mostly because you are likely\nto find all of them if you did a lot of weird checkouts in one session.\n\n> diff --git a/Documentation/git-checkout.adoc\n> b/Documentation/git-checkout.adoc\n> index 2aefea0228..4e9e94e24d 100644\n> --- a/Documentation/git-checkout.adoc\n> +++ b/Documentation/git-checkout.adoc\n> @@ -376,135 +376,8 @@ For more details, see the 'pathspec' entry in\n> [snip]\n\nI didn’t read the rest here.\n\n"},{"id":"554845","messageId":"5dad29e9-24e6-494a-9b0f-701af856ae69@app.fastmail.com","threadId":"66484","inReplyTo":"cb482e6d-0c76-4f34-b72c-03b5234d4f37@app.fastmail.com","subject":"Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-13T11:48:38Z","receivedAt":"2026-10-13T11:48:38Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"To make this process easier, I'm going to first deal with factual issues\n(like any mistakes or ideas for more information content to include).\nI'll mark comments that are suggestions for how to make the wording\nmore clear with \"style comment\" to potentially address later.\n\nOn Wed, Oct 7, 2026, at 3:02 PM, Kristoffer Haugsbakk wrote:\n>> Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation\n>\n> This change adds a standalone guide as well. The subject “just” make it\n> sound like you are rewriting the text where it is.\n\nYes. I ran out of space while writing the subject line. \nHappy to make changes to how the commit is structured if that would\nbe better.\n\n>>  Documentation/detached-head.adoc   |  43 ++++++++++\n>>  Documentation/git-checkout.adoc    | 129 +----------------------------\n>>  Documentation/gitdetachedhead.adoc |  14 ++++\n>\n> Why in one word instead of hyphenating `detached-head`?\n> (gitdetached-head(7))\n\nCurrently the guides are all one word with no hyphens.\nHappy to use a different style if folks think we shouldn't use\nthe current naming convention for the guides \n\n>>  advice.c                           |   1 +\n>>  command-list.txt                   |   1 +\n>\n> This is missing meson/Makefile changes in order to make\n> gitdetachedhead(7).\n\nThanks, will fix.\n\n>>  5 files changed, 60 insertions(+), 128 deletions(-)\n>>  create mode 100644 Documentation/detached-head.adoc\n>>  create mode 100644 Documentation/gitdetachedhead.adoc\n>>\n>> diff --git a/Documentation/detached-head.adoc\n>> b/Documentation/detached-head.adoc\n>> new file mode 100644\n>> index 0000000000..1e00712124\n>> --- /dev/null\n>> +++ b/Documentation/detached-head.adoc\n>> @@ -0,0 +1,43 @@\n>> +`HEAD` is where Git stores your current branch. `HEAD` can either be:\n>\n>\n>> +\n>> +1. A branch, which is your current branch.\n>> +2. A commit ID, when you don't have a current branch.\n>> +   This is called \"detached HEAD state\".\n>> +\n>> +It can sometimes be useful for `HEAD` to be a commit ID.\n>> +For example, it lets you look at an old version of your code\n>> +(with `git checkout COMMIT_ID`).\n>\n> Maybe go straight to `git switch --detached COMMIT_ID` here.\n\nStyle comment.\n\n> It is very useful to describe detached `HEAD` as something that you can\n> fall into by accident. It is very much perenially needed. And this\n> paragraph explains a legitimate, intentional use.\n>\n> But a dedicated guide is also an opportunity to not only acknowledge hey\n> there is a use here but to explain actively why it is\n> convenient. Because one thing is “detached `HEAD`” as a conceptual,\n> scary blind alley where my work might get garbage collected. But only\n> thinking in terms of branches and tags can lead to a dead end of only\n> thinking of Git as:\n>\n> 1. The state of our collective work right now (“main”)\n> 2. Our important waypoints (tags)\n>\n> So before you lead them out of the maw of the garbage incinerator, you\n> can help level up their use of Git by explaining why checking out\n> commits freely is useful with an example of why they would do that.\n>\n> 1. Finding buggy commits manually (this would probably end with a\n>    mention of git-bisect(1))\n> 2. Testing that each commit on a branch (forked from `main`) passes the\n>    test suite\n> 3. Browsing an interesting commit manually instead of pointing `git\n>    grep` at the commit (or something)\n> 4. Just being on `origin/main` instead of having a `main`. I never\n>    update “main”. So why would I go to the trouble of keeping it up to\n>    date? I can just “be on” `origin/main` (detached on whatever that\n>    points to).\n\nThis is a nice list of reasons being in detached head state, thanks.\nNot sure if it will be helpful to include or not though.\n\n>    See also StackOverflow questions about how to update hundreds of\n>    local branches with git-pull(1) or something. Why? They do not have\n>    hundreds of local branches that they are authoring. They just want\n>    those branches by other people to be updated. But that is not\n>    necessary for anything. You just need the remote-tracking\n>    branches. Including if you want to check them out (on detached\n>    `HEAD`).\n>\n> This conceptual dead end (of no “detached `HEAD`) could manifest itself\n> like this:\n>\n> • “I must always be on a branch”\n> • “Therefore I can only check out old commits by first creating a\n>   branch”\n> • “Every interesting commit must have a tag for posteriety so we can\n>   name it” (you just need the hash, even abbreviated)\n> • “We must tag this commit for the build so we can name the build” (you\n>   can just use the hash or use part-of-the-hash with git-describe(1))\n>\n>> +The only problem is that if you create new commits while in detached\n>> +HEAD state, those commits won't be on a branch. This makes those new\n>> +commits much harder to find later. Also, Git considers commits that\n>> +aren't on any branch (or a tag or other reference) to be garbage.\n>> +Git will eventually permanently delete those \"garbage\" commits during\n>> +garbage collection.\n>\n> Maybe this is where you should mention git-reflog(1) (and git-log(1)\n> maybe (see later)).\n>\n> Maybe this about garbage collection could be tempered with a mention of\n> the however-many default days for reflog expiry. It’s such a long time\n> that if any of my commits get garbage collected... I probably didn’t\n> need them.\n\nGood idea, will mention it's 90 days by default.\n\n>> +\n>> +There are 3 main ways you can end up in detached HEAD state\n>> +unintentionally:\n>\n> I would say “typical” instead of “main”. As in these things are the\n> typical gateways to this state (unintentionally).\n\nStyle comment\n\n>> +\n>> +The easiest way to avoid accidentally ending up in detached HEAD state\n>> +is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to\n>> +switch branches. `git switch` won't let you detach unless you\n>> explicitly\n>> +pass the `--detach` argument.\n>> +\n>> +To get back onto a branch, you can:\n>> +\n>> +1. Switch to the branch you want to be on, with `git switch BRANCHNAME`.\n>> +2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`.\n>> +   You might want to do this if you've created new commits, so that you can\n>> +   find the commit later and so that it won't be garbage collected.\n>> +\n>> +If you create commits in detached HEAD state that aren't on a branch,\n>> +you can find them later using linkgit:git-reflog[1].\n>\n> Okay, but it’s more immediate and obvious to use `git log`. Say you\n> created three commits by accident while not on a branch. Then they will\n> be immediately um logged.\n>\n> git-reflog(1) is excellent too of course, mostly because you are likely\n> to find all of them if you did a lot of weird checkouts in one session.\n\nGoing to deal with this another way\n\n"},{"id":"554850","messageId":"2642391e-1cef-4071-ae3f-db6fee3fab74@app.fastmail.com","threadId":"66484","inReplyTo":"5dad29e9-24e6-494a-9b0f-701af856ae69@app.fastmail.com","subject":"Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-10-13T12:20:29Z","receivedAt":"2026-10-13T12:20:29Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Tue, Oct 13, 2026, at 13:48, Julia Evans wrote:\n> On Wed, Oct 7, 2026, at 3:02 PM, Kristoffer Haugsbakk wrote:\n>>>[snip]\n>>>  Documentation/detached-head.adoc   |  43 ++++++++++\n>>>  Documentation/git-checkout.adoc    | 129 +----------------------------\n>>>  Documentation/gitdetachedhead.adoc |  14 ++++\n>>\n>> Why in one word instead of hyphenating `detached-head`?\n>> (gitdetached-head(7))\n>\n> Currently the guides are all one word with no hyphens.\n> Happy to use a different style if folks think we shouldn't use\n> the current naming convention for the guides\n\nI’m confused. It doesn’t look like that to me?\n\n    $ git help --guides\n    The Git concept guides are:\n       core-tutorial    A Git core tutorial for developers\n       credentials      Providing usernames and passwords to Git\n       cvs-migration    Git for CVS users\n       diffcore         Tweaking diff output\n       everyday         A useful minimum set of commands for Everyday Git\n       faq              Frequently asked questions about using Git\n       glossary         A Git Glossary\n       namespaces       Git namespaces\n       remote-helpers   Helper programs to interact with remote repositories\n       submodules       Mounting one repository inside another\n       tutorial         A tutorial introduction to Git\n       tutorial-2       A tutorial introduction to Git: part two\n       workflows        An overview of recommended workflows with Git\n\n    'git help -a' and 'git help -g' list available subcommands and some\n    concept guides. See 'git help <command>' or 'git help <concept>'\n    to read about a specific subcommand or concept.\n    See 'git help git' for an overview of the system.\n\nWhat is definitely the case is that there is no hyphen between `git` and\nthe first word, maybe in order to distinguish section 1 commands) and\nsection 5 and 7 manpages.\n\n>\n>[snip]\n\n"},{"id":"554852","messageId":"1637a8fb-d689-47fe-a008-e8e90d9889b9@app.fastmail.com","threadId":"66484","inReplyTo":"2642391e-1cef-4071-ae3f-db6fee3fab74@app.fastmail.com","subject":"Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-13T12:27:18Z","receivedAt":"2026-10-13T12:27:18Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Tue, Oct 13, 2026, at 8:20 AM, Kristoffer Haugsbakk wrote:\n> On Tue, Oct 13, 2026, at 13:48, Julia Evans wrote:\n>> On Wed, Oct 7, 2026, at 3:02 PM, Kristoffer Haugsbakk wrote:\n>>>>[snip]\n>>>>  Documentation/detached-head.adoc   |  43 ++++++++++\n>>>>  Documentation/git-checkout.adoc    | 129 +----------------------------\n>>>>  Documentation/gitdetachedhead.adoc |  14 ++++\n>>>\n>>> Why in one word instead of hyphenating `detached-head`?\n>>> (gitdetached-head(7))\n>>\n>> Currently the guides are all one word with no hyphens.\n>> Happy to use a different style if folks think we shouldn't use\n>> the current naming convention for the guides\n>\n> I’m confused. It doesn’t look like that to me?\n>\n>     $ git help --guides\n>     The Git concept guides are:\n>        core-tutorial    A Git core tutorial for developers\n>        credentials      Providing usernames and passwords to Git\n>        cvs-migration    Git for CVS users\n>        diffcore         Tweaking diff output\n>        everyday         A useful minimum set of commands for Everyday Git\n>        faq              Frequently asked questions about using Git\n>        glossary         A Git Glossary\n>        namespaces       Git namespaces\n>        remote-helpers   Helper programs to interact with remote repositories\n>        submodules       Mounting one repository inside another\n>        tutorial         A tutorial introduction to Git\n>        tutorial-2       A tutorial introduction to Git: part two\n>        workflows        An overview of recommended workflows with Git\n>\n>     'git help -a' and 'git help -g' list available subcommands and some\n>     concept guides. See 'git help <command>' or 'git help <concept>'\n>     to read about a specific subcommand or concept.\n>     See 'git help git' for an overview of the system.\n>\n> What is definitely the case is that there is no hyphen between `git` and\n> the first word, maybe in order to distinguish section 1 commands) and\n> section 5 and 7 manpages.\n\nThanks, I'll change the naming, I didn't realize that. For some reason I felt\nsure it was the other way. Maybe we should rename `gitmergeconflicts`\nto `gitmerge-conflicts` in the other patch series too.\n\nMy best guess is that I made that mistake because I (maybe idiosyncratically)\nalways use `man <page>`  to access the Git man pages, and typing\n`man gitdetached-head` feels awkward to me. \nBut of course we're recommending that folks use `git help detached-head`,\nand `git help detached-head` is much nicer than `git help detachedhead`.\n\n"},{"id":"554853","messageId":"5e07d489-ca34-4dcb-8953-c58d30261926@app.fastmail.com","threadId":"66484","inReplyTo":"1637a8fb-d689-47fe-a008-e8e90d9889b9@app.fastmail.com","subject":"Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-13T12:42:07Z","receivedAt":"2026-10-13T12:42:07Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":">> What is definitely the case is that there is no hyphen between `git` and\n>> the first word, maybe in order to distinguish section 1 commands) and\n>> section 5 and 7 manpages.\n>\n> Thanks, I'll change the naming, I didn't realize that. For some reason I felt\n> sure it was the other way. Maybe we should rename `gitmergeconflicts`\n> to `gitmerge-conflicts` in the other patch series too.\n>\n> My best guess is that I made that mistake because I (maybe idiosyncratically)\n> always use `man <page>`  to access the Git man pages, and typing\n> `man gitdetached-head` feels awkward to me. \n> But of course we're recommending that folks use `git help detached-head`,\n> and `git help detached-head` is much nicer than `git help detachedhead`.\n\nReflecting on this a little more, I think there's a bit of a disconnect between\nhow we recommend users use the Git help system (via `git help config`)\nand how we refer to other man pages in the man pages, which is like this:\n\n> (see git-fetch(1), git-config(1) and gitmodules(5))\n\nIf a user sees a reference like `git-config(1)` or `gitmodules(5)`,\nthe most obvious way to look it up is to type `man git-config`, or\n`man gitmodules` and not to deduce that you can run\n`git help config` or `git help modules`: Especially because sometimes\nyou need to remove a `git-` from the beginning and sometimes just\n`git`. I'm don't think the `git-help` man page even explains how those\nprefixes work.\n\nSo at some point if we want to really encourage people to use\n`git help` instead of `man` we might want to revisit how we present\nthe internal references in the man pages.\n\nObviously not something to solve right now, and I don't know\nwhat a good solution would be.\n\n"},{"id":"554854","messageId":"31f8c254-328b-405f-bc26-b077fa57b5ef@app.fastmail.com","threadId":"66484","inReplyTo":"xmqqik3da2bs.fsf@gitster.g","subject":"Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-13T12:54:56Z","receivedAt":"2026-10-13T12:54:56Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Thanks for the review. I'm going to mark comments that I feel are about style issues\n(like \"could this be explained in a more clear way?\") as just \"style comment\" to deal with\nlater.\n\nIn general if we really want to make sure that this is as clear as possible, I\nthink it would be most effective to do a second revision later (after merging\nthis) where we get feedback from users and find out what folks are confused by.\n\nOn Wed, Oct 7, 2026, at 12:43 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> diff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc\n>> new file mode 100644\n>> index 0000000000..1e00712124\n>> --- /dev/null\n>> +++ b/Documentation/detached-head.adoc\n>> @@ -0,0 +1,43 @@\n>> +`HEAD` is where Git stores your current branch. `HEAD` can either be:\n>> +\n>> +1. A branch, which is your current branch.\n>> +2. A commit ID, when you don't have a current branch.\n>> +   This is called \"detached HEAD state\".\n>\n> HEAD is branch which can either be a branch or something else?\n\nStyle comment. Probably this is the one I'd prioritize the highest.\n\n>     HEAD records the state from which your current changes started.\n>     This can be a branch (the \"current branch\"), or it may not be\n>     associated with any concrete branch (in which case HEAD is\n>     \"detached\")\n>> +It can sometimes be useful for `HEAD` to be a commit ID.\n>> +For example, it lets you look at an old version of your code\n>> +(with `git checkout COMMIT_ID`).\n>\n> To \"look at\" an older state is more versatile than simply running\n> 'git show COMMIT_ID:path', as it allows you to do anything you can\n> do on a branch, such as building and testing.  Thus,\n>\n>  \tA detached HEAD is useful when you want to tentatively visit\n> \tan old state with 'git checkout --detach v0.1', without\n> \thaving to create a dedicated branch for it.\n\nStyle comment.\n\n>> +The only problem is that if you create new commits while in detached\n>> +HEAD state, those commits won't be on a branch.\n>\n> I would suggest rephrasing \"The only problem\" to \"One caveat is\" or\n> something.  When sightseeing and experimenting, the ability to\n> create throw-away commits without the need to clean them up later,\n> or to invent a unique name for a temporary branch, is not a problem.\n> It is an advantage.\n\nStyle comment.\n\n>> This makes those new\n>> +commits much harder to find later. Also, Git considers commits that\n>> +aren't on any branch (or a tag or other reference) to be garbage.\n>> +Git will eventually permanently delete those \"garbage\" commits during\n>> +garbage collection.\n>\n> Correct.\n>\n> Perhaps it is better to clarify this by adding \"after you leave\n> the detached HEAD state\" after \"to find later\".  While you are in\n> the detached HEAD state, you can run 'git log' to find the commits\n> you created there, as you can do everything you normally can on a\n> branch, or use 'git reflog @{now}' for that matter.\n>\n>> +There are 3 main ways you can end up in detached HEAD state\n>> +unintentionally:\n>> +\n>> +1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID\n>> +2. `git checkout v1.3`, where v1.3 is a tag name\n>\n> These I wouldn't call \"unintentionally\".  They are documented and\n> supported ways to do so, and will remain to be so.  \"unknowingly\"\n> may be a more fair way to call these gotchas, though.\n\nThanks, removed \"unintentionally\".\n\n>\n>> +The easiest way to avoid accidentally ending up in detached HEAD state\n>> +is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to\n>> +switch branches. `git switch` won't let you detach unless you explicitly\n>> +pass the `--detach` argument.\n>\n> Correct, but the motivation to 'avoid accidentally ending up' may\n> want to be spelled out.  Most often checking out a tag is to go\n> sightseeing, where you do not want to 'avoid' detached HEAD.\n\nStyle comment.\n\n>> +To get back onto a branch, you can:\n>> +\n>> +1. Switch to the branch you want to be on, with `git switch BRANCHNAME`.\n>> +2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`.\n>> +   You might want to do this if you've created new commits, so that you can\n>> +   find the commit later and so that it won't be garbage collected.\n>\n> Very good.\n>\n>> +If you create commits in detached HEAD state that aren't on a branch,\n>> +you can find them later using linkgit:git-reflog[1].\n>\n> This, as you already said, is \"much harder to find later\" option.\n> There should be a better recovery option described here before\n> resorting to \"git reflog HEAD\" after you switched back.  E.g.,\n>\n>     If you have created commits in detached HEAD state and then\n>     switched away from the state, all is not lost.  \"git checkout\"\n>     would have give you a warning message, like this:\n>\n> \tWarning: you are leaving 2 commits behind, not connected to\n> \tany of your branches\n>\n> \tc816689 typofix the previous\n> \t8e1bff5 decsribe detached HEAD state better\n>\n>     You can create branches to keep them, e.g., \"git branch saved c816689\",\n>     by using the commit object names left there.\n\nThanks, added a mention of this warning. It's a really nice example of the ways\nGit helps avoid issues.\n\n>> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n>> index 2aefea0228..4e9e94e24d 100644\n>> --- a/Documentation/git-checkout.adoc\n>> +++ b/Documentation/git-checkout.adoc\n>> @@ -376,135 +376,8 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n>>  [[DETACHED_HEAD]]\n>>  DETACHED HEAD\n>>  -------------\n>> +include::detached-head.adoc[]\n>\n> Losing the diagrams is a bit concerning.  However, if the intention\n> is to have readers learn how HEAD refers to a branch pointing at a\n> commit with history structured as a DAG elsewhere in a more basic\n> concepts guide, I suspect that it would actually work better.  This\n> could even be reduced to a simple \"see also\" pointer to that other\n> guide.\n>\n> If an existing user only uses 'switch' and never reads 'git help\n> checkout', they are already not seeing these diagrams, or perhaps\n> they learned the concepts elsewhere.  They still manage to\n> understand Git well enough to make use of it, so perhaps this\n> approach is OK.  I dunno.\n\nThanks, good idea to give people a pointer to more info about HEAD.\nI'll try adding a pointer to `git help datamodel`.\n\nI'm not against adding diagrams, but I think if we want to add diagrams that\nshould be a separate project where we actually get feedback from users.\nSimilarly for explaining `HEAD` in more detail.\n\n"},{"id":"554855","messageId":"pull.2250.v2.git.1791896486100.gitgitgadget@gmail.com","threadId":"66484","inReplyTo":"pull.2250.git.1791384721919.gitgitgadget@gmail.com","subject":"[PATCH v2] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-13T13:01:26Z","receivedAt":"2026-10-13T13:01:26Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nThe current explanation has the following issues:\n\n- Says detached HEAD state is useful but doesn't explain why\n- Takes many paragraphs before explaining what detached HEAD state is\n- It's common for users to accidentally end up in detached HEAD state,\n  but it doesn't explain why that might happen\n- One of the UI improvements in `git switch` is to make it harder\n  to detach accidentally, but that isn't advertised.\n  See 7968bef06b (switch: only allow explicit detached HEAD, 2019-03-29)\n- Too many confusing diagrams\n\nWrite a new explanation addressing these issues, and put it in a\nstandalone guide so that we can easily reference it from advice\n(\"see `git help detachedhead`\").\nThe result is a shorter guide that covers more material.\n\nThe framing that \"Git considers commits that aren't on a branch/other\nreference to be garbage\" is taken from Steve Klabnik's tutorial\nhttps://steveklabnik.github.io/jujutsu-tutorial/branching-merging-and-conflicts/anonymous-branches.html.\nIt's funny and it's consistent with the way Git uses the term\n\"garbage collection\".\n\nCo-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n    doc: checkout: rewrite detached HEAD state explanation\n    \n    This is a pretty quick rewrite where we didn't get any user feedback. If\n    we really want to make sure it's clear to users as possible, we should\n    IMO do a second stage later where we ask users which parts are unclear.\n    \n    Changes in v2:\n    \n     * Make the meson.build and Makefile changes (thanks to Kristoffer)\n     * Rename to gitdata-model (thanks to Kristoffer)\n     * Mention commits will be deleted after 90 days to make it seem less\n       scary (thanks to Kristoffer)\n     * Add an \"easily\" qualifier to \"it lets you look at an old version of\n       your code\", to avoid implying that this is the only way (thanks to\n       Junio)\n     * Mention that Git will warn you when switching branches if you're\n       leaving commits behind (thanks to Junio)\n     * Remove \"unintentionally\" (thanks to Junio)\n     * Mention git help datamodel (thanks to Junio)\n    \n    Left the style comments alone (ideas for how to make it more clear) to\n    be potentially addressed in v3, after we finalize the information\n    content.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2250%2Fjvns%2Fdetached-head-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2250/jvns/detached-head-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/2250\n\nRange-diff vs v1:\n\n 1:  efe0f9db36 ! 1:  83139be46f doc: checkout: rewrite detached HEAD state explanation\n     @@ Commit message\n          Co-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n     + ## Documentation/Makefile ##\n     +@@ Documentation/Makefile: MAN7_TXT += gitcore-tutorial.adoc\n     + MAN7_TXT += gitcredentials.adoc\n     + MAN7_TXT += gitcvs-migration.adoc\n     + MAN7_TXT += gitdatamodel.adoc\n     ++MAN7_TXT += gitdetached-head.adoc\n     + MAN7_TXT += gitdiffcore.adoc\n     + MAN7_TXT += giteveryday.adoc\n     + MAN7_TXT += gitfaq.adoc\n     +\n       ## Documentation/detached-head.adoc (new) ##\n      @@\n      +`HEAD` is where Git stores your current branch. `HEAD` can either be:\n     @@ Documentation/detached-head.adoc (new)\n      +   This is called \"detached HEAD state\".\n      +\n      +It can sometimes be useful for `HEAD` to be a commit ID.\n     -+For example, it lets you look at an old version of your code\n     -+(with `git checkout COMMIT_ID`).\n     ++For example, it lets you easily look at an old version of your code\n     ++(with `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`).\n      +\n      +The only problem is that if you create new commits while in detached\n      +HEAD state, those commits won't be on a branch. This makes those new\n      +commits much harder to find later. Also, Git considers commits that\n      +aren't on any branch (or a tag or other reference) to be garbage.\n      +Git will eventually permanently delete those \"garbage\" commits during\n     -+garbage collection.\n     ++garbage collection. Those commits will be deleted after 90 days by\n     ++default, see linkgit:git-gc[1] for more.\n      +\n     -+There are 3 main ways you can end up in detached HEAD state\n     -+unintentionally:\n     ++There are 3 main ways you can end up in detached HEAD state:\n      +\n      +1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID\n      +2. `git checkout v1.3`, where v1.3 is a tag name\n     @@ Documentation/detached-head.adoc (new)\n      +   You might want to do this if you've created new commits, so that you can\n      +   find the commit later and so that it won't be garbage collected.\n      +\n     -+If you create commits in detached HEAD state that aren't on a branch,\n     -+you can find them later using linkgit:git-reflog[1].\n     ++If you switch branches after making commits in detached HEAD state, Git\n     ++will warn you that you might be about to \"lose\" those commits and print\n     ++out the commit ID. You can also always find those commits later using\n     ++linkgit:git-reflog[1].\n     ++\n     ++Here's what that warning looks like:\n     ++\n     ++-------------------------\n     ++Warning: you are leaving 1 commit behind, not connected to\n     ++any of your branches:\n     ++\n     ++  48c09f6 3\n     ++-------------------------\n     ++\n     ++For a more in-depth explanation of how `HEAD` works in Git,\n     ++see linkgit:gitdatamodel[7] (`git help datamodel`).\n      \n       ## Documentation/git-checkout.adoc ##\n      @@ Documentation/git-checkout.adoc: For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n     @@ Documentation/git-checkout.adoc: For more details, see the 'pathspec' entry in l\n       [[ARGUMENT_DISAMBIGUATION]]\n       ARGUMENT DISAMBIGUATION\n      \n     - ## Documentation/gitdetachedhead.adoc (new) ##\n     + ## Documentation/gitdetached-head.adoc (new) ##\n      @@\n     -+gitdetachedhead(7)\n     -+===============\n     ++gitdetached-head(7)\n     ++===================\n      +\n      +NAME\n      +----\n     -+gitdetachedhead - How detached HEAD state works\n     ++gitdetached-head - How detached HEAD state works\n      +\n      +DESCRIPTION\n      +-----------\n     @@ Documentation/gitdetachedhead.adoc (new)\n      +---\n      +Part of the linkgit:git[1] suite\n      \n     + ## Documentation/meson.build ##\n     +@@ Documentation/meson.build: manpages = {\n     +   'gitcredentials.adoc' : 7,\n     +   'gitcvs-migration.adoc' : 7,\n     +   'gitdatamodel.adoc' : 7,\n     ++  'gitdetached-head.adoc' : 7,\n     +   'gitdiffcore.adoc' : 7,\n     +   'giteveryday.adoc' : 7,\n     +   'gitfaq.adoc' : 7,\n     +\n       ## advice.c ##\n      @@ advice.c: void detach_advice(const char *new_name)\n       \t\"\\n\"\n     @@ command-list.txt: gitcore-tutorial                        guide\n       gitcredentials                          guide\n       gitcvs-migration                        guide\n       gitdatamodel                            guide\n     -+gitdetachedhead                         guide\n     ++gitdetached-head                         guide\n       gitdiffcore                             guide\n       giteveryday                             guide\n       gitfaq                                  guide\n\n\n Documentation/Makefile              |   1 +\n Documentation/detached-head.adoc    |  57 ++++++++++++\n Documentation/git-checkout.adoc     | 129 +---------------------------\n Documentation/gitdetached-head.adoc |  14 +++\n Documentation/meson.build           |   1 +\n advice.c                            |   1 +\n command-list.txt                    |   1 +\n 7 files changed, 76 insertions(+), 128 deletions(-)\n create mode 100644 Documentation/detached-head.adoc\n create mode 100644 Documentation/gitdetached-head.adoc\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f8dea4b395..5892f48b06 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -54,6 +54,7 @@ MAN7_TXT += gitcore-tutorial.adoc\n MAN7_TXT += gitcredentials.adoc\n MAN7_TXT += gitcvs-migration.adoc\n MAN7_TXT += gitdatamodel.adoc\n+MAN7_TXT += gitdetached-head.adoc\n MAN7_TXT += gitdiffcore.adoc\n MAN7_TXT += giteveryday.adoc\n MAN7_TXT += gitfaq.adoc\ndiff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc\nnew file mode 100644\nindex 0000000000..712074c0ef\n--- /dev/null\n+++ b/Documentation/detached-head.adoc\n@@ -0,0 +1,57 @@\n+`HEAD` is where Git stores your current branch. `HEAD` can either be:\n+\n+1. A branch, which is your current branch.\n+2. A commit ID, when you don't have a current branch.\n+   This is called \"detached HEAD state\".\n+\n+It can sometimes be useful for `HEAD` to be a commit ID.\n+For example, it lets you easily look at an old version of your code\n+(with `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`).\n+\n+The only problem is that if you create new commits while in detached\n+HEAD state, those commits won't be on a branch. This makes those new\n+commits much harder to find later. Also, Git considers commits that\n+aren't on any branch (or a tag or other reference) to be garbage.\n+Git will eventually permanently delete those \"garbage\" commits during\n+garbage collection. Those commits will be deleted after 90 days by\n+default, see linkgit:git-gc[1] for more.\n+\n+There are 3 main ways you can end up in detached HEAD state:\n+\n+1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID\n+2. `git checkout v1.3`, where v1.3 is a tag name\n+3. `git checkout origin/main`, where `origin/main` is\n+   a remote-tracking branch\n+\n+Checking out a tag puts you in detached HEAD state because `HEAD` can\n+only be a branch or a commit, not a tag or any other reference.\n+So `git checkout TAG` will set HEAD to the commit for that tag.\n+\n+The easiest way to avoid accidentally ending up in detached HEAD state\n+is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to\n+switch branches. `git switch` won't let you detach unless you explicitly\n+pass the `--detach` argument.\n+\n+To get back onto a branch, you can:\n+\n+1. Switch to the branch you want to be on, with `git switch BRANCHNAME`.\n+2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`.\n+   You might want to do this if you've created new commits, so that you can\n+   find the commit later and so that it won't be garbage collected.\n+\n+If you switch branches after making commits in detached HEAD state, Git\n+will warn you that you might be about to \"lose\" those commits and print\n+out the commit ID. You can also always find those commits later using\n+linkgit:git-reflog[1].\n+\n+Here's what that warning looks like:\n+\n+-------------------------\n+Warning: you are leaving 1 commit behind, not connected to\n+any of your branches:\n+\n+  48c09f6 3\n+-------------------------\n+\n+For a more in-depth explanation of how `HEAD` works in Git,\n+see linkgit:gitdatamodel[7] (`git help datamodel`).\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 2aefea0228..4e9e94e24d 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -376,135 +376,8 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n [[DETACHED_HEAD]]\n DETACHED HEAD\n -------------\n-`HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each\n-branch refers to a specific commit. Let's look at a repo with three\n-commits, one of them tagged, and with branch `master` checked out:\n \n-------------\n-           HEAD (refers to branch 'master')\n-            |\n-            v\n-a---b---c  branch 'master' (refers to commit 'c')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-When a commit is created in this state, the branch is updated to refer to\n-the new commit. Specifically, `git commit` creates a new commit `d`, whose\n-parent is commit `c`, and then updates branch `master` to refer to new\n-commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers\n-to commit `d`:\n-\n-------------\n-$ edit; git add; git commit\n-\n-               HEAD (refers to branch 'master')\n-                |\n-                v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is sometimes useful to be able to checkout a commit that is not at\n-the tip of any named branch, or even to create a new commit that is not\n-referenced by a named branch. Let's look at what happens when we\n-checkout commit `b` (here we show two ways this may be done):\n-\n-------------\n-$ git checkout v2.0  # or\n-$ git checkout master^^\n-\n-   HEAD (refers to commit 'b')\n-    |\n-    v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-Notice that regardless of which checkout command we use, `HEAD` now refers\n-directly to commit `b`. This is known as being in detached `HEAD` state.\n-It means simply that `HEAD` refers to a specific commit, as opposed to\n-referring to a named branch. Let's see what happens when we create a commit:\n-\n-------------\n-$ edit; git add; git commit\n-\n-     HEAD (refers to commit 'e')\n-      |\n-      v\n-      e\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-There is now a new commit `e`, but it is referenced only by `HEAD`. We can\n-of course add yet another commit in this state:\n-\n-------------\n-$ edit; git add; git commit\n-\n-\t HEAD (refers to commit 'f')\n-\t  |\n-\t  v\n-      e---f\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-In fact, we can perform all the normal Git operations. But, let's look\n-at what happens when we then checkout `master`:\n-\n-------------\n-$ git checkout master\n-\n-               HEAD (refers to branch 'master')\n-      e---f     |\n-     /          v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is important to realize that at this point nothing refers to commit\n-`f`. Eventually commit `f` (and by extension commit `e`) will be deleted\n-by the routine Git garbage collection process, unless we create a reference\n-before that happens. If we have not yet moved away from commit `f`,\n-any of these will create a reference to it:\n-\n-------------\n-$ git checkout -b foo  # or \"git switch -c foo\"  <1>\n-$ git branch foo                                 <2>\n-$ git tag foo                                    <3>\n-------------\n-<1> creates a new branch `foo`, which refers to commit `f`, and then\n-    updates `HEAD` to refer to branch `foo`. In other words, we'll no longer\n-    be in detached `HEAD` state after this command.\n-<2> similarly creates a new branch `foo`, which refers to commit `f`,\n-    but leaves `HEAD` detached.\n-<3> creates a new tag `foo`, which refers to commit `f`,\n-    leaving `HEAD` detached.\n-\n-If we have moved away from commit `f`, then we must first recover its object\n-name (typically by using git reflog), and then we can create a reference to\n-it. For example, to see the last two commits to which `HEAD` referred, we\n-can use either of these commands:\n-\n-------------\n-$ git reflog -2 HEAD # or\n-$ git log -g -2 HEAD\n-------------\n+include::detached-head.adoc[]\n \n [[ARGUMENT_DISAMBIGUATION]]\n ARGUMENT DISAMBIGUATION\ndiff --git a/Documentation/gitdetached-head.adoc b/Documentation/gitdetached-head.adoc\nnew file mode 100644\nindex 0000000000..a477060db2\n--- /dev/null\n+++ b/Documentation/gitdetached-head.adoc\n@@ -0,0 +1,14 @@\n+gitdetached-head(7)\n+===================\n+\n+NAME\n+----\n+gitdetached-head - How detached HEAD state works\n+\n+DESCRIPTION\n+-----------\n+include::detached-head.adoc[]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex cfa9c67609..6b3141647f 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -197,6 +197,7 @@ manpages = {\n   'gitcredentials.adoc' : 7,\n   'gitcvs-migration.adoc' : 7,\n   'gitdatamodel.adoc' : 7,\n+  'gitdetached-head.adoc' : 7,\n   'gitdiffcore.adoc' : 7,\n   'giteveryday.adoc' : 7,\n   'gitfaq.adoc' : 7,\ndiff --git a/advice.c b/advice.c\nindex 401d047391..43f86c2eaf 100644\n--- a/advice.c\n+++ b/advice.c\n@@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n \t\"\\n\"\n \t\"  git switch -\\n\"\n \t\"\\n\"\n+\t\"Run `git help detachedhead` to learn more.\\n\"\n \t\"Turn off this advice by setting config variable advice.detachedHead to false\\n\\n\");\n \n \tfprintf(stderr, fmt, new_name);\ndiff --git a/command-list.txt b/command-list.txt\nindex 63ae2a67c9..922a1dbd84 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -218,6 +218,7 @@ gitcore-tutorial                        guide\n gitcredentials                          guide\n gitcvs-migration                        guide\n gitdatamodel                            guide\n+gitdetached-head                         guide\n gitdiffcore                             guide\n giteveryday                             guide\n gitfaq                                  guide\n\nbase-commit: 5a7d1e8045ce66c908f62598e26cbb8df7b39a90\n-- \ngitgitgadget\n\n"},{"id":"555061","messageId":"xmqqecdsru6l.fsf@gitster.g","threadId":"66484","inReplyTo":"pull.2250.v2.git.1791896486100.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-14T18:52:34Z","receivedAt":"2026-10-14T18:52:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Write a new explanation addressing these issues, and put it in a\n> standalone guide so that we can easily reference it from advice\n> (\"see `git help detachedhead`\").\n\nIsn't it 'git help detached-head' in this edition?\n\n> Co-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n\nCan the other author also sign it off?\n\n> +Git will eventually permanently delete those \"garbage\" commits during\n> +garbage collection. Those commits will be deleted after 90 days by\n> +default, see linkgit:git-gc[1] for more.\n\nDoes this say 90 days because that is the gc.reflogExpire retention?\n\nIf you create a commit, change your mind, rewind the tip of the\nbranch (e.g., with \"git commit --amend\"), and then keep working, the\noriginal commit before amending would be unreachable from the tip of\nthat branch.  Its reflog entry would then expire after\ngc.reflogExpireUnreachable, which defaults to 30 days.  If your\ncommit were created on a detached HEAD, I am not sure offhand how\nthe thresholds for gc.reflogExpire and gc.reflogExpireUnreachable\ncome into play for HEAD, as HEAD by default flips back and forth\nregularly across branch tips that are not reachable from each other.\nWhen \"gc\" kicks in, the commit HEAD currently points to is unlikely\nto reach the abandoned commit.\n\nIt might be safer to either say \"after 30 days by default\" or\ngeneralize it to \"after a few weeks by default\" to avoid being\noverly prescriptive.\n\n> diff --git a/advice.c b/advice.c\n> index 401d047391..43f86c2eaf 100644\n> --- a/advice.c\n> +++ b/advice.c\n> @@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n>  \t\"\\n\"\n>  \t\"  git switch -\\n\"\n>  \t\"\\n\"\n> +\t\"Run `git help detachedhead` to learn more.\\n\"\n\n\"git help deatched-head\" here, too.\n\n>  \tfprintf(stderr, fmt, new_name);\n> diff --git a/command-list.txt b/command-list.txt\n> index 63ae2a67c9..922a1dbd84 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -218,6 +218,7 @@ gitcore-tutorial                        guide\n>  gitcredentials                          guide\n>  gitcvs-migration                        guide\n>  gitdatamodel                            guide\n> +gitdetached-head                         guide\n>  gitdiffcore                             guide\n>  giteveryday                             guide\n>  gitfaq                                  guide\n\nThis seems to be manually aligned with SP, so compensate the\naddition of \"-\" between detached and head by removing one SP before\nguide on the same line.\n\nThanks.\n\n"},{"id":"555071","messageId":"18556e31-d85b-4b28-b01f-91ae99cbe9cc@app.fastmail.com","threadId":"66484","inReplyTo":"xmqqecdsru6l.fsf@gitster.g","subject":"Re: [PATCH v2] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-14T21:10:40Z","receivedAt":"2026-10-14T21:10:40Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"On Wed, Oct 14, 2026, at 2:52 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> Write a new explanation addressing these issues, and put it in a\n>> standalone guide so that we can easily reference it from advice\n>> (\"see `git help detachedhead`\").\n>\n> Isn't it 'git help detached-head' in this edition?\n\nWill fix.\n\n>> Co-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n>> Signed-off-by: Julia Evans <julia@jvns.ca>\n>\n> Can the other author also sign it off?\n\nWill do.\n\n>> +Git will eventually permanently delete those \"garbage\" commits during\n>> +garbage collection. Those commits will be deleted after 90 days by\n>> +default, see linkgit:git-gc[1] for more.\n>\n> Does this say 90 days because that is the gc.reflogExpire retention?\n\nYes, I wasn't sure how it works exactly.\n\n> If you create a commit, change your mind, rewind the tip of the\n> branch (e.g., with \"git commit --amend\"), and then keep working, the\n> original commit before amending would be unreachable from the tip of\n> that branch.  Its reflog entry would then expire after\n> gc.reflogExpireUnreachable, which defaults to 30 days.  If your\n> commit were created on a detached HEAD, I am not sure offhand how\n> the thresholds for gc.reflogExpire and gc.reflogExpireUnreachable\n> come into play for HEAD, as HEAD by default flips back and forth\n> regularly across branch tips that are not reachable from each other.\n> When \"gc\" kicks in, the commit HEAD currently points to is unlikely\n> to reach the abandoned commit.\n>\n> It might be safer to either say \"after 30 days by default\" or\n> generalize it to \"after a few weeks by default\" to avoid being\n> overly prescriptive.\n\nWill change to \"30 days\", I think \"30 days\" makes it a tiny bit easier\nfor someone to figure out where that number might come from.\n\n>> diff --git a/advice.c b/advice.c\n>> index 401d047391..43f86c2eaf 100644\n>> --- a/advice.c\n>> +++ b/advice.c\n>> @@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n>>  \t\"\\n\"\n>>  \t\"  git switch -\\n\"\n>>  \t\"\\n\"\n>> +\t\"Run `git help detachedhead` to learn more.\\n\"\n>\n> \"git help deatched-head\" here, too.\n\nWill do.\n\n>>  \tfprintf(stderr, fmt, new_name);\n>> diff --git a/command-list.txt b/command-list.txt\n>> index 63ae2a67c9..922a1dbd84 100644\n>> --- a/command-list.txt\n>> +++ b/command-list.txt\n>> @@ -218,6 +218,7 @@ gitcore-tutorial                        guide\n>>  gitcredentials                          guide\n>>  gitcvs-migration                        guide\n>>  gitdatamodel                            guide\n>> +gitdetached-head                         guide\n>>  gitdiffcore                             guide\n>>  giteveryday                             guide\n>>  gitfaq                                  guide\n>\n> This seems to be manually aligned with SP, so compensate the\n> addition of \"-\" between detached and head by removing one SP before\n> guide on the same line.\n\nWill do.\n\n"},{"id":"555195","messageId":"pull.2250.v3.git.1792097882327.gitgitgadget@gmail.com","threadId":"66484","inReplyTo":"pull.2250.git.1791384721919.gitgitgadget@gmail.com","subject":"[PATCH v3] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-15T20:58:02Z","receivedAt":"2026-10-15T20:58:02Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nThe current explanation has the following issues:\n\n- Says detached HEAD state is useful but doesn't explain why\n- Takes many paragraphs before explaining what detached HEAD state is\n- It's common for users to accidentally end up in detached HEAD state,\n  but it doesn't explain why that might happen\n- One of the UI improvements in `git switch` is to make it harder\n  to detach accidentally, but that isn't advertised.\n  See 7968bef06b (switch: only allow explicit detached HEAD, 2019-03-29)\n- Too many confusing diagrams\n\nWrite a new explanation addressing these issues, and put it in a\nstandalone guide so that we can easily reference it from advice\n(\"see `git help detached-head`\").\nThe result is a shorter guide that covers more material.\n\nThe framing that \"Git considers commits that aren't on a branch/other\nreference to be garbage\" is taken from Steve Klabnik's tutorial\nhttps://steveklabnik.github.io/jujutsu-tutorial/branching-merging-and-conflicts/anonymous-branches.html.\nIt's funny and it's consistent with the way Git uses the term\n\"garbage collection\".\n\nCo-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n    doc: checkout: rewrite detached HEAD state explanation\n    \n    This is a pretty quick rewrite where we didn't get any user feedback. If\n    we really want to make sure it's clear to users as possible, we should\n    IMO do a second stage later where we ask users which parts are unclear.\n    \n    Changes in v2:\n    \n     * Make the meson.build and Makefile changes (thanks to Kristoffer)\n     * Rename to gitdata-model (thanks to Kristoffer)\n     * Mention commits will be deleted after 90 days to make it seem less\n       scary (thanks to Kristoffer)\n     * Add an \"easily\" qualifier to \"it lets you look at an old version of\n       your code\", to avoid implying that this is the only way (thanks to\n       Junio)\n     * Mention that Git will warn you when switching branches if you're\n       leaving commits behind (thanks to Junio)\n     * Remove \"unintentionally\" (thanks to Junio)\n     * Mention git help datamodel (thanks to Junio)\n    \n    Changes in v3:\n    \n    I went through the style comments from v1.\n    \n    content changes:\n    \n     * Change \"90 days\" to \"30 days\" (thanks to Junio)\n     * Say that HEAD is where Git stores your \"current branch or commit\" to\n       make the first sentence read better (thanks to Junio)\n     * Mention git switch --detach a little earlier (thanks to Kristoffer)\n     * Replace \"the only problem\" with \"it's important to know that\" (thanks\n       to Junio)\n    \n    formatting changes etc:\n    \n     * Replace help detachedhead with help detached-head (thanks to Junio)\n     * Fix spacing in command-list.txt (thanks to Junio)\n     * Get Marie's signoff (thanks to Junio)\n    \n    non-changes: Left these phrases alone because I don't think the proposed\n    changes would make it more clear.\n    \n     * \"3 main ways you can end up in detached HEAD state\"\n     * \"to look at an old version of your code\"\n     * \"avoid accidentally ending up\"\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2250%2Fjvns%2Fdetached-head-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2250/jvns/detached-head-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/2250\n\nRange-diff vs v2:\n\n 1:  83139be46f ! 1:  0ab8814664 doc: checkout: rewrite detached HEAD state explanation\n     @@ Commit message\n      \n          Write a new explanation addressing these issues, and put it in a\n          standalone guide so that we can easily reference it from advice\n     -    (\"see `git help detachedhead`\").\n     +    (\"see `git help detached-head`\").\n          The result is a shorter guide that covers more material.\n      \n          The framing that \"Git considers commits that aren't on a branch/other\n     @@ Commit message\n          \"garbage collection\".\n      \n          Co-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n     +    Signed-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n       ## Documentation/Makefile ##\n     @@ Documentation/Makefile: MAN7_TXT += gitcore-tutorial.adoc\n      \n       ## Documentation/detached-head.adoc (new) ##\n      @@\n     -+`HEAD` is where Git stores your current branch. `HEAD` can either be:\n     ++`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:\n      +\n      +1. A branch, which is your current branch.\n      +2. A commit ID, when you don't have a current branch.\n     @@ Documentation/detached-head.adoc (new)\n      +For example, it lets you easily look at an old version of your code\n      +(with `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`).\n      +\n     -+The only problem is that if you create new commits while in detached\n     -+HEAD state, those commits won't be on a branch. This makes those new\n     -+commits much harder to find later. Also, Git considers commits that\n     -+aren't on any branch (or a tag or other reference) to be garbage.\n     ++But it's important to know that if you create new commits while in\n     ++detached HEAD state, those commits won't be on a branch. This makes\n     ++those new commits much harder to find later. Also, Git considers commits\n     ++that aren't on any branch (or a tag or other reference) to be garbage.\n      +Git will eventually permanently delete those \"garbage\" commits during\n     -+garbage collection. Those commits will be deleted after 90 days by\n     ++garbage collection. Those commits will be deleted after 30 days by\n      +default, see linkgit:git-gc[1] for more.\n      +\n      +There are 3 main ways you can end up in detached HEAD state:\n     @@ advice.c: void detach_advice(const char *new_name)\n       \t\"\\n\"\n       \t\"  git switch -\\n\"\n       \t\"\\n\"\n     -+\t\"Run `git help detachedhead` to learn more.\\n\"\n     ++\t\"Run `git help detached-head` to learn more.\\n\"\n       \t\"Turn off this advice by setting config variable advice.detachedHead to false\\n\\n\");\n       \n       \tfprintf(stderr, fmt, new_name);\n     @@ command-list.txt: gitcore-tutorial                        guide\n       gitcredentials                          guide\n       gitcvs-migration                        guide\n       gitdatamodel                            guide\n     -+gitdetached-head                         guide\n     ++gitdetached-head                        guide\n       gitdiffcore                             guide\n       giteveryday                             guide\n       gitfaq                                  guide\n\n\n Documentation/Makefile              |   1 +\n Documentation/detached-head.adoc    |  57 ++++++++++++\n Documentation/git-checkout.adoc     | 129 +---------------------------\n Documentation/gitdetached-head.adoc |  14 +++\n Documentation/meson.build           |   1 +\n advice.c                            |   1 +\n command-list.txt                    |   1 +\n 7 files changed, 76 insertions(+), 128 deletions(-)\n create mode 100644 Documentation/detached-head.adoc\n create mode 100644 Documentation/gitdetached-head.adoc\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f8dea4b395..5892f48b06 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -54,6 +54,7 @@ MAN7_TXT += gitcore-tutorial.adoc\n MAN7_TXT += gitcredentials.adoc\n MAN7_TXT += gitcvs-migration.adoc\n MAN7_TXT += gitdatamodel.adoc\n+MAN7_TXT += gitdetached-head.adoc\n MAN7_TXT += gitdiffcore.adoc\n MAN7_TXT += giteveryday.adoc\n MAN7_TXT += gitfaq.adoc\ndiff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc\nnew file mode 100644\nindex 0000000000..d8e59e10c6\n--- /dev/null\n+++ b/Documentation/detached-head.adoc\n@@ -0,0 +1,57 @@\n+`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:\n+\n+1. A branch, which is your current branch.\n+2. A commit ID, when you don't have a current branch.\n+   This is called \"detached HEAD state\".\n+\n+It can sometimes be useful for `HEAD` to be a commit ID.\n+For example, it lets you easily look at an old version of your code\n+(with `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`).\n+\n+But it's important to know that if you create new commits while in\n+detached HEAD state, those commits won't be on a branch. This makes\n+those new commits much harder to find later. Also, Git considers commits\n+that aren't on any branch (or a tag or other reference) to be garbage.\n+Git will eventually permanently delete those \"garbage\" commits during\n+garbage collection. Those commits will be deleted after 30 days by\n+default, see linkgit:git-gc[1] for more.\n+\n+There are 3 main ways you can end up in detached HEAD state:\n+\n+1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID\n+2. `git checkout v1.3`, where v1.3 is a tag name\n+3. `git checkout origin/main`, where `origin/main` is\n+   a remote-tracking branch\n+\n+Checking out a tag puts you in detached HEAD state because `HEAD` can\n+only be a branch or a commit, not a tag or any other reference.\n+So `git checkout TAG` will set HEAD to the commit for that tag.\n+\n+The easiest way to avoid accidentally ending up in detached HEAD state\n+is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to\n+switch branches. `git switch` won't let you detach unless you explicitly\n+pass the `--detach` argument.\n+\n+To get back onto a branch, you can:\n+\n+1. Switch to the branch you want to be on, with `git switch BRANCHNAME`.\n+2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`.\n+   You might want to do this if you've created new commits, so that you can\n+   find the commit later and so that it won't be garbage collected.\n+\n+If you switch branches after making commits in detached HEAD state, Git\n+will warn you that you might be about to \"lose\" those commits and print\n+out the commit ID. You can also always find those commits later using\n+linkgit:git-reflog[1].\n+\n+Here's what that warning looks like:\n+\n+-------------------------\n+Warning: you are leaving 1 commit behind, not connected to\n+any of your branches:\n+\n+  48c09f6 3\n+-------------------------\n+\n+For a more in-depth explanation of how `HEAD` works in Git,\n+see linkgit:gitdatamodel[7] (`git help datamodel`).\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 2aefea0228..4e9e94e24d 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -376,135 +376,8 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n [[DETACHED_HEAD]]\n DETACHED HEAD\n -------------\n-`HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each\n-branch refers to a specific commit. Let's look at a repo with three\n-commits, one of them tagged, and with branch `master` checked out:\n \n-------------\n-           HEAD (refers to branch 'master')\n-            |\n-            v\n-a---b---c  branch 'master' (refers to commit 'c')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-When a commit is created in this state, the branch is updated to refer to\n-the new commit. Specifically, `git commit` creates a new commit `d`, whose\n-parent is commit `c`, and then updates branch `master` to refer to new\n-commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers\n-to commit `d`:\n-\n-------------\n-$ edit; git add; git commit\n-\n-               HEAD (refers to branch 'master')\n-                |\n-                v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is sometimes useful to be able to checkout a commit that is not at\n-the tip of any named branch, or even to create a new commit that is not\n-referenced by a named branch. Let's look at what happens when we\n-checkout commit `b` (here we show two ways this may be done):\n-\n-------------\n-$ git checkout v2.0  # or\n-$ git checkout master^^\n-\n-   HEAD (refers to commit 'b')\n-    |\n-    v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-Notice that regardless of which checkout command we use, `HEAD` now refers\n-directly to commit `b`. This is known as being in detached `HEAD` state.\n-It means simply that `HEAD` refers to a specific commit, as opposed to\n-referring to a named branch. Let's see what happens when we create a commit:\n-\n-------------\n-$ edit; git add; git commit\n-\n-     HEAD (refers to commit 'e')\n-      |\n-      v\n-      e\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-There is now a new commit `e`, but it is referenced only by `HEAD`. We can\n-of course add yet another commit in this state:\n-\n-------------\n-$ edit; git add; git commit\n-\n-\t HEAD (refers to commit 'f')\n-\t  |\n-\t  v\n-      e---f\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-In fact, we can perform all the normal Git operations. But, let's look\n-at what happens when we then checkout `master`:\n-\n-------------\n-$ git checkout master\n-\n-               HEAD (refers to branch 'master')\n-      e---f     |\n-     /          v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is important to realize that at this point nothing refers to commit\n-`f`. Eventually commit `f` (and by extension commit `e`) will be deleted\n-by the routine Git garbage collection process, unless we create a reference\n-before that happens. If we have not yet moved away from commit `f`,\n-any of these will create a reference to it:\n-\n-------------\n-$ git checkout -b foo  # or \"git switch -c foo\"  <1>\n-$ git branch foo                                 <2>\n-$ git tag foo                                    <3>\n-------------\n-<1> creates a new branch `foo`, which refers to commit `f`, and then\n-    updates `HEAD` to refer to branch `foo`. In other words, we'll no longer\n-    be in detached `HEAD` state after this command.\n-<2> similarly creates a new branch `foo`, which refers to commit `f`,\n-    but leaves `HEAD` detached.\n-<3> creates a new tag `foo`, which refers to commit `f`,\n-    leaving `HEAD` detached.\n-\n-If we have moved away from commit `f`, then we must first recover its object\n-name (typically by using git reflog), and then we can create a reference to\n-it. For example, to see the last two commits to which `HEAD` referred, we\n-can use either of these commands:\n-\n-------------\n-$ git reflog -2 HEAD # or\n-$ git log -g -2 HEAD\n-------------\n+include::detached-head.adoc[]\n \n [[ARGUMENT_DISAMBIGUATION]]\n ARGUMENT DISAMBIGUATION\ndiff --git a/Documentation/gitdetached-head.adoc b/Documentation/gitdetached-head.adoc\nnew file mode 100644\nindex 0000000000..a477060db2\n--- /dev/null\n+++ b/Documentation/gitdetached-head.adoc\n@@ -0,0 +1,14 @@\n+gitdetached-head(7)\n+===================\n+\n+NAME\n+----\n+gitdetached-head - How detached HEAD state works\n+\n+DESCRIPTION\n+-----------\n+include::detached-head.adoc[]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex cfa9c67609..6b3141647f 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -197,6 +197,7 @@ manpages = {\n   'gitcredentials.adoc' : 7,\n   'gitcvs-migration.adoc' : 7,\n   'gitdatamodel.adoc' : 7,\n+  'gitdetached-head.adoc' : 7,\n   'gitdiffcore.adoc' : 7,\n   'giteveryday.adoc' : 7,\n   'gitfaq.adoc' : 7,\ndiff --git a/advice.c b/advice.c\nindex 401d047391..8d2c1ff1ee 100644\n--- a/advice.c\n+++ b/advice.c\n@@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n \t\"\\n\"\n \t\"  git switch -\\n\"\n \t\"\\n\"\n+\t\"Run `git help detached-head` to learn more.\\n\"\n \t\"Turn off this advice by setting config variable advice.detachedHead to false\\n\\n\");\n \n \tfprintf(stderr, fmt, new_name);\ndiff --git a/command-list.txt b/command-list.txt\nindex 63ae2a67c9..7fb57765fb 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -218,6 +218,7 @@ gitcore-tutorial                        guide\n gitcredentials                          guide\n gitcvs-migration                        guide\n gitdatamodel                            guide\n+gitdetached-head                        guide\n gitdiffcore                             guide\n giteveryday                             guide\n gitfaq                                  guide\n\nbase-commit: 5a7d1e8045ce66c908f62598e26cbb8df7b39a90\n-- \ngitgitgadget\n\n"},{"id":"555200","messageId":"xmqqecdqk2qr.fsf@gitster.g","threadId":"66484","inReplyTo":"pull.2250.v3.git.1792097882327.gitgitgadget@gmail.com","subject":"Re: [PATCH v3] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-15T22:39:24Z","receivedAt":"2026-10-15T22:39:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n>     non-changes: Left these phrases alone because I don't think the proposed\n>     changes would make it more clear.\n\nThose who contributed their time to review this document did so\nbelieving they were suggesting improvements.  Simply dismissing\ntheir feedback as \"style\" in 'v2' without explaining what you\ndisliked about their suggestions is unhelpful.  It is hard to know\nwhat to make of a dismissal that lacks any supporting reasoning,\nother than \"I don't think\".\n\n> diff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc\n> new file mode 100644\n> index 0000000000..d8e59e10c6\n> --- /dev/null\n> +++ b/Documentation/detached-head.adoc\n> @@ -0,0 +1,57 @@\n> +`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:\n> +\n> +1. A branch, which is your current branch.\n> +2. A commit ID, when you don't have a current branch.\n> +   This is called \"detached HEAD state\".\n\nDifferences between v1 and v3 did not make much improvement in this\narea, though.  The phrase \"branch or commit\" highlights the\ndistinction, but it fails to clarify what is common to both, which\nis equally important.\n\nPerhaps restarting from something along this line\n\n    HEAD records the state from which your current changes started.\n    This can be a branch (the \"current branch\"), or it be a commit,\n    (in which case HEAD is \"detached\").\n\nand polishing further may take us to a better end state.  An\nimportant distinction that is not captured in the above (or your\nversion) that we may want to cover is that when you are on a branch,\nyour changes will grow that branch, and when you are not on a\nbranch, your changes will not affect any branch and stay temporary.\n\n> +It can sometimes be useful for `HEAD` to be a commit ID.\n> +For example, it lets you easily look at an old version of your code\n> +(with `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`).\n\nWe should use a verb stronger than \"look at\" to emphasize the\nprimary advantage of having the entire state visible in the working\ntree.  If a user merely wants to read or inspect a single historical\nfile, they can do so easily without moving their HEAD by running\n'git show COMMIT_ID:path/to/file'.  Checking out a commit allows\nsomething much more powerful.  It restores your entire working\ndirectory to that exact state.\n\n    In the detached HEAD state, you can safely build, run, and\n    experiment with any historical version of your codebase, without\n    having to worry about clobbering your branches, and you do not\n    have to clutter your repository with temporary branches.\n\nI said \"safely build, run\" because you had \"old version of your\nCODE\" in the paragraph, but if you can give examples outside the\nprogramming area, that would be even better.  E.g.,\n\n- Writers may able to rebuild and locally preview a complete\n  historical version of a book or documentation site to see how\n  cross-references and formatting rendered at that time.\n\n- Game Designers may open an entire historical scene in an editor\n  (like Unity or Blender) where assets, textures, and coordinates\n  must all exist in a precise, interconnected state to load\n  correctly.\n\n- Data Scientists may execute and reproduce a specific historical\n  data pipeline or model run using the exact combination of scripts\n  and datasets that existed on that day.\n\n\n> +There are 3 main ways you can end up in detached HEAD state:\n> +\n> +1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID\n> +2. `git checkout v1.3`, where v1.3 is a tag name\n> +3. `git checkout origin/main`, where `origin/main` is\n> +   a remote-tracking branch\n> +\n> +Checking out a tag puts you in detached HEAD state because `HEAD` can\n> +only be a branch or a commit, not a tag or any other reference.\n> +So `git checkout TAG` will set HEAD to the commit for that tag.\n\nA more standard phrase for \"the commit for that tag\" is \"the tagged\ncommit\".\n\nBecause we will recommend \"switch\" to be a way to require to be more\nexplicit when users mean to go into the detached HEAD state soon\nbelow, I think we would want to move the \"checkout <COMMIT>\" and\n\"switch --detach <COMMIT>\" description to here from the earlier\n\"sometimes useful\" paragraph, to complement the above list of ways\nto detach your HEAD.\n\n> +If you switch branches after making commits in detached HEAD state, Git\n> +will warn you that you might be about to \"lose\" those commits and print\n> +out the commit ID. You can also always find those commits later using\n> +linkgit:git-reflog[1].\n> +\n> +Here's what that warning looks like:\n> +\n> +-------------------------\n> +Warning: you are leaving 1 commit behind, not connected to\n> +any of your branches:\n> +\n> +  48c09f6 3\n> +-------------------------\n\nYour readers can guess that the 7 digit hex may probably be the\ncommit object name you are about to lose, but you should use a bit\nmore realistic descriptive title, not \"3\", to avoid confusion.  I\nknow many users do not write a good log message, but even a single\nword \"bugfix\" is better than \"3\" ;-)\n\n\n"},{"id":"555242","messageId":"01232f89-6f57-48d2-b6de-d51c91b6fdb3@app.fastmail.com","threadId":"66484","inReplyTo":"xmqqecdqk2qr.fsf@gitster.g","subject":"Re: [PATCH v3] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-16T14:55:38Z","receivedAt":"2026-10-16T14:55:38Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Thu, Oct 15, 2026, at 6:39 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>>     non-changes: Left these phrases alone because I don't think the proposed\n>>     changes would make it more clear.\n>\n> Those who contributed their time to review this document did so\n> believing they were suggesting improvements.  Simply dismissing\n> their feedback as \"style\" in 'v2' without explaining what you\n> disliked about their suggestions is unhelpful.  It is hard to know\n> what to make of a dismissal that lacks any supporting reasoning,\n> other than \"I don't think\".\n\nMy job to is write clear technical explanations and a big part of what I do\nis to try to reconcile the point of view of experts (who understand how the\nsoftware works) and users (who know which parts are confusing).\nI think we've talked about this \"curse of knowledge\" issue before.\n\nI'm always happy to have a detailed discussion when it comes to accuracy,\nand I'm extremely grateful for the time everyone puts in when it comes\nto pointing out accuracy issues, and when figuring out when it's appropriate\nto occasionally tell a \"white lie\" :)\n\nThe reason I was a little brief is that these in depth discussions about how\nto explain a concept as clearly as possible to users are not effective if\nthere are no users involved in the process. It takes a lot of time without\nmaking substantial improvements.\n\nThere are some more ideas on this site about having a \"user-centric\"\nmindset, like using learner personas. Happy to talk about that if you think\nit would be helpful. Sometimes tone can get lost here so let me know if it\nwould be helpful to have a video call!\nhttps://www.writethedocs.org/blog/newsletter-june-2025/#help-contributors-think-like-users\n\n>> diff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc\n>> new file mode 100644\n>> index 0000000000..d8e59e10c6\n>> --- /dev/null\n>> +++ b/Documentation/detached-head.adoc\n>> @@ -0,0 +1,57 @@\n>> +`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:\n>> +\n>> +1. A branch, which is your current branch.\n>> +2. A commit ID, when you don't have a current branch.\n>> +   This is called \"detached HEAD state\".\n>\n> Differences between v1 and v3 did not make much improvement in this\n> area, though.  The phrase \"branch or commit\" highlights the\n> distinction, but it fails to clarify what is common to both, which\n> is equally important.\n>\n> Perhaps restarting from something along this line\n>\n>     HEAD records the state from which your current changes started.\n>     This can be a branch (the \"current branch\"), or it be a commit,\n>     (in which case HEAD is \"detached\").\n>\n> and polishing further may take us to a better end state.  An\n> important distinction that is not captured in the above (or your\n> version) that we may want to cover is that when you are on a branch,\n> your changes will grow that branch, and when you are not on a\n> branch, your changes will not affect any branch and stay temporary.\n\nThis is a case where if we really want to make sure it's clear, we need\nto go get feedback from users. There's likely a better way to explain it\nbut I don't think that this conversation will result in an improvement.\nReally doing a good job of explaining HEAD is a pretty big project.\n\nIt's not clear to me if you think the current wording is unusable\nor if you just think it could be better.\n\n>> +It can sometimes be useful for `HEAD` to be a commit ID.\n>> +For example, it lets you easily look at an old version of your code\n>> +(with `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`).\n>\n> We should use a verb stronger than \"look at\" to emphasize the\n> primary advantage of having the entire state visible in the working\n> tree.  If a user merely wants to read or inspect a single historical\n> file, they can do so easily without moving their HEAD by running\n> 'git show COMMIT_ID:path/to/file'.  Checking out a commit allows\n> something much more powerful.  It restores your entire working\n> directory to that exact state.\n\nChanged this to \"check out an old version of your project\".\n\n>     In the detached HEAD state, you can safely build, run, and\n>     experiment with any historical version of your codebase, without\n>     having to worry about clobbering your branches, and you do not\n>     have to clutter your repository with temporary branches.\n>\n> I said \"safely build, run\" because you had \"old version of your\n> CODE\" in the paragraph, but if you can give examples outside the\n> programming area, that would be even better.  E.g.,\n>\n> - Writers may able to rebuild and locally preview a complete\n>   historical version of a book or documentation site to see how\n>   cross-references and formatting rendered at that time.\n>\n> - Game Designers may open an entire historical scene in an editor\n>   (like Unity or Blender) where assets, textures, and coordinates\n>   must all exist in a precise, interconnected state to load\n>   correctly.\n>\n> - Data Scientists may execute and reproduce a specific historical\n>   data pipeline or model run using the exact combination of scripts\n>   and datasets that existed on that day.\n\nI like these examples, added a shorter version of a couple of\nthem. Also replaced \"code\" with \"project\" to make it more general.\n\n>\n>> +There are 3 main ways you can end up in detached HEAD state:\n>> +\n>> +1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID\n>> +2. `git checkout v1.3`, where v1.3 is a tag name\n>> +3. `git checkout origin/main`, where `origin/main` is\n>> +   a remote-tracking branch\n>> +\n>> +Checking out a tag puts you in detached HEAD state because `HEAD` can\n>> +only be a branch or a commit, not a tag or any other reference.\n>> +So `git checkout TAG` will set HEAD to the commit for that tag.\n>\n> A more standard phrase for \"the commit for that tag\" is \"the tagged\n> commit\".\n\nWill do.\n\n> Because we will recommend \"switch\" to be a way to require to be more\n> explicit when users mean to go into the detached HEAD state soon\n> below, I think we would want to move the \"checkout <COMMIT>\" and\n> \"switch --detach <COMMIT>\" description to here from the earlier\n> \"sometimes useful\" paragraph, to complement the above list of ways\n> to detach your HEAD.\n\nAgreed there's some duplication here we can fix, will do.\n\n>> +If you switch branches after making commits in detached HEAD state, Git\n>> +will warn you that you might be about to \"lose\" those commits and print\n>> +out the commit ID. You can also always find those commits later using\n>> +linkgit:git-reflog[1].\n>> +\n>> +Here's what that warning looks like:\n>> +\n>> +-------------------------\n>> +Warning: you are leaving 1 commit behind, not connected to\n>> +any of your branches:\n>> +\n>> +  48c09f6 3\n>> +-------------------------\n>\n> Your readers can guess that the 7 digit hex may probably be the\n> commit object name you are about to lose, but you should use a bit\n> more realistic descriptive title, not \"3\", to avoid confusion.  I\n> know many users do not write a good log message, but even a single\n> word \"bugfix\" is better than \"3\" ;-)\n\nOops, I meant to fix that before, thanks.\n\n"},{"id":"555252","messageId":"xmqqzewdfuhm.fsf@gitster.g","threadId":"66484","inReplyTo":"01232f89-6f57-48d2-b6de-d51c91b6fdb3@app.fastmail.com","subject":"Re: [PATCH v3] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-16T17:03:33Z","receivedAt":"2026-10-16T17:03:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> This is a case where if we really want to make sure it's clear, we need\n> to go get feedback from users. There's likely a better way to explain it\n> but I don't think that this conversation will result in an improvement.\n> Really doing a good job of explaining HEAD is a pretty big project.\n>\n> It's not clear to me if you think the current wording is unusable\n> or if you just think it could be better.\n\nThen let me make it clear.\n\nI do not know if your version is unusable or good enough, but if you\nare going to take one version to guinea-pig readers to test and\npolish starting from that version, I think what I gave you would\ngive us a better starting point.\n\nOtherwise I would not be suggesting replacements (this applies to\nall other points in the message you are responding to).\n\nThanks.\n\n"},{"id":"555260","messageId":"7e888746-4220-494d-b8ab-00bdd5da5876@app.fastmail.com","threadId":"66484","inReplyTo":"xmqqzewdfuhm.fsf@gitster.g","subject":"Re: [PATCH v3] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-16T18:35:19Z","receivedAt":"2026-10-16T18:35:19Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"On Fri, Oct 16, 2026, at 1:03 PM, Junio C Hamano wrote:\n> \"Julia Evans\" <julia@jvns.ca> writes:\n>\n>> This is a case where if we really want to make sure it's clear, we need\n>> to go get feedback from users. There's likely a better way to explain it\n>> but I don't think that this conversation will result in an improvement.\n>> Really doing a good job of explaining HEAD is a pretty big project.\n>>\n>> It's not clear to me if you think the current wording is unusable\n>> or if you just think it could be better.\n>\n> Then let me make it clear.\n>\n> I do not know if your version is unusable or good enough, but if you\n> are going to take one version to guinea-pig readers to test and\n> polish starting from that version, I think what I gave you would\n> give us a better starting point.\n\nI'm not planning to test this version on readers right now, no.\n\nHere's what I wrote in the first email in this thread:\n\n    Often when rewriting these explanations I go through a process where I\n    ask users' feedback on the old explanation. Here I didn't do that\n    basically because that process takes a long time and I'm working on a\n    bunch of other time consuming docs projects so I did a quick rewrite\n    based on my previous experience explaining detached HEAD state to folks.\n\n    I thought this could be a nice quick docs win on a topic which many\n    users find quite confusing. If the changes here are too controversial I\n    can drop it for now.\n    \n\n"},{"id":"555267","messageId":"pull.2250.v4.git.1792177409868.gitgitgadget@gmail.com","threadId":"66484","inReplyTo":"pull.2250.git.1791384721919.gitgitgadget@gmail.com","subject":"[PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-16T19:03:29Z","receivedAt":"2026-10-16T19:03:29Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nThe current explanation has the following issues:\n\n- Says detached HEAD state is useful but doesn't explain why\n- Takes many paragraphs before explaining what detached HEAD state is\n- It's common for users to accidentally end up in detached HEAD state,\n  but it doesn't explain why that might happen\n- One of the UI improvements in `git switch` is to make it harder\n  to detach accidentally, but that isn't advertised.\n  See 7968bef06b (switch: only allow explicit detached HEAD, 2019-03-29)\n- Too many confusing diagrams\n\nWrite a new explanation addressing these issues, and put it in a\nstandalone guide so that we can easily reference it from advice\n(\"see `git help detached-head`\").\nThe result is a shorter guide that covers more material.\n\nThe framing that \"Git considers commits that aren't on a branch/other\nreference to be garbage\" is taken from Steve Klabnik's tutorial\nhttps://steveklabnik.github.io/jujutsu-tutorial/branching-merging-and-conflicts/anonymous-branches.html.\nIt's funny and it's consistent with the way Git uses the term\n\"garbage collection\".\n\nCo-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n    doc: checkout: rewrite detached HEAD state explanation\n    \n    This is a pretty quick rewrite where we didn't get any user feedback. If\n    we really want to make sure it's clear to users as possible, we should\n    IMO do a second stage later where we ask users which parts are unclear.\n    \n    Changes in v2:\n    \n     * Make the meson.build and Makefile changes (thanks to Kristoffer)\n     * Rename to gitdata-model (thanks to Kristoffer)\n     * Mention commits will be deleted after 90 days to make it seem less\n       scary (thanks to Kristoffer)\n     * Add an \"easily\" qualifier to \"it lets you look at an old version of\n       your code\", to avoid implying that this is the only way (thanks to\n       Junio)\n     * Mention that Git will warn you when switching branches if you're\n       leaving commits behind (thanks to Junio)\n     * Remove \"unintentionally\" (thanks to Junio)\n     * Mention git help datamodel (thanks to Junio)\n    \n    Changes in v3:\n    \n    I went through the style comments from v1.\n    \n    content changes:\n    \n     * Change \"90 days\" to \"30 days\" (thanks to Junio)\n     * Say that HEAD is where Git stores your \"current branch or commit\" to\n       make the first sentence read better (thanks to Junio)\n     * Mention git switch --detach a little earlier (thanks to Kristoffer)\n     * Replace \"the only problem\" with \"it's important to know that\" (thanks\n       to Junio)\n    \n    formatting changes etc:\n    \n     * Replace help detachedhead with help detached-head (thanks to Junio)\n     * Fix spacing in command-list.txt (thanks to Junio)\n     * Get Marie's signoff (thanks to Junio)\n    \n    non-changes: Left these phrases alone because I don't think the proposed\n    changes would make it more clear.\n    \n     * \"3 main ways you can end up in detached HEAD state\"\n     * \"to look at an old version of your code\"\n     * \"avoid accidentally ending up\"\n    \n    Changes in v4:\n    \n     * Fix commit message in example: \"fix bug\", not \"3\" (thanks to Junio)\n     * \"commit for that tag\" -> \"tagged commit\" (thanks to Junio)\n     * Move \"git checkout COMMIT_ID or git switch --detach COMMIT_ID\" down\n       to the \"3 main ways\" list to reduce duplication (thanks to Junio)\n     * Add some examples and be clearer about how detached HEAD state lets\n       you check out an old version of the project. (thanks to Junio)\n    \n    non-changes:\n    \n     * It's probably possible to explain HEAD better. That seems like a big\n       project to me since HEAD in Git is a very tricky topic. I think it\n       would be better to address in a separate patch series to have more\n       time to think it through. Or if we think it's not possible to merge\n       this without explaining HEAD better then I guess it shouldn't be\n       merged.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2250%2Fjvns%2Fdetached-head-v4\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2250/jvns/detached-head-v4\nPull-Request: https://github.com/gitgitgadget/git/pull/2250\n\nRange-diff vs v3:\n\n 1:  0ab8814664 ! 1:  88210ad52d doc: checkout: rewrite detached HEAD state explanation\n     @@ Documentation/detached-head.adoc (new)\n      +2. A commit ID, when you don't have a current branch.\n      +   This is called \"detached HEAD state\".\n      +\n     -+It can sometimes be useful for `HEAD` to be a commit ID.\n     -+For example, it lets you easily look at an old version of your code\n     -+(with `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`).\n     ++It can sometimes be useful for `HEAD` to be a commit ID, because\n     ++it lets you easily check out an old version of your project. For\n     ++example, a data scientist could use this to run an old version of a\n     ++data pipeline or a programmer could use this to figure out when a bug\n     ++was introduced.\n      +\n      +But it's important to know that if you create new commits while in\n      +detached HEAD state, those commits won't be on a branch. This makes\n     @@ Documentation/detached-head.adoc (new)\n      +\n      +There are 3 main ways you can end up in detached HEAD state:\n      +\n     -+1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID\n     ++1. `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`,\n     ++   where `COMMIT_ID` is a commit ID.\n      +2. `git checkout v1.3`, where v1.3 is a tag name\n      +3. `git checkout origin/main`, where `origin/main` is\n      +   a remote-tracking branch\n      +\n      +Checking out a tag puts you in detached HEAD state because `HEAD` can\n      +only be a branch or a commit, not a tag or any other reference.\n     -+So `git checkout TAG` will set HEAD to the commit for that tag.\n     ++So `git checkout TAG` will set HEAD to the tagged commit.\n      +\n      +The easiest way to avoid accidentally ending up in detached HEAD state\n      +is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to\n     @@ Documentation/detached-head.adoc (new)\n      +Warning: you are leaving 1 commit behind, not connected to\n      +any of your branches:\n      +\n     -+  48c09f6 3\n     ++  48c09f6 fix bug\n      +-------------------------\n      +\n      +For a more in-depth explanation of how `HEAD` works in Git,\n\n\n Documentation/Makefile              |   1 +\n Documentation/detached-head.adoc    |  60 +++++++++++++\n Documentation/git-checkout.adoc     | 129 +---------------------------\n Documentation/gitdetached-head.adoc |  14 +++\n Documentation/meson.build           |   1 +\n advice.c                            |   1 +\n command-list.txt                    |   1 +\n 7 files changed, 79 insertions(+), 128 deletions(-)\n create mode 100644 Documentation/detached-head.adoc\n create mode 100644 Documentation/gitdetached-head.adoc\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f8dea4b395..5892f48b06 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -54,6 +54,7 @@ MAN7_TXT += gitcore-tutorial.adoc\n MAN7_TXT += gitcredentials.adoc\n MAN7_TXT += gitcvs-migration.adoc\n MAN7_TXT += gitdatamodel.adoc\n+MAN7_TXT += gitdetached-head.adoc\n MAN7_TXT += gitdiffcore.adoc\n MAN7_TXT += giteveryday.adoc\n MAN7_TXT += gitfaq.adoc\ndiff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc\nnew file mode 100644\nindex 0000000000..a918a75799\n--- /dev/null\n+++ b/Documentation/detached-head.adoc\n@@ -0,0 +1,60 @@\n+`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:\n+\n+1. A branch, which is your current branch.\n+2. A commit ID, when you don't have a current branch.\n+   This is called \"detached HEAD state\".\n+\n+It can sometimes be useful for `HEAD` to be a commit ID, because\n+it lets you easily check out an old version of your project. For\n+example, a data scientist could use this to run an old version of a\n+data pipeline or a programmer could use this to figure out when a bug\n+was introduced.\n+\n+But it's important to know that if you create new commits while in\n+detached HEAD state, those commits won't be on a branch. This makes\n+those new commits much harder to find later. Also, Git considers commits\n+that aren't on any branch (or a tag or other reference) to be garbage.\n+Git will eventually permanently delete those \"garbage\" commits during\n+garbage collection. Those commits will be deleted after 30 days by\n+default, see linkgit:git-gc[1] for more.\n+\n+There are 3 main ways you can end up in detached HEAD state:\n+\n+1. `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`,\n+   where `COMMIT_ID` is a commit ID.\n+2. `git checkout v1.3`, where v1.3 is a tag name\n+3. `git checkout origin/main`, where `origin/main` is\n+   a remote-tracking branch\n+\n+Checking out a tag puts you in detached HEAD state because `HEAD` can\n+only be a branch or a commit, not a tag or any other reference.\n+So `git checkout TAG` will set HEAD to the tagged commit.\n+\n+The easiest way to avoid accidentally ending up in detached HEAD state\n+is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to\n+switch branches. `git switch` won't let you detach unless you explicitly\n+pass the `--detach` argument.\n+\n+To get back onto a branch, you can:\n+\n+1. Switch to the branch you want to be on, with `git switch BRANCHNAME`.\n+2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`.\n+   You might want to do this if you've created new commits, so that you can\n+   find the commit later and so that it won't be garbage collected.\n+\n+If you switch branches after making commits in detached HEAD state, Git\n+will warn you that you might be about to \"lose\" those commits and print\n+out the commit ID. You can also always find those commits later using\n+linkgit:git-reflog[1].\n+\n+Here's what that warning looks like:\n+\n+-------------------------\n+Warning: you are leaving 1 commit behind, not connected to\n+any of your branches:\n+\n+  48c09f6 fix bug\n+-------------------------\n+\n+For a more in-depth explanation of how `HEAD` works in Git,\n+see linkgit:gitdatamodel[7] (`git help datamodel`).\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 2aefea0228..4e9e94e24d 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -376,135 +376,8 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n [[DETACHED_HEAD]]\n DETACHED HEAD\n -------------\n-`HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each\n-branch refers to a specific commit. Let's look at a repo with three\n-commits, one of them tagged, and with branch `master` checked out:\n \n-------------\n-           HEAD (refers to branch 'master')\n-            |\n-            v\n-a---b---c  branch 'master' (refers to commit 'c')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-When a commit is created in this state, the branch is updated to refer to\n-the new commit. Specifically, `git commit` creates a new commit `d`, whose\n-parent is commit `c`, and then updates branch `master` to refer to new\n-commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers\n-to commit `d`:\n-\n-------------\n-$ edit; git add; git commit\n-\n-               HEAD (refers to branch 'master')\n-                |\n-                v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is sometimes useful to be able to checkout a commit that is not at\n-the tip of any named branch, or even to create a new commit that is not\n-referenced by a named branch. Let's look at what happens when we\n-checkout commit `b` (here we show two ways this may be done):\n-\n-------------\n-$ git checkout v2.0  # or\n-$ git checkout master^^\n-\n-   HEAD (refers to commit 'b')\n-    |\n-    v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-Notice that regardless of which checkout command we use, `HEAD` now refers\n-directly to commit `b`. This is known as being in detached `HEAD` state.\n-It means simply that `HEAD` refers to a specific commit, as opposed to\n-referring to a named branch. Let's see what happens when we create a commit:\n-\n-------------\n-$ edit; git add; git commit\n-\n-     HEAD (refers to commit 'e')\n-      |\n-      v\n-      e\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-There is now a new commit `e`, but it is referenced only by `HEAD`. We can\n-of course add yet another commit in this state:\n-\n-------------\n-$ edit; git add; git commit\n-\n-\t HEAD (refers to commit 'f')\n-\t  |\n-\t  v\n-      e---f\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-In fact, we can perform all the normal Git operations. But, let's look\n-at what happens when we then checkout `master`:\n-\n-------------\n-$ git checkout master\n-\n-               HEAD (refers to branch 'master')\n-      e---f     |\n-     /          v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is important to realize that at this point nothing refers to commit\n-`f`. Eventually commit `f` (and by extension commit `e`) will be deleted\n-by the routine Git garbage collection process, unless we create a reference\n-before that happens. If we have not yet moved away from commit `f`,\n-any of these will create a reference to it:\n-\n-------------\n-$ git checkout -b foo  # or \"git switch -c foo\"  <1>\n-$ git branch foo                                 <2>\n-$ git tag foo                                    <3>\n-------------\n-<1> creates a new branch `foo`, which refers to commit `f`, and then\n-    updates `HEAD` to refer to branch `foo`. In other words, we'll no longer\n-    be in detached `HEAD` state after this command.\n-<2> similarly creates a new branch `foo`, which refers to commit `f`,\n-    but leaves `HEAD` detached.\n-<3> creates a new tag `foo`, which refers to commit `f`,\n-    leaving `HEAD` detached.\n-\n-If we have moved away from commit `f`, then we must first recover its object\n-name (typically by using git reflog), and then we can create a reference to\n-it. For example, to see the last two commits to which `HEAD` referred, we\n-can use either of these commands:\n-\n-------------\n-$ git reflog -2 HEAD # or\n-$ git log -g -2 HEAD\n-------------\n+include::detached-head.adoc[]\n \n [[ARGUMENT_DISAMBIGUATION]]\n ARGUMENT DISAMBIGUATION\ndiff --git a/Documentation/gitdetached-head.adoc b/Documentation/gitdetached-head.adoc\nnew file mode 100644\nindex 0000000000..a477060db2\n--- /dev/null\n+++ b/Documentation/gitdetached-head.adoc\n@@ -0,0 +1,14 @@\n+gitdetached-head(7)\n+===================\n+\n+NAME\n+----\n+gitdetached-head - How detached HEAD state works\n+\n+DESCRIPTION\n+-----------\n+include::detached-head.adoc[]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex cfa9c67609..6b3141647f 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -197,6 +197,7 @@ manpages = {\n   'gitcredentials.adoc' : 7,\n   'gitcvs-migration.adoc' : 7,\n   'gitdatamodel.adoc' : 7,\n+  'gitdetached-head.adoc' : 7,\n   'gitdiffcore.adoc' : 7,\n   'giteveryday.adoc' : 7,\n   'gitfaq.adoc' : 7,\ndiff --git a/advice.c b/advice.c\nindex 401d047391..8d2c1ff1ee 100644\n--- a/advice.c\n+++ b/advice.c\n@@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n \t\"\\n\"\n \t\"  git switch -\\n\"\n \t\"\\n\"\n+\t\"Run `git help detached-head` to learn more.\\n\"\n \t\"Turn off this advice by setting config variable advice.detachedHead to false\\n\\n\");\n \n \tfprintf(stderr, fmt, new_name);\ndiff --git a/command-list.txt b/command-list.txt\nindex 63ae2a67c9..7fb57765fb 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -218,6 +218,7 @@ gitcore-tutorial                        guide\n gitcredentials                          guide\n gitcvs-migration                        guide\n gitdatamodel                            guide\n+gitdetached-head                        guide\n gitdiffcore                             guide\n giteveryday                             guide\n gitfaq                                  guide\n\nbase-commit: 5a7d1e8045ce66c908f62598e26cbb8df7b39a90\n-- \ngitgitgadget\n\n"},{"id":"555268","messageId":"xmqq33u5fouq.fsf@gitster.g","threadId":"66484","inReplyTo":"7e888746-4220-494d-b8ab-00bdd5da5876@app.fastmail.com","subject":"Re: [PATCH v3] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-16T19:05:17Z","receivedAt":"2026-10-16T19:05:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> I'm not planning to test this version on readers right now, no.\n\nThat is fine.  But eventually we will reach the point where we\nhave something we think is good enough to show to test readers,\nno?  And I thought you were asking for help to improve the draft\nto reach that stage by sending the patch.\n\n> Here's what I wrote in the first email in this thread:\n>\n>     Often when rewriting these explanations I go through a process where I\n>     ask users' feedback on the old explanation. Here I didn't do that\n>     basically because that process takes a long time and I'm working on a\n>     bunch of other time consuming docs projects so I did a quick rewrite\n>     based on my previous experience explaining detached HEAD state to folks.\n>\n>     I thought this could be a nice quick docs win on a topic which many\n>     users find quite confusing. If the changes here are too controversial I\n>     can drop it for now.\n\nAfter a long process, you may forget which suggestions you chose not\nto adopt by the time you are ready to show the draft to your test\nreaders, and those who spent their brain cycles reviewing it might\nnot notice that their input has been forgotten, either.  I was\nworried about that kind of waste.\n\nThanks.\n\n"},{"id":"555277","messageId":"xmqqh5ile4h4.fsf@gitster.g","threadId":"66484","inReplyTo":"pull.2250.v4.git.1792177409868.gitgitgadget@gmail.com","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-16T21:10:47Z","receivedAt":"2026-10-16T21:10:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n>     This is a pretty quick rewrite where we didn't get any user feedback. If\n>     we really want to make sure it's clear to users as possible, we should\n>     IMO do a second stage later where we ask users which parts are unclear.\n\nOK.\n\n>      * It's probably possible to explain HEAD better. That seems like a big\n>        project to me since HEAD in Git is a very tricky topic. I think it\n>        would be better to address in a separate patch series to have more\n>        time to think it through. Or if we think it's not possible to merge\n>        this without explaining HEAD better then I guess it shouldn't be\n>        merged.\n\nI do not understand why you need to draw a \"take it or leave it\"\nwith this topic here.  If you feel that the explanation of HEAD is\niffy, you know what we have here will not be the final version, and\nyou think we lack the capacity to reach the best possible\ndescription with the usual review exchange, then I do not see why\nyou have to insist keeping what you initially have written.  You can\nreplace it with anything that is better than your initial version\nand then still record that we will further polish it later in the\nproposed log message and we will be in a better place, no?\n\nJust to leave a record, so that we have better chance remembering\nthe suggested improved text, here are what I think the first two\nparagraphs should be replaced with.\n\n    HEAD records the state from which your current changes started.\n    This can be a branch (the \"current branch\"), or it be a commit,\n    (in which case HEAD is \"detached\").\n\n    In the detached HEAD state, you can safely build, run, and\n    experiment with any historical version of your codebase, without\n    having to worry about clobbering your branches, and you do not\n    have to clutter your repository with temporary branches.\n\nHaving said all that, the changes between v3 and v4 look OK to me,\nso let me update the previous copy I have with this version.\n\n"},{"id":"555287","messageId":"xmqqse25cni7.fsf@gitster.g","threadId":"66484","inReplyTo":"pull.2250.v4.git.1792177409868.gitgitgadget@gmail.com","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-16T22:02:40Z","receivedAt":"2026-10-16T22:02:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n>  advice.c                            |   1 +\n> ...\n> diff --git a/advice.c b/advice.c\n> index 401d047391..8d2c1ff1ee 100644\n> --- a/advice.c\n> +++ b/advice.c\n> @@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n>  \t\"\\n\"\n>  \t\"  git switch -\\n\"\n>  \t\"\\n\"\n> +\t\"Run `git help detached-head` to learn more.\\n\"\n>  \t\"Turn off this advice by setting config variable advice.detachedHead to false\\n\\n\");\n>  \n>  \tfprintf(stderr, fmt, new_name);\n\nThis breaks t2020 without an accompanying change.\n\nYou can squash in the attached patch to unbreak the test.\n\nSince nobody's terminal talks markdown or asciidoc, let's use the\nvanilla single quote instead of backquote while we are at it.\n\n advice.c                   | 2 +-\n t/t2020-checkout-detach.sh | 2 ++\n 2 files changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git c/advice.c w/advice.c\nindex 8d2c1ff1ee..3238e9b866 100644\n--- c/advice.c\n+++ w/advice.c\n@@ -291,7 +291,7 @@ void detach_advice(const char *new_name)\n \t\"\\n\"\n \t\"  git switch -\\n\"\n \t\"\\n\"\n-\t\"Run `git help detached-head` to learn more.\\n\"\n+\t\"Run 'git help detached-head' to learn more.\\n\"\n \t\"Turn off this advice by setting config variable advice.detachedHead to false\\n\\n\");\n \n \tfprintf(stderr, fmt, new_name);\ndiff --git c/t/t2020-checkout-detach.sh w/t/t2020-checkout-detach.sh\nindex 28bbbe6c05..804dc2a67f 100755\n--- c/t/t2020-checkout-detach.sh\n+++ w/t/t2020-checkout-detach.sh\n@@ -228,6 +228,7 @@ test_expect_success 'describe_detached_head prints no SHA-1 ellipsis when not as\n \n \t  git switch -\n \n+\tRun ${SQ}git help detached-head${SQ} to learn more.\n \tTurn off this advice by setting config variable advice.detachedHead to false\n \n \tHEAD is now at \\$commit three\n@@ -310,6 +311,7 @@ test_expect_success 'describe_detached_head does print SHA-1 ellipsis when asked\n \n \t  git switch -\n \n+\tRun ${SQ}git help detached-head${SQ} to learn more.\n \tTurn off this advice by setting config variable advice.detachedHead to false\n \n \tHEAD is now at \\$commit... three\n\n"},{"id":"555416","messageId":"9c15d34e-406d-4702-b606-da102a340e71@app.fastmail.com","threadId":"66484","inReplyTo":"xmqqik3da2bs.fsf@gitster.g","subject":"Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-19T14:05:58Z","receivedAt":"2026-10-19T14:05:58Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"On Wed, Oct 7, 2026, at 12:43 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> diff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc\n>> new file mode 100644\n>> index 0000000000..1e00712124\n>> --- /dev/null\n>> +++ b/Documentation/detached-head.adoc\n>> @@ -0,0 +1,43 @@\n>> +`HEAD` is where Git stores your current branch. `HEAD` can either be:\n>> +\n>> +1. A branch, which is your current branch.\n>> +2. A commit ID, when you don't have a current branch.\n>> +   This is called \"detached HEAD state\".\n>\n> HEAD is branch which can either be a branch or something else?\n>\n>     HEAD records the state from which your current changes started.\n>     This can be a branch (the \"current branch\"), or it may not be\n>     associated with any concrete branch (in which case HEAD is\n>     \"detached\").\n\nYou asked for a more detailed explanation for why I don't think\nthis is clearer, so here's my best attempt. \n\nIt's important to use the same words that users might themselves use\nto describe a concept, for example, \"means\", \"is\", \"points at\", \"is a reference\nto\", etc.\n\nIn March 2024 I asked experienced Git users to explain their impressions of what\nHEAD means, and I got a lot of really great replies. I've included a bunch of\nthem at the end of this email. I think it's a really great example of how there\nare a lot of \"technically wrong but useful\" ideas about how things in Git work.\nWhen I think about how to explain HEAD, it's in the context of that research\nI did around March 2024.\n\nYour suggestion (\"HEAD records the state from which your current\nchanges started.\" uses pretty different language (\"records\") from\nthe language users are using in the quotes below. I think it would be great if\nwe could make a correct statement that builds on the ideas that users already\nhave about HEAD, using the kind of language that they themselves would use to\ndescribe the ideas.\n\nLet me know if this is a helpful way for you to bring some user perspectives\ninto the conversation. Like I said earlier I don't really think it's possible to\ndiscuss how to explain HEAD in a vacuum so maybe these quotes will help!\n\nAlso if you could give me any ideas for how to reply in a \"shorter\" way than\n\"I don't think this is clearer\" let me know, I can't bring you quotes from user\nresearch to justify every single wording choice :)\n\n-  \"HEAD is a mysterious thing I never need to know about unless something has\ng-one wrong, eg. merge conflicts.\"\n\n-\"the HEAD Commit in my Clone of our Repo is the Commit at the top of: git log\"\n\n- \"Other than seeing \"detached head\" sometimes and panicking, I don't really know\nwhat Head is. And I used git quite a bit over the years 😅\"\n\n- \"HEAD points at the latest commit of the branch you're viewing. Except when it\ndoesn’t. There's attached and detached head situations and that's where it gets\nsomewhat confusing.\"\n\n- \"It is a… thing… which “points at”… the newest (?) commit that “”I”” am ¿on?\"\n\n- \"it's a pointer to the latest commit on the currently checked out branch\"\n\n- \"HEAD means (a pointer to) the (commit hash of the) checked-out branch\"\n\n- \"HEAD is the reference to the current commit that's checked out.\"\n\n- \"The commit which will be the parent of the next commit you create, at least\nusing \"git commit\" command.\"\n\n- \"unless I am taking special pains to deliberately edit history, HEAD will\n(1) become the first parent of whichever commit I write next AND (2) names the\nbranch where that commit will be appended\".\n\n- \"it's where you \"currently are\" on a branch (or maybe in the whole repo? not\nsure on head vs HEAD)\"\n\n- \"the most recent commit on the branch you're working on\"\n\n- \"Insertion point for new commits.\"\n\n- \"HEAD is a \"commit-like\"? that refers to the commit? that was used? to populate\nthe working directory?\"\n\n- \"a file in .git that points to either a commit or a ref; git uses this as the\n\"current\" commit for things like git status\"\n\n- \"HEAD is a symbolic reference to another reference ... I don't have a mental\nmodel for what happens if HEAD points at a tag ref\"\n\n- \"my impression is that it's the commit I'm currently looking at. It's attached\nif that commit is the tip of a branch (means I can make new commits), and it's\ndetached when that is not the case.\"\n\n- \"it's a file that contains the currently checked-out commit id or branch name?\"\n\n- \"Sometimes I think I kinda understand. Then I remember the existence of the\nphrase “detached HEAD”.\"\n\n- \"HEAD is what is going to be the parent of your next commit\"\n\n- \"HEAD points at the latest commit in the branch you're currently in. So if\nyou're in main, it's the latest commit there. If you're in dev, it's the latest\ncommit in that branch.  ... But if you're in a branch and not on the latest\ncommit, HEAD still points at the latest commit.\"\n\n- \"HEAD is shorthand for \"most recent commit on current branch\".\"\n\n- \"it means \"the commit I have checked out at this very moment\".\"\n\n- \"I am quite unconfident as I only ever see it mentioned when running 'git\nreset'. From that context, something like \"the most recent 'saved' state of the\nrepo before you made any 'unsaved' modifications\"\"\n\n- \"A pointer to the *latest* commit (not necessarily \"current\" commit) in\nwhatever I'm working on. ... the latest commit\" is whatever is conceptually \"at\nthe end\" of the branch's timeline.\"\n\n- \"HEAD is used as a pointer to the current commit, while it is (usually) pointer\nto the current branch, which head (lowercase) points to the current commit - one\nlayer of indirection.\"\n\n- \"I think of it as pointing to the next place where a commit would appear if I\nmade one\"\n\n- \"HEAD is a reference to a commit, either directly or indirectly. A direct\ncommit is just in detached state, where HEAD is looking at the commit itself.\nAn indirect reference would be the case you’ve shown above, where HEAD is a\nreference to a reference.\"\n\n- \"Its like... the thing at the end of the branch, right? Like... the current\ncommit.\"\n\n- \"I think in practice it is the last ref checked out. Sometimes it is the SHA of\nthe revision (detached head), sometimes it is a ref (branch or tag).\"\n\n- \"HEAD means the head of a specific branch, which seems to be the default branch\nin github?\"\n\n- \"the git command that involves HEAD which I use most often is `git push origin\nHEAD` ... I'd definitely struggle to articulate why this works the way that\nit does\"\n\n"},{"id":"555468","messageId":"xmqqcxt52xkn.fsf@gitster.g","threadId":"66484","inReplyTo":"9c15d34e-406d-4702-b606-da102a340e71@app.fastmail.com","subject":"Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-19T21:24:24Z","receivedAt":"2026-10-19T21:24:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> Let me know if this is a helpful way for you to bring some user perspectives\n> into the conversation. Like I said earlier I don't really think it's possible to\n> discuss how to explain HEAD in a vacuum so maybe these quotes will help!\n\nIt surely is more helpful than \"I think it is not better\" that is\nnot backed by anything.\n\n> Also if you could give me any ideas for how to reply in a \"shorter\" way than\n> \"I don't think this is clearer\" let me know, I can't bring you quotes from user\n> research to justify every single wording choice :)\n\nIOW, \"Trust me\" ;-)\n\nIt is often good enough among those who have worked together for\nsome time, and you certainly do qualify.\n\n> -  \"HEAD is a mysterious thing I never need to know about unless something has\n> g-one wrong, eg. merge conflicts.\"\n\nSomebody may have said so, but how does bringing it (together with\nmany other examples) up in _this_ discussion help us find a better\nway to explain it to users?\n\nSomebody is clueless about HEAD and does not feel the need to\nunderstand it until they really need to.  This fact alone, that they\ncan get going with such a sketchy understanding and make use of Git\nsufficiently well may be a great thing by itself.  It may support an\nargument that we do not really have to explain what HEAD is to our\nreaders.  Is that the argument you are making?\n\nI won't comment on each and every one of them, but is your point\nthat many potential readers do not understand HEAD and doing fine?\n\nOf course there are a handful of examples that they do get it, like\nthis one.\n\n> - \"HEAD is a reference to a commit, either directly or indirectly. A direct\n> commit is just in detached state, where HEAD is looking at the commit itself.\n> An indirect reference would be the case you’ve shown above, where HEAD is a\n> reference to a reference.\"\n\nBut what did you want to illustrate again?  I am little bit fuzzy on\nwhat you wanted to achieve by dumping these at me.\n\nThanks.\n\n"},{"id":"555530","messageId":"1AA9F133-4B0C-4AAC-B296-5C2543C642F2@jvns.ca","threadId":"66484","inReplyTo":"xmqqcxt52xkn.fsf@gitster.g","subject":"Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-20T12:52:25Z","receivedAt":"2026-10-20T12:52:25Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n> On Oct 19, 2026, at 5:24 PM, Junio C Hamano <gitster@pobox.com> wrote:\n> \n> \"Julia Evans\" <julia@jvns.ca> writes:\n> \n>> Let me know if this is a helpful way for you to bring some user perspectives\n>> into the conversation. Like I said earlier I don't really think it's possible to\n>> discuss how to explain HEAD in a vacuum so maybe these quotes will help!\n> \n> It surely is more helpful than \"I think it is not better\" that is\n> not backed by anything.\n> \n>> Also if you could give me any ideas for how to reply in a \"shorter\" way than\n>> \"I don't think this is clearer\" let me know, I can't bring you quotes from user\n>> research to justify every single wording choice :)\n> \n> IOW, \"Trust me\" ;-)\n> \n> It is often good enough among those who have worked together for\n> some time, and you certainly do qualify.\n\nThat’s good to hear!\n\n>> -  \"HEAD is a mysterious thing I never need to know about unless something has\n>> g-one wrong, eg. merge conflicts.\"\n> \n> Somebody may have said so, but how does bringing it (together with\n> many other examples) up in _this_ discussion help us find a better\n> way to explain it to users?\n\n> Somebody is clueless about HEAD and does not feel the need to\n> understand it until they really need to.  This fact alone, that they\n> can get going with such a sketchy understanding and make use of Git\n> sufficiently well may be a great thing by itself.  It may support an\n> argument that we do not really have to explain what HEAD is to our\n> readers.  Is that the argument you are making?\n> \n> I won't comment on each and every one of them, but is your point\n> that many potential readers do not understand HEAD and doing fine?\n\nI do think that’s true yes.\n\n> Of course there are a handful of examples that they do get it, like\n> this one.\n> \n>> - \"HEAD is a reference to a commit, either directly or indirectly. A direct\n>> commit is just in detached state, where HEAD is looking at the commit itself.\n>> An indirect reference would be the case you’ve shown above, where HEAD is a\n>> reference to a reference.\"\n> \n> But what did you want to illustrate again?  I am little bit fuzzy on\n> what you wanted to achieve by dumping these at me.\n\nMostly to give an idea of the kind of language users are using when\ntalking about Git, to explain why saying “records” isn’t appropriate\nand why more generally it might not be possible for me to accept\nyour suggested wordings for how to explain things verbatim.\nFor example elsewhere in this thread you suggested another wording\nand seemed to find it hard to understand why I wouldn't replace\nwhat Marie and I had written with your suggested “better” wording.\n\nAlso I have the impression that our assumptions about what Git users\nknow and what users need are quite different, and I thought it might\nhelp illustrate why I might have a different point of view.\n\nI agree these kinds of comments can be a little unsettling to read when\nsome of them are “wrong”. I believe that these comments are from\nfolks who are quite a bit more knowledgeable than the average Git user.\n\nIt’s my job to sort through them and figure out how to write the docs\nwith them in mind and I’m definitely not asking you to do that :)\nI do need some trust though.\n"},{"id":"555532","messageId":"426b0cf4-d37f-420f-a7df-48bd6281818d@app.fastmail.com","threadId":"66484","inReplyTo":"1AA9F133-4B0C-4AAC-B296-5C2543C642F2@jvns.ca","subject":"Re: [PATCH] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-20T13:06:58Z","receivedAt":"2026-10-20T13:06:58Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> I agree these kinds of comments can be a little unsettling to read when\n> some of them are “wrong”. I believe that these comments are from\n> folks who are quite a bit more knowledgeable than the average Git user.\n\nI forgot the mandatory XKCD here :) https://xkcd.com/2501/\n\n"},{"id":"557812","messageId":"CALnO6CBGcG42NxtpuPaJVrzAMC=J8iVstsHCSi6vDQhDmFJ-Kw@mail.gmail.com","threadId":"66484","inReplyTo":"xmqqh5ile4h4.fsf@gitster.g","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-11-07T20:06:36Z","receivedAt":"2026-11-07T20:06:36Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"Hi all,\n\nI've read through this thread a few times, and I'm still interested in\nseeing the detached HEAD manual land. It seems like the following need\nto happen?\n\n1. We are waiting on a reroll from Julia with the SQUASH??? commit or\nsomething like it applied\n(https://lore.kernel.org/git/xmqqse25cni7.fsf@gitster.g/)\n2. The discussion about how to describe HEAD needs resolved.\n\nOn Fri, Oct 16, 2026 at 5:11 PM Junio C Hamano <gitster@pobox.com> wrote:\n>\n> Just to leave a record, so that we have better chance remembering\n> the suggested improved text, here are what I think the first two\n> paragraphs should be replaced with.\n>\n>     HEAD records the state from which your current changes started.\n>     This can be a branch (the \"current branch\"), or it be a commit,\n>     (in which case HEAD is \"detached\").\n>\n>     In the detached HEAD state, you can safely build, run, and\n>     experiment with any historical version of your codebase, without\n>     having to worry about clobbering your branches, and you do not\n>     have to clutter your repository with temporary branches.\n\nHere's what Junio suggested^, and here's what v4 has\n\n+`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:\n+\n+1. A branch, which is your current branch.\n+2. A commit ID, when you don't have a current branch.\n+   This is called \"detached HEAD state\".\n+\n+It can sometimes be useful for `HEAD` to be a commit ID, because\n+it lets you easily check out an old version of your project. For\n+example, a data scientist could use this to run an old version of a\n+data pipeline or a programmer could use this to figure out when a bug\n+was introduced.\n\nI do not personally think it's worth focusing on \"the state from which\nyour current changes started\" (even leaving aside the \"what if I have\nno changes?\" moment), in part because I don't think that's how most\nusers conceive of HEAD. Other than that detail, I think the first\nparagraphs of each option coincide.\n\nThere are some quotes which use the \"it's the parent of the next\ncommit\" mental model, though, so we could include a comment on that?\nIt might be distracting, and could make its way into some kind of\nadmonition/aside if need be?\n\nThe second paragraphs differ a bit, with Junio's containing some bits\nabout clobbering extant branches and not needing temporary branches. I\nthink we could work something in there, like\n\n    It can sometimes be useful for `HEAD` to be a commit ID,\n    because it lets you easily check out an old version of your\n    project. For example, a data scientist could use this to run\n    an old version of a data pipeline or a programmer could use\n    this to figure out when a bug was introduced. By detaching\n    `HEAD`, you don't need to worry about clobbering an existing\n    branch or creating a temporary branch.\n\n? I suppose we could also be more explicit (\"build, run, and\nexperiment\"), if we wanted, but this is a good example to start from.\n\n> Having said all that, the changes between v3 and v4 look OK to me,\n> so let me update the previous copy I have with this version.\n\nOtherwise, we're approaching a finish here?\n\n-- \nD. Ben Knoble\n\n"},{"id":"557828","messageId":"xmqq7bio6jb4.fsf@gitster.g","threadId":"66484","inReplyTo":"CALnO6CBGcG42NxtpuPaJVrzAMC=J8iVstsHCSi6vDQhDmFJ-Kw@mail.gmail.com","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-08T04:25:35Z","receivedAt":"2026-11-08T04:25:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble\" <ben.knoble@gmail.com> writes:\n\n> +`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:\n> +\n> +1. A branch, which is your current branch.\n> +2. A commit ID, when you don't have a current branch.\n> +   This is called \"detached HEAD state\".\n> +\n> +It can sometimes be useful for `HEAD` to be a commit ID, because\n> +it lets you easily check out an old version of your project. For\n> +example, a data scientist could use this to run an old version of a\n> +data pipeline or a programmer could use this to figure out when a bug\n> +was introduced.\n> ...\n> There are some quotes which use the \"it's the parent of the next\n> commit\" mental model, though, so we could include a comment on that?\n\n\"From which your current changes started\" is exactly that.  HEAD is\nwhere you started from (and can come back to, if you get lost after\nbotching your working tree state).  Your next commit is built on top\nof it, and then that new commit becomes your current commit.\n\nThis is why it is useful for users to realize that HEAD is simply\nwhere you started from, regardless of where you are going.\n\n> The second paragraphs differ a bit, with Junio's containing some bits\n> about clobbering extant branches and not needing temporary branches. I\n> think we could work something in there, like\n> ...\n>     this to figure out when a bug was introduced. By detaching\n>     `HEAD`, you don't need to worry about clobbering an existing\n>     branch or creating a temporary branch.\n>\n> ? I suppose we could also be more explicit (\"build, run, and\n> experiment\"), if we wanted, but this is a good example to start from.\n\nI assume you mean the last two lines?  I do appreciate that addition.\n\nHowever, we should avoid saying \"useful for HEAD to be a commit ID\".\nBeing a commit ID is not the notable characteristic of a detached\nHEAD; the fact that it directly refers to a commit is what gives us\nthese useful features.  Recording a hexadecimal commit object name\n(instead of a refname of a branch) is a mere implementation detail\nof that direct reference.\n\nSince Julia's introductory paragraph already established the term\n\"detached HEAD\" very well, there is no need to resort to a roundabout\nphrasing like \"useful for HEAD to be a commit ID\".  I suggest\nrewriting the beginning of that paragraph to start with:\n\n    It can be useful for the HEAD to be directly refering to a\n    commit (instead of indirectly referring to a commit by naming\n    the current branch).\n\nThis introduces the remainder of her paragraph much better, and\nmakes your addition about not needing to worry about clobbering\nexisting branches or consuming temporary refs easier to understand.\n\n> Otherwise, we're approaching a finish here?\n\nI hope so.  The document overall is moving in the right direction,\nand I just want to see these minor technical descriptions improved.\n\n"},{"id":"558000","messageId":"f7d4600b-909f-4dd7-94da-d525649a9546@app.fastmail.com","threadId":"66484","inReplyTo":"xmqq7bio6jb4.fsf@gitster.g","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-09T21:48:36Z","receivedAt":"2026-11-09T21:48:36Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Sat, Nov 7, 2026, at 11:25 PM, Junio C Hamano wrote:\n> \"D. Ben Knoble\" <ben.knoble@gmail.com> writes:\n>\n>> +`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:\n>> +\n>> +1. A branch, which is your current branch.\n>> +2. A commit ID, when you don't have a current branch.\n>> +   This is called \"detached HEAD state\".\n>> +\n>> +It can sometimes be useful for `HEAD` to be a commit ID, because\n>> +it lets you easily check out an old version of your project. For\n>> +example, a data scientist could use this to run an old version of a\n>> +data pipeline or a programmer could use this to figure out when a bug\n>> +was introduced.\n>> ...\n>> There are some quotes which use the \"it's the parent of the next\n>> commit\" mental model, though, so we could include a comment on that?\n>\n> \"From which your current changes started\" is exactly that.  HEAD is\n> where you started from (and can come back to, if you get lost after\n> botching your working tree state).  Your next commit is built on top\n> of it, and then that new commit becomes your current commit.\n>\n> This is why it is useful for users to realize that HEAD is simply\n> where you started from, regardless of where you are going.\n\nI think it's reasonable to try to explain that in both cases\nthere's something in common.\n\nHere's an idea for how to do that:\n  \n  In Git, you can always use `HEAD` to refer to the current commit.\n  But `HEAD` isn't just your current commit: it's also where Git\n  stores the name of your current branch. `HEAD` can either be:\n  \n  1. A branch, which is your current branch.\n     The current commit is the latest commit on that branch.\n  2. A commit ID, when you don't have a current branch.\n     This is called \"detached HEAD state\".\n  \n  It can sometimes be useful for `HEAD` to be a commit ID, because...\n\n>> The second paragraphs differ a bit, with Junio's containing some bits\n>> about clobbering extant branches and not needing temporary branches. I\n>> think we could work something in there, like\n>> ...\n>>     this to figure out when a bug was introduced. By detaching\n>>     `HEAD`, you don't need to worry about clobbering an existing\n>>     branch or creating a temporary branch.\n>>\n>> ? I suppose we could also be more explicit (\"build, run, and\n>> experiment\"), if we wanted, but this is a good example to start from.\n>\n> I assume you mean the last two lines?  I do appreciate that addition.\n>\n> However, we should avoid saying \"useful for HEAD to be a commit ID\".\n> Being a commit ID is not the notable characteristic of a detached\n> HEAD; the fact that it directly refers to a commit is what gives us\n> these useful features.  Recording a hexadecimal commit object name\n> (instead of a refname of a branch) is a mere implementation detail\n> of that direct reference.\n\nSaying \"it's a commit ID\" is a simple way to say that it directly refers\nto a commit in a small number of words. I'm not sure what your goal is\nhere, do you think that statement is somehow misleading to users?\n\n"},{"id":"558022","messageId":"xmqqfqx9uqsn.fsf@gitster.g","threadId":"66484","inReplyTo":"f7d4600b-909f-4dd7-94da-d525649a9546@app.fastmail.com","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-10T06:46:48Z","receivedAt":"2026-11-10T06:46:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> On Sat, Nov 7, 2026, at 11:25 PM, Junio C Hamano wrote:\n>> \"D. Ben Knoble\" <ben.knoble@gmail.com> writes:\n>>\n>>> +`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:\n>>> +\n>>> +1. A branch, which is your current branch.\n>>> +2. A commit ID, when you don't have a current branch.\n>>> +   This is called \"detached HEAD state\".\n> ...\n> Saying \"it's a commit ID\" is a simple way to say that it directly refers\n> to a commit in a small number of words. I'm not sure what your goal is\n> here, do you think that statement is somehow misleading to users?\n\nYes, I find it highly misleading, and otherwise I wouldn't be\ndiscussing this patch.\n\nI think the part I find it problematic the most in\n\n    HEAD is a branch vs HEAD is a commit ID\n\nis that HEAD *IS NOT* either of these things.  HEAD may record one\nof these kinds of things but it never is a branch or an commit\nobject name.\n\nAnd HEAD records one of these kinds of things to either directly or\nindirectly refer to a commit that is currently checked out.\n\nThat is why I want to see the first description of the above to\nserve as a solid base to convey these points, with later\ndescriptions we build on top:\n\n * `HEAD` can record either (1) a branch, or (2) a commit object\n    name.\n\n * The purpose of HEAD doing so is to refer to a commit that is\n   currently checked out, either directly or indirectly.\n\n * The latter (i.e., the direct reference) may be unfamiliar to\n   users.  It is called \"detached HEAD\" state.\n\n * The commit referred to by the HEAD will become the parent of the\n   commit you create.  When your HEAD records a branch, its tip is\n   advanced.  Otherwise no branch is affected.  Either case, HEAD\n   now refers to the commit you newly created.\n\nAnd I find that saying \"HEAD is a branch\" or \"HEAD is a commit\" is\nmisleading and does not help that goal.\n\nHTH.\n\n"},{"id":"558077","messageId":"ce9fcde0-2181-4773-9133-f39ea1ebf7bf@app.fastmail.com","threadId":"66484","inReplyTo":"xmqqfqx9uqsn.fsf@gitster.g","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-10T13:13:35Z","receivedAt":"2026-11-10T13:13:35Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"I'm going to reply to this email a bit out of order because I want to say\nthis is a great list first:\n\n> That is why I want to see the first description of the above to\n> serve as a solid base to convey these points, with later\n> descriptions we build on top:\n\n>  * `HEAD` can record either (1) a branch, or (2) a commit object\n>     name.\n>\n>  * The purpose of HEAD doing so is to refer to a commit that is\n>    currently checked out, either directly or indirectly.\n>\n>  * The latter (i.e., the direct reference) may be unfamiliar to\n>    users.  It is called \"detached HEAD\" state.\n>\n>  * The commit referred to by the HEAD will become the parent of the\n>    commit you create.  When your HEAD records a branch, its tip is\n>    advanced.  Otherwise no branch is affected.  Either case, HEAD\n>    now refers to the commit you newly created.\n\nI'm not sure if we need to communicate the last point here, but\ndefinitely the goal is to communicate the first 3 points.\n\n> ... And HEAD records one of these kinds of things to either directly or\n> indirectly refer to a commit that is currently checked out.\n\nnow back to the beginning:\n\n> And I find that saying \"HEAD is a branch\" or \"HEAD is a commit\" is\n> misleading and does not help that goal.\n\n>> Saying \"it's a commit ID\" is a simple way to say that it directly refers\n>> to a commit in a small number of words. I'm not sure what your goal is\n>> here, do you think that statement is somehow misleading to users?\n>\n> Yes, I find it highly misleading, and otherwise I wouldn't be\n> discussing this patch.\n>\n> I think the part I find it problematic the most in\n>\n>     HEAD is a branch vs HEAD is a commit ID\n> is that HEAD *IS NOT* either of these things. \n\nThe all caps \"IS NOT\" doesn't help me understand why it's misleading\nbut it does tell me you feel strongly about this so I assume it's important :)\nIt might help to give an example of something a user might believe about\nHEAD that is not true as a result of reading this.\nI'll try a different suggestion and see if that helps though.\n\nOften I approach this issue by talking about Git's implementation directly,\nlike \".git/HEAD is a file that can contain either a branch name or commit ID\".\nUsually I think it's not good to talk about the implementation that way,\nbut I think HEAD might be an exception because in practice I've found that\nusers find the explanation of the implementation helpful.\n\nHere's a version which handles the issue by talking about `.git/HEAD`.\n\n  In Git, you can always use `HEAD` to refer to the commit you have\n  checked out. But HEAD is also where Git stores the name of your current\n  branch. Internally, `.git/HEAD` is a file that contains either:\n  \n  1. A branch name, which is your current branch.\n     The commit you have checked out is the latest commit on that branch.\n  2. A commit ID, when you don't have a current branch.\n     This is called \"detached HEAD state\".\n  \n  It can sometimes be useful for `HEAD` to refer to a commit directly\n  because it lets you easily check out an old version of your project.\n  ...\n\nBut talking about the implementation in this way isn't a good idea (even though\nit might have been okay 10 years ago) because immediately as soon as we make the\nreftable backend the default, users will try to look at `.git/HEAD` and it won't\nbe there, which will cause confusion.\n\nWe could talk about `git symbolic-ref HEAD` but that introduces a whole\nother can of worms of \"what is a symbolic ref\" and I don't know is helpful.\n\n> HEAD may record one\n> of these kinds of things but it never is a branch or an commit\n> object name.\n\nWhat does the verb \"record\" mean to you? I've seen you and other folks in the\nGit project use a lot but I've never totally understood what it's intended to\nmean. I haven't seen it used in this way outside of the Git project.\n\nLike I said before in this thread, it's important to use verbs that\nusers themselves might use to describe a concept (references, points to, etc).\nDoes \"records\" mean the same thing as \"references\" or \"points to\" from your\nperspective? My guess is no, because \"references\" and \"points to\" can also refer\nto indirect references, and I think \"records\" may mean something more specific.\nMaybe it means something like \"there's an abstract key-value store in Git where\nthe key is 'HEAD' and the value is a branch name or commit ID\"?\n\n\"Records\" is not a good word to use to communicate with users about\nthis topic because the meaning of the verb won't be understood.\n\n"},{"id":"558248","messageId":"pull.2250.v5.git.1794432869488.gitgitgadget@gmail.com","threadId":"66484","inReplyTo":"pull.2250.git.1791384721919.gitgitgadget@gmail.com","subject":"[PATCH v5] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-11-11T21:34:29Z","receivedAt":"2026-11-11T21:34:29Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nThe current explanation has the following issues:\n\n- Says detached HEAD state is useful but doesn't explain why\n- Takes many paragraphs before explaining what detached HEAD state is\n- It's common for users to accidentally end up in detached HEAD state,\n  but it doesn't explain why that might happen\n- One of the UI improvements in `git switch` is to make it harder\n  to detach accidentally, but that isn't advertised.\n  See 7968bef06b (switch: only allow explicit detached HEAD, 2019-03-29)\n- Too many confusing diagrams\n\nWrite a new explanation addressing these issues, and put it in a\nstandalone guide so that we can easily reference it from advice\n(\"see `git help detached-head`\").\nThe result is a shorter guide that covers more material.\n\nThe framing that \"Git considers commits that aren't on a branch/other\nreference to be garbage\" is taken from Steve Klabnik's tutorial\nhttps://steveklabnik.github.io/jujutsu-tutorial/branching-merging-and-conflicts/anonymous-branches.html.\nIt's funny and it's consistent with the way Git uses the term\n\"garbage collection\".\n\nCo-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n    doc: checkout: rewrite detached HEAD state explanation\n    \n    This is a pretty quick rewrite where we didn't get any user feedback. If\n    we really want to make sure it's clear to users as possible, we should\n    IMO do a second stage later where we ask users which parts are unclear.\n    \n    Changes in v2:\n    \n     * Make the meson.build and Makefile changes (thanks to Kristoffer)\n     * Rename to gitdata-model (thanks to Kristoffer)\n     * Mention commits will be deleted after 90 days to make it seem less\n       scary (thanks to Kristoffer)\n     * Add an \"easily\" qualifier to \"it lets you look at an old version of\n       your code\", to avoid implying that this is the only way (thanks to\n       Junio)\n     * Mention that Git will warn you when switching branches if you're\n       leaving commits behind (thanks to Junio)\n     * Remove \"unintentionally\" (thanks to Junio)\n     * Mention git help datamodel (thanks to Junio)\n    \n    Changes in v3:\n    \n    I went through the style comments from v1.\n    \n    content changes:\n    \n     * Change \"90 days\" to \"30 days\" (thanks to Junio)\n     * Say that HEAD is where Git stores your \"current branch or commit\" to\n       make the first sentence read better (thanks to Junio)\n     * Mention git switch --detach a little earlier (thanks to Kristoffer)\n     * Replace \"the only problem\" with \"it's important to know that\" (thanks\n       to Junio)\n    \n    formatting changes etc:\n    \n     * Replace help detachedhead with help detached-head (thanks to Junio)\n     * Fix spacing in command-list.txt (thanks to Junio)\n     * Get Marie's signoff (thanks to Junio)\n    \n    non-changes: Left these phrases alone because I don't think the proposed\n    changes would make it more clear.\n    \n     * \"3 main ways you can end up in detached HEAD state\"\n     * \"to look at an old version of your code\"\n     * \"avoid accidentally ending up\"\n    \n    Changes in v4:\n    \n     * Fix commit message in example: \"fix bug\", not \"3\" (thanks to Junio)\n     * \"commit for that tag\" -> \"tagged commit\" (thanks to Junio)\n     * Move \"git checkout COMMIT_ID or git switch --detach COMMIT_ID\" down\n       to the \"3 main ways\" list to reduce duplication (thanks to Junio)\n     * Add some examples and be clearer about how detached HEAD state lets\n       you check out an old version of the project. (thanks to Junio)\n    \n    non-changes:\n    \n     * It's probably possible to explain HEAD better. That seems like a big\n       project to me since HEAD in Git is a very tricky topic. I think it\n       would be better to address in a separate patch series to have more\n       time to think it through. Or if we think it's not possible to merge\n       this without explaining HEAD better then I guess it shouldn't be\n       merged.\n    \n    Changes in v5:\n    \n     * Explain HEAD's relationship to the current commit to make it feel\n       more uniform (thanks to Junio)\n     * Add a note about the benefits of detaching HEAD (thanks to Junio &\n       Ben)\n     * Change \"HEAD can either be a commit ID or a branch name\"\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2250%2Fjvns%2Fdetached-head-v5\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2250/jvns/detached-head-v5\nPull-Request: https://github.com/gitgitgadget/git/pull/2250\n\nRange-diff vs v4:\n\n 1:  88210ad52d ! 1:  cd4e443809 doc: checkout: rewrite detached HEAD state explanation\n     @@ Documentation/Makefile: MAN7_TXT += gitcore-tutorial.adoc\n      \n       ## Documentation/detached-head.adoc (new) ##\n      @@\n     -+`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:\n     ++In Git, you can always use `HEAD` to refer to the commit you have\n     ++checked out. But `HEAD` is also where Git stores the name of your\n     ++current branch. Internally in Git, `HEAD` can either be stored as:\n      +\n     -+1. A branch, which is your current branch.\n     ++1. A branch name, which is your current branch.\n     ++   The commit you have checked out is the latest commit on that branch.\n      +2. A commit ID, when you don't have a current branch.\n      +   This is called \"detached HEAD state\".\n      +\n     @@ Documentation/detached-head.adoc (new)\n      +it lets you easily check out an old version of your project. For\n      +example, a data scientist could use this to run an old version of a\n      +data pipeline or a programmer could use this to figure out when a bug\n     -+was introduced.\n     ++was introduced. By detaching `HEAD`, you don't need to create a\n     ++temporary branch.\n      +\n      +But it's important to know that if you create new commits while in\n      +detached HEAD state, those commits won't be on a branch. This makes\n\n\n Documentation/Makefile              |   1 +\n Documentation/detached-head.adoc    |  64 ++++++++++++++\n Documentation/git-checkout.adoc     | 129 +---------------------------\n Documentation/gitdetached-head.adoc |  14 +++\n Documentation/meson.build           |   1 +\n advice.c                            |   1 +\n command-list.txt                    |   1 +\n 7 files changed, 83 insertions(+), 128 deletions(-)\n create mode 100644 Documentation/detached-head.adoc\n create mode 100644 Documentation/gitdetached-head.adoc\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f8dea4b395..5892f48b06 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -54,6 +54,7 @@ MAN7_TXT += gitcore-tutorial.adoc\n MAN7_TXT += gitcredentials.adoc\n MAN7_TXT += gitcvs-migration.adoc\n MAN7_TXT += gitdatamodel.adoc\n+MAN7_TXT += gitdetached-head.adoc\n MAN7_TXT += gitdiffcore.adoc\n MAN7_TXT += giteveryday.adoc\n MAN7_TXT += gitfaq.adoc\ndiff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc\nnew file mode 100644\nindex 0000000000..48dbc1da1c\n--- /dev/null\n+++ b/Documentation/detached-head.adoc\n@@ -0,0 +1,64 @@\n+In Git, you can always use `HEAD` to refer to the commit you have\n+checked out. But `HEAD` is also where Git stores the name of your\n+current branch. Internally in Git, `HEAD` can either be stored as:\n+\n+1. A branch name, which is your current branch.\n+   The commit you have checked out is the latest commit on that branch.\n+2. A commit ID, when you don't have a current branch.\n+   This is called \"detached HEAD state\".\n+\n+It can sometimes be useful for `HEAD` to be a commit ID, because\n+it lets you easily check out an old version of your project. For\n+example, a data scientist could use this to run an old version of a\n+data pipeline or a programmer could use this to figure out when a bug\n+was introduced. By detaching `HEAD`, you don't need to create a\n+temporary branch.\n+\n+But it's important to know that if you create new commits while in\n+detached HEAD state, those commits won't be on a branch. This makes\n+those new commits much harder to find later. Also, Git considers commits\n+that aren't on any branch (or a tag or other reference) to be garbage.\n+Git will eventually permanently delete those \"garbage\" commits during\n+garbage collection. Those commits will be deleted after 30 days by\n+default, see linkgit:git-gc[1] for more.\n+\n+There are 3 main ways you can end up in detached HEAD state:\n+\n+1. `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`,\n+   where `COMMIT_ID` is a commit ID.\n+2. `git checkout v1.3`, where v1.3 is a tag name\n+3. `git checkout origin/main`, where `origin/main` is\n+   a remote-tracking branch\n+\n+Checking out a tag puts you in detached HEAD state because `HEAD` can\n+only be a branch or a commit, not a tag or any other reference.\n+So `git checkout TAG` will set HEAD to the tagged commit.\n+\n+The easiest way to avoid accidentally ending up in detached HEAD state\n+is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to\n+switch branches. `git switch` won't let you detach unless you explicitly\n+pass the `--detach` argument.\n+\n+To get back onto a branch, you can:\n+\n+1. Switch to the branch you want to be on, with `git switch BRANCHNAME`.\n+2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`.\n+   You might want to do this if you've created new commits, so that you can\n+   find the commit later and so that it won't be garbage collected.\n+\n+If you switch branches after making commits in detached HEAD state, Git\n+will warn you that you might be about to \"lose\" those commits and print\n+out the commit ID. You can also always find those commits later using\n+linkgit:git-reflog[1].\n+\n+Here's what that warning looks like:\n+\n+-------------------------\n+Warning: you are leaving 1 commit behind, not connected to\n+any of your branches:\n+\n+  48c09f6 fix bug\n+-------------------------\n+\n+For a more in-depth explanation of how `HEAD` works in Git,\n+see linkgit:gitdatamodel[7] (`git help datamodel`).\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 2aefea0228..4e9e94e24d 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -376,135 +376,8 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n [[DETACHED_HEAD]]\n DETACHED HEAD\n -------------\n-`HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each\n-branch refers to a specific commit. Let's look at a repo with three\n-commits, one of them tagged, and with branch `master` checked out:\n \n-------------\n-           HEAD (refers to branch 'master')\n-            |\n-            v\n-a---b---c  branch 'master' (refers to commit 'c')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-When a commit is created in this state, the branch is updated to refer to\n-the new commit. Specifically, `git commit` creates a new commit `d`, whose\n-parent is commit `c`, and then updates branch `master` to refer to new\n-commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers\n-to commit `d`:\n-\n-------------\n-$ edit; git add; git commit\n-\n-               HEAD (refers to branch 'master')\n-                |\n-                v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is sometimes useful to be able to checkout a commit that is not at\n-the tip of any named branch, or even to create a new commit that is not\n-referenced by a named branch. Let's look at what happens when we\n-checkout commit `b` (here we show two ways this may be done):\n-\n-------------\n-$ git checkout v2.0  # or\n-$ git checkout master^^\n-\n-   HEAD (refers to commit 'b')\n-    |\n-    v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-Notice that regardless of which checkout command we use, `HEAD` now refers\n-directly to commit `b`. This is known as being in detached `HEAD` state.\n-It means simply that `HEAD` refers to a specific commit, as opposed to\n-referring to a named branch. Let's see what happens when we create a commit:\n-\n-------------\n-$ edit; git add; git commit\n-\n-     HEAD (refers to commit 'e')\n-      |\n-      v\n-      e\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-There is now a new commit `e`, but it is referenced only by `HEAD`. We can\n-of course add yet another commit in this state:\n-\n-------------\n-$ edit; git add; git commit\n-\n-\t HEAD (refers to commit 'f')\n-\t  |\n-\t  v\n-      e---f\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-In fact, we can perform all the normal Git operations. But, let's look\n-at what happens when we then checkout `master`:\n-\n-------------\n-$ git checkout master\n-\n-               HEAD (refers to branch 'master')\n-      e---f     |\n-     /          v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is important to realize that at this point nothing refers to commit\n-`f`. Eventually commit `f` (and by extension commit `e`) will be deleted\n-by the routine Git garbage collection process, unless we create a reference\n-before that happens. If we have not yet moved away from commit `f`,\n-any of these will create a reference to it:\n-\n-------------\n-$ git checkout -b foo  # or \"git switch -c foo\"  <1>\n-$ git branch foo                                 <2>\n-$ git tag foo                                    <3>\n-------------\n-<1> creates a new branch `foo`, which refers to commit `f`, and then\n-    updates `HEAD` to refer to branch `foo`. In other words, we'll no longer\n-    be in detached `HEAD` state after this command.\n-<2> similarly creates a new branch `foo`, which refers to commit `f`,\n-    but leaves `HEAD` detached.\n-<3> creates a new tag `foo`, which refers to commit `f`,\n-    leaving `HEAD` detached.\n-\n-If we have moved away from commit `f`, then we must first recover its object\n-name (typically by using git reflog), and then we can create a reference to\n-it. For example, to see the last two commits to which `HEAD` referred, we\n-can use either of these commands:\n-\n-------------\n-$ git reflog -2 HEAD # or\n-$ git log -g -2 HEAD\n-------------\n+include::detached-head.adoc[]\n \n [[ARGUMENT_DISAMBIGUATION]]\n ARGUMENT DISAMBIGUATION\ndiff --git a/Documentation/gitdetached-head.adoc b/Documentation/gitdetached-head.adoc\nnew file mode 100644\nindex 0000000000..a477060db2\n--- /dev/null\n+++ b/Documentation/gitdetached-head.adoc\n@@ -0,0 +1,14 @@\n+gitdetached-head(7)\n+===================\n+\n+NAME\n+----\n+gitdetached-head - How detached HEAD state works\n+\n+DESCRIPTION\n+-----------\n+include::detached-head.adoc[]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex cfa9c67609..6b3141647f 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -197,6 +197,7 @@ manpages = {\n   'gitcredentials.adoc' : 7,\n   'gitcvs-migration.adoc' : 7,\n   'gitdatamodel.adoc' : 7,\n+  'gitdetached-head.adoc' : 7,\n   'gitdiffcore.adoc' : 7,\n   'giteveryday.adoc' : 7,\n   'gitfaq.adoc' : 7,\ndiff --git a/advice.c b/advice.c\nindex 401d047391..8d2c1ff1ee 100644\n--- a/advice.c\n+++ b/advice.c\n@@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n \t\"\\n\"\n \t\"  git switch -\\n\"\n \t\"\\n\"\n+\t\"Run `git help detached-head` to learn more.\\n\"\n \t\"Turn off this advice by setting config variable advice.detachedHead to false\\n\\n\");\n \n \tfprintf(stderr, fmt, new_name);\ndiff --git a/command-list.txt b/command-list.txt\nindex 63ae2a67c9..7fb57765fb 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -218,6 +218,7 @@ gitcore-tutorial                        guide\n gitcredentials                          guide\n gitcvs-migration                        guide\n gitdatamodel                            guide\n+gitdetached-head                        guide\n gitdiffcore                             guide\n giteveryday                             guide\n gitfaq                                  guide\n\nbase-commit: 5a7d1e8045ce66c908f62598e26cbb8df7b39a90\n-- \ngitgitgadget\n\n"},{"id":"558249","messageId":"ddc6d42c-6e40-46a5-bb70-f89f11525ac4@jvns.ca","threadId":"66484","inReplyTo":"CALnO6CBGcG42NxtpuPaJVrzAMC=J8iVstsHCSi6vDQhDmFJ-Kw@mail.gmail.com","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-11T21:45:34Z","receivedAt":"2026-11-11T21:45:34Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> Here's what Junio suggested^, and here's what v4 has\n>\n> +`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:\n> +\n> +1. A branch, which is your current branch.\n> +2. A commit ID, when you don't have a current branch.\n> +   This is called \"detached HEAD state\".\n> +\n> +It can sometimes be useful for `HEAD` to be a commit ID, because\n> +it lets you easily check out an old version of your project. For\n> +example, a data scientist could use this to run an old version of a\n> +data pipeline or a programmer could use this to figure out when a bug\n> +was introduced.\n>\n> I do not personally think it's worth focusing on \"the state from which\n> your current changes started\" (even leaving aside the \"what if I have\n> no changes?\" moment), in part because I don't think that's how most\n> users conceive of HEAD. Other than that detail, I think the first\n> paragraphs of each option coincide.\n>\n> There are some quotes which use the \"it's the parent of the next\n> commit\" mental model, though, so we could include a comment on that?\n> It might be distracting, and could make its way into some kind of\n> admonition/aside if need be?\n\nYeah I agree the \"it's the parent of the next commit\" would be distracting unless there's a specific reason we need to include it.\n\nI agree \"the state from which your current changes started\" isn't right but I think if we reinterpret it as \"the current commit you have checked out\" (which I think has the same or a very similar meaning) then it'll seem familiar to folks and might even help.\n\n> The second paragraphs differ a bit, with Junio's containing some bits\n> about clobbering extant branches and not needing temporary branches. I\n> think we could work something in there, like\n>\n>      It can sometimes be useful for `HEAD` to be a commit ID,\n>      because it lets you easily check out an old version of your\n>      project. For example, a data scientist could use this to run\n>      an old version of a data pipeline or a programmer could use\n>      this to figure out when a bug was introduced. By detaching\n>      `HEAD`, you don't need to worry about clobbering an existing\n>      branch or creating a temporary branch.\n\nThanks, I took this language. I left out \"clobbering an existing branch\" because I couldn't think of a reason why someone would clobber an existing branch to check out an old version of their code.\n\n- Julia\n\n\n"},{"id":"558271","messageId":"xmqqqzgrklkh.fsf@gitster.g","threadId":"66484","inReplyTo":"pull.2250.v5.git.1794432869488.gitgitgadget@gmail.com","subject":"Re: [PATCH v5] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-11T23:14:22Z","receivedAt":"2026-11-11T23:14:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> +current branch. Internally in Git, `HEAD` can either be stored as:\n\nI am not sure if I am the only one who finds this phrasing awkward.\n\nIt is not like HEAD is stored (in somewhere) as something.  Rather,\nHEAD *is* the container.  Its implementation may be a file on the\nfilesystem in reffiles backend, or a record in the reftable\ndatabase.  In either case, HEAD stores the refname of the current\nbranch, or the object name of the current commit the HEAD is\ndetached at.\n\nSo, from that point of view, I would understand it better if the\nabove said\n\n    Internally in Git, `HEAD` can store either ... (branch name or\n    commit object name) ...\n\nor something.\n\n> diff --git a/advice.c b/advice.c\n> index 401d047391..8d2c1ff1ee 100644\n> --- a/advice.c\n> +++ b/advice.c\n> @@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n>  \t\"\\n\"\n>  \t\"  git switch -\\n\"\n>  \t\"\\n\"\n> +\t\"Run `git help detached-head` to learn more.\\n\"\n\nShouldn't we be using a normal single quote instead of backtick?\n\nExisting references to command in this file has the command without\nquotes, on its own line \"\\tgit merge --no-ff\\n\", or uses a normal\nsingle quote as in \"... use 'git add/rm <file>'\".\n\nPeople's terminals do not grok markdown anyway ;-)\n\n"},{"id":"558272","messageId":"03a0b42a-08f8-4b9e-9dd9-9caf3fc5f7e6@jvns.ca","threadId":"66484","inReplyTo":"xmqqqzgrklkh.fsf@gitster.g","subject":"Re: [PATCH v5] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-12T00:01:31Z","receivedAt":"2026-11-12T00:01:31Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\nOn 2026-11-11 6:14 p.m., Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> +current branch. Internally in Git, `HEAD` can either be stored as:\n> I am not sure if I am the only one who finds this phrasing awkward.\n>\n> It is not like HEAD is stored (in somewhere) as something.  Rather,\n> HEAD *is* the container.  Its implementation may be a file on the\n> filesystem in reffiles backend, or a record in the reftable\n> database.  In either case, HEAD stores the refname of the current\n> branch, or the object name of the current commit the HEAD is\n> detached at.\n>\n> So, from that point of view, I would understand it better if the\n> above said\n>\n>      Internally in Git, `HEAD` can store either ... (branch name or\n>      commit object name) ...\n>\n> or something.\nI think it does read better that way, I'll change it to that.\n>> diff --git a/advice.c b/advice.c\n>> index 401d047391..8d2c1ff1ee 100644\n>> --- a/advice.c\n>> +++ b/advice.c\n>> @@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n>>   \t\"\\n\"\n>>   \t\"  git switch -\\n\"\n>>   \t\"\\n\"\n>> +\t\"Run `git help detached-head` to learn more.\\n\"\n> Shouldn't we be using a normal single quote instead of backtick?\n\nSeems reasonable, I'll change it.\n\nWill send a new version with those two things tomorrow if there's nothing else.\n\n\n"},{"id":"558273","messageId":"D6E81F16-3546-4FF2-B589-3A5CD70E966F@gmail.com","threadId":"66484","inReplyTo":"ddc6d42c-6e40-46a5-bb70-f89f11525ac4@jvns.ca","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-11-12T01:58:37Z","receivedAt":"2026-11-12T01:58:37Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 11 nov. 2026 à 16:45, Julia Evans <julia@jvns.ca> a écrit :\n> \n> ﻿\n>> \n>> […]\n> \n> Yeah I agree the \"it's the parent of the next commit\" would be distracting unless there's a specific reason we need to include it.\n> \n> I agree \"the state from which your current changes started\" isn't right but I think if we reinterpret it as \"the current commit you have checked out\" (which I think has the same or a very similar meaning) then it'll seem familiar to folks and might even help.\n> \n>> […]\n> \n> Thanks, I took this language. I left out \"clobbering an existing branch\" because I couldn't think of a reason why someone would clobber an existing branch to check out an old version of their code.\n> \n> - Julia\n\nGlad we could move this forward!\n"},{"id":"558275","messageId":"xmqqmrrelmja.fsf@gitster.g","threadId":"66484","inReplyTo":"xmqqqzgrklkh.fsf@gitster.g","subject":"Re: [PATCH v5] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-12T04:08:09Z","receivedAt":"2026-11-12T04:08:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n>\n>> diff --git a/advice.c b/advice.c\n>> index 401d047391..8d2c1ff1ee 100644\n>> --- a/advice.c\n>> +++ b/advice.c\n>> @@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n>>  \t\"\\n\"\n>>  \t\"  git switch -\\n\"\n>>  \t\"\\n\"\n>> +\t\"Run `git help detached-head` to learn more.\\n\"\n>\n> Shouldn't we be using a normal single quote instead of backtick?\n>\n> Existing references to command in this file has the command without\n> quotes, on its own line \"\\tgit merge --no-ff\\n\", or uses a normal\n> single quote as in \"... use 'git add/rm <file>'\".\n>\n> People's terminals do not grok markdown anyway ;-)\n\nOne more thing.\n\nThis change needs to update t/t2020-checkout-detach.sh because the\nnew output is not expected there (yet).\n\n\n"},{"id":"558299","messageId":"xmqq5wy2kqhl.fsf@gitster.g","threadId":"66484","inReplyTo":"ddc6d42c-6e40-46a5-bb70-f89f11525ac4@jvns.ca","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-12T15:40:22Z","receivedAt":"2026-11-12T15:40:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Julia Evans <julia@jvns.ca> writes:\n\n> Yeah I agree the \"it's the parent of the next commit\" would be \n> distracting unless there's a specific reason we need to include it.\n>\n> I agree \"the state from which your current changes started\" isn't right \n> but I think if we reinterpret it as \"the current commit you have checked \n> out\" (which I think has the same or a very similar meaning) then it'll \n> seem familiar to folks and might even help.\n> ...\n> because I couldn't think of a reason why someone would clobber an \n> existing branch to check out an old version of their code.\n\nWhen I find something interesting in a topic, which may be an old\ncommit from the point of view of 'seen', I would detach HEAD at the\ntip of the branch to take a look at its contents, because what I am\ngoing to do next would very often involve modifying the working tree\nfiles to experiment.  Even a topic that is documentation only, like\nthe je/doc-detached-head topic, can have a cascading effect that\nends up breaking tests, for example, and I'd be futzing with the\nsources and tests to figure out what the best fix would be.  Even\nthough I am not going to make any permanent commits out of these\nefforts, being able to make temporary commits to mark a resumable\nstate is handy, and when my spelunking gets longer, I do make such\ncommits.\n\nBut of course, I do *not* want to contaminate the topic branch I\nhave been looking at.  The work I do, whether it is for validation\nor for satisfying my own curiosity, does not necessarily align with\nthe objective the topic author had in mind when they wrote it.\n\nThis is where detached HEAD is the perfect mechanism to take\nadvantage of.  You do not want to clobber the branch you are going\nto start your journey at, yet you want to be able to make tentative\nchanges to experiment, and you want to be able to take snapshots.\n\nAnd during the journey, your HEAD points at a commit from which your\ncurrent changes started and points at a commit your next commit will\nrecord as its parent.\n\nI guess it requires a developer's mindset and imagination to\nappreciate why detached HEAD is useful while spelunking.  We often\nphrase the act of visiting random commits (often older ones) as\n\"sight-seeing\", but in reality, even when you are mostly looking,\nyou do want to futz with things you see there.\n\nIt is in a developer's heart ;-).\n\nHope this clarifies.\n\n"},{"id":"558302","messageId":"931a94e4-feab-49a9-b5c6-479f0d7f8b75@jvns.ca","threadId":"66484","inReplyTo":"xmqq5wy2kqhl.fsf@gitster.g","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-12T16:37:35Z","receivedAt":"2026-11-12T16:37:35Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\nOn 2026-11-12 10:40 a.m., Junio C Hamano wrote:\n> Julia Evans <julia@jvns.ca> writes:\n>\n>> Yeah I agree the \"it's the parent of the next commit\" would be\n>> distracting unless there's a specific reason we need to include it.\n>>\n>> I agree \"the state from which your current changes started\" isn't right\n>> but I think if we reinterpret it as \"the current commit you have checked\n>> out\" (which I think has the same or a very similar meaning) then it'll\n>> seem familiar to folks and might even help.\n>> ...\n>> because I couldn't think of a reason why someone would clobber an\n>> existing branch to check out an old version of their code.\n> When I find something interesting in a topic, which may be an old\n> commit from the point of view of 'seen', I would detach HEAD at the\n> tip of the branch to take a look at its contents, because what I am\n> going to do next would very often involve modifying the working tree\n> files to experiment.  Even a topic that is documentation only, like\n> the je/doc-detached-head topic, can have a cascading effect that\n> ends up breaking tests, for example, and I'd be futzing with the\n> sources and tests to figure out what the best fix would be.  Even\n> though I am not going to make any permanent commits out of these\n> efforts, being able to make temporary commits to mark a resumable\n> state is handy, and when my spelunking gets longer, I do make such\n> commits.\nThanks, this is helpful, it makes sense now why this would be useful to you as the Git maintainer with what I've learned about your workflow.\n> I guess it requires a developer's mindset and imagination to\n> appreciate why detached HEAD is useful while spelunking.  We often\n> phrase the act of visiting random commits (often older ones) as\n> \"sight-seeing\", but in reality, even when you are mostly looking,\n> you do want to futz with things you see there.\n\nI'm not sure what you mean by \"it requires a developer's mindset\", in my time working as a developer using Git I never ran into a case where I would have needed to clobber a branch in this way :)\n\nIt's important to remember that different Git users can have very different workflows (especially among developers, I think!) and that one person's workflow may not generalize well to other developers.\n\nThis is something I pay a lot of attention to in my own work: some parts of my own personal workflow are a bit unusual and I keep a mental catalog of those things to avoid giving them as advice.\n\n> It is in a developer's heart ;-).\n>\n> Hope this clarifies.\n\n"},{"id":"558330","messageId":"xmqqik21j1ie.fsf@gitster.g","threadId":"66484","inReplyTo":"931a94e4-feab-49a9-b5c6-479f0d7f8b75@jvns.ca","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-12T19:25:13Z","receivedAt":"2026-11-12T19:25:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Julia Evans <julia@jvns.ca> writes:\n\n>> I guess it requires a developer's mindset and imagination to\n>> appreciate why detached HEAD is useful while spelunking.  We often\n>> phrase the act of visiting random commits (often older ones) as\n>> \"sight-seeing\", but in reality, even when you are mostly looking,\n>> you do want to futz with things you see there.\n>\n> I'm not sure what you mean by \"it requires a developer's mindset\", in my \n> time working as a developer using Git I never ran into a case where I \n> would have needed to clobber a branch in this way :)\n\nSightseeing is not just going to look and see, but touching and\nbreaking things.  That kind of curiosity was what I meant by a\ndeveloper's mindset.\n\nAnd of course, I never ran into a case where I needed to clobber a\nbranch, either.  That is why I do not work on other people's topic\nbranches to begin with, and make use of detached HEAD instead.\n\nIn any case, now we have a shared better understanding of where\n\"where your current work started\" and \"will be the parent of your\nnext commit\" came from.  Hopefully the next iteration will become\nclearer on these points?  I think the central difference is that you\nseem to consider detached HEAD state is only about pure sightseeing\nwhile it was designed to allow touching and breaking.  If the user\nis not making any changes, of course it does not make sense to talk\nabout \"your current changes\" or \"next commit\".  But detached HEAD is\nnot limited to such a world view.\n\nThanks.\n\n"},{"id":"558358","messageId":"4d6f9b6a-e658-4797-bc4a-0cfc533056d8@jvns.ca","threadId":"66484","inReplyTo":"xmqqik21j1ie.fsf@gitster.g","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-12T22:45:07Z","receivedAt":"2026-11-12T22:45:07Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> I think the central difference is that you\n> seem to consider detached HEAD state is only about pure sightseeing\n> while it was designed to allow touching and breaking.  If the user\n> is not making any changes, of course it does not make sense to talk\n> about \"your current changes\" or \"next commit\".  But detached HEAD is\n> not limited to such a world view.\n\nWe say very clearly that you can make commits while in detached HEAD state so I don't think there's any danger of readers not realizing that's possible.\n\n  But it's important to know that if you create new commits while in\n  detached HEAD state, those commits won't be on a branch.\n\n\n"},{"id":"558359","messageId":"pull.2250.v6.git.1794523656200.gitgitgadget@gmail.com","threadId":"66484","inReplyTo":"pull.2250.git.1791384721919.gitgitgadget@gmail.com","subject":"[PATCH v6] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-11-12T22:47:36Z","receivedAt":"2026-11-12T22:47:36Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nThe current explanation has the following issues:\n\n- Says detached HEAD state is useful but doesn't explain why\n- Takes many paragraphs before explaining what detached HEAD state is\n- It's common for users to accidentally end up in detached HEAD state,\n  but it doesn't explain why that might happen\n- One of the UI improvements in `git switch` is to make it harder\n  to detach accidentally, but that isn't advertised.\n  See 7968bef06b (switch: only allow explicit detached HEAD, 2019-03-29)\n- Too many confusing diagrams\n\nWrite a new explanation addressing these issues, and put it in a\nstandalone guide so that we can easily reference it from advice\n(\"see `git help detached-head`\").\nThe result is a shorter guide that covers more material.\n\nThe framing that \"Git considers commits that aren't on a branch/other\nreference to be garbage\" is taken from Steve Klabnik's tutorial\nhttps://steveklabnik.github.io/jujutsu-tutorial/branching-merging-and-conflicts/anonymous-branches.html.\nIt's funny and it's consistent with the way Git uses the term\n\"garbage collection\".\n\nCo-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n    doc: checkout: rewrite detached HEAD state explanation\n    \n    This is a pretty quick rewrite where we didn't get any user feedback. If\n    we really want to make sure it's clear to users as possible, we should\n    IMO do a second stage later where we ask users which parts are unclear.\n    \n    Changes in v2:\n    \n     * Make the meson.build and Makefile changes (thanks to Kristoffer)\n     * Rename to gitdata-model (thanks to Kristoffer)\n     * Mention commits will be deleted after 90 days to make it seem less\n       scary (thanks to Kristoffer)\n     * Add an \"easily\" qualifier to \"it lets you look at an old version of\n       your code\", to avoid implying that this is the only way (thanks to\n       Junio)\n     * Mention that Git will warn you when switching branches if you're\n       leaving commits behind (thanks to Junio)\n     * Remove \"unintentionally\" (thanks to Junio)\n     * Mention git help datamodel (thanks to Junio)\n    \n    Changes in v3:\n    \n    I went through the style comments from v1.\n    \n    content changes:\n    \n     * Change \"90 days\" to \"30 days\" (thanks to Junio)\n     * Say that HEAD is where Git stores your \"current branch or commit\" to\n       make the first sentence read better (thanks to Junio)\n     * Mention git switch --detach a little earlier (thanks to Kristoffer)\n     * Replace \"the only problem\" with \"it's important to know that\" (thanks\n       to Junio)\n    \n    formatting changes etc:\n    \n     * Replace help detachedhead with help detached-head (thanks to Junio)\n     * Fix spacing in command-list.txt (thanks to Junio)\n     * Get Marie's signoff (thanks to Junio)\n    \n    non-changes: Left these phrases alone because I don't think the proposed\n    changes would make it more clear.\n    \n     * \"3 main ways you can end up in detached HEAD state\"\n     * \"to look at an old version of your code\"\n     * \"avoid accidentally ending up\"\n    \n    Changes in v4:\n    \n     * Fix commit message in example: \"fix bug\", not \"3\" (thanks to Junio)\n     * \"commit for that tag\" -> \"tagged commit\" (thanks to Junio)\n     * Move \"git checkout COMMIT_ID or git switch --detach COMMIT_ID\" down\n       to the \"3 main ways\" list to reduce duplication (thanks to Junio)\n     * Add some examples and be clearer about how detached HEAD state lets\n       you check out an old version of the project. (thanks to Junio)\n    \n    non-changes:\n    \n     * It's probably possible to explain HEAD better. That seems like a big\n       project to me since HEAD in Git is a very tricky topic. I think it\n       would be better to address in a separate patch series to have more\n       time to think it through. Or if we think it's not possible to merge\n       this without explaining HEAD better then I guess it shouldn't be\n       merged.\n    \n    Changes in v5:\n    \n     * Explain HEAD's relationship to the current commit to make it feel\n       more uniform (thanks to Junio)\n     * Add a note about the benefits of detaching HEAD (thanks to Junio &\n       Ben)\n     * Change \"HEAD can either be a commit ID or a branch name\"\n    \n    Changes in v6:\n    \n     * Adjust some wording around \"stores\" (thanks to Junio)\n     * Change the quote style in advice.c (thanks to Junio)\n     * Update expected output in t2020-checkout-detach.sh (thanks to Junio)\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2250%2Fjvns%2Fdetached-head-v6\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2250/jvns/detached-head-v6\nPull-Request: https://github.com/gitgitgadget/git/pull/2250\n\nRange-diff vs v5:\n\n 1:  cd4e443809 ! 1:  64f50b8248 doc: checkout: rewrite detached HEAD state explanation\n     @@ Documentation/detached-head.adoc (new)\n      @@\n      +In Git, you can always use `HEAD` to refer to the commit you have\n      +checked out. But `HEAD` is also where Git stores the name of your\n     -+current branch. Internally in Git, `HEAD` can either be stored as:\n     ++current branch. Internally in Git, `HEAD` can store either:\n      +\n      +1. A branch name, which is your current branch.\n      +   The commit you have checked out is the latest commit on that branch.\n     @@ advice.c: void detach_advice(const char *new_name)\n       \t\"\\n\"\n       \t\"  git switch -\\n\"\n       \t\"\\n\"\n     -+\t\"Run `git help detached-head` to learn more.\\n\"\n     ++\t\"Run 'git help detached-head' to learn more.\\n\"\n       \t\"Turn off this advice by setting config variable advice.detachedHead to false\\n\\n\");\n       \n       \tfprintf(stderr, fmt, new_name);\n     @@ command-list.txt: gitcore-tutorial                        guide\n       gitdiffcore                             guide\n       giteveryday                             guide\n       gitfaq                                  guide\n     +\n     + ## t/t2020-checkout-detach.sh ##\n     +@@ t/t2020-checkout-detach.sh: test_expect_success 'describe_detached_head prints no SHA-1 ellipsis when not as\n     + \n     + \t  git switch -\n     + \n     ++\tRun 'git help detached-head' to learn more.\n     + \tTurn off this advice by setting config variable advice.detachedHead to false\n     + \n     + \tHEAD is now at \\$commit three\n     +@@ t/t2020-checkout-detach.sh: test_expect_success 'describe_detached_head does print SHA-1 ellipsis when asked\n     + \n     + \t  git switch -\n     + \n     ++\tRun 'git help detached-head' to learn more.\n     + \tTurn off this advice by setting config variable advice.detachedHead to false\n     + \n     + \tHEAD is now at \\$commit... three\n\n\n Documentation/Makefile              |   1 +\n Documentation/detached-head.adoc    |  64 ++++++++++++++\n Documentation/git-checkout.adoc     | 129 +---------------------------\n Documentation/gitdetached-head.adoc |  14 +++\n Documentation/meson.build           |   1 +\n advice.c                            |   1 +\n command-list.txt                    |   1 +\n t/t2020-checkout-detach.sh          |   2 +\n 8 files changed, 85 insertions(+), 128 deletions(-)\n create mode 100644 Documentation/detached-head.adoc\n create mode 100644 Documentation/gitdetached-head.adoc\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f8dea4b395..5892f48b06 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -54,6 +54,7 @@ MAN7_TXT += gitcore-tutorial.adoc\n MAN7_TXT += gitcredentials.adoc\n MAN7_TXT += gitcvs-migration.adoc\n MAN7_TXT += gitdatamodel.adoc\n+MAN7_TXT += gitdetached-head.adoc\n MAN7_TXT += gitdiffcore.adoc\n MAN7_TXT += giteveryday.adoc\n MAN7_TXT += gitfaq.adoc\ndiff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc\nnew file mode 100644\nindex 0000000000..78ee6631a4\n--- /dev/null\n+++ b/Documentation/detached-head.adoc\n@@ -0,0 +1,64 @@\n+In Git, you can always use `HEAD` to refer to the commit you have\n+checked out. But `HEAD` is also where Git stores the name of your\n+current branch. Internally in Git, `HEAD` can store either:\n+\n+1. A branch name, which is your current branch.\n+   The commit you have checked out is the latest commit on that branch.\n+2. A commit ID, when you don't have a current branch.\n+   This is called \"detached HEAD state\".\n+\n+It can sometimes be useful for `HEAD` to be a commit ID, because\n+it lets you easily check out an old version of your project. For\n+example, a data scientist could use this to run an old version of a\n+data pipeline or a programmer could use this to figure out when a bug\n+was introduced. By detaching `HEAD`, you don't need to create a\n+temporary branch.\n+\n+But it's important to know that if you create new commits while in\n+detached HEAD state, those commits won't be on a branch. This makes\n+those new commits much harder to find later. Also, Git considers commits\n+that aren't on any branch (or a tag or other reference) to be garbage.\n+Git will eventually permanently delete those \"garbage\" commits during\n+garbage collection. Those commits will be deleted after 30 days by\n+default, see linkgit:git-gc[1] for more.\n+\n+There are 3 main ways you can end up in detached HEAD state:\n+\n+1. `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`,\n+   where `COMMIT_ID` is a commit ID.\n+2. `git checkout v1.3`, where v1.3 is a tag name\n+3. `git checkout origin/main`, where `origin/main` is\n+   a remote-tracking branch\n+\n+Checking out a tag puts you in detached HEAD state because `HEAD` can\n+only be a branch or a commit, not a tag or any other reference.\n+So `git checkout TAG` will set HEAD to the tagged commit.\n+\n+The easiest way to avoid accidentally ending up in detached HEAD state\n+is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to\n+switch branches. `git switch` won't let you detach unless you explicitly\n+pass the `--detach` argument.\n+\n+To get back onto a branch, you can:\n+\n+1. Switch to the branch you want to be on, with `git switch BRANCHNAME`.\n+2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`.\n+   You might want to do this if you've created new commits, so that you can\n+   find the commit later and so that it won't be garbage collected.\n+\n+If you switch branches after making commits in detached HEAD state, Git\n+will warn you that you might be about to \"lose\" those commits and print\n+out the commit ID. You can also always find those commits later using\n+linkgit:git-reflog[1].\n+\n+Here's what that warning looks like:\n+\n+-------------------------\n+Warning: you are leaving 1 commit behind, not connected to\n+any of your branches:\n+\n+  48c09f6 fix bug\n+-------------------------\n+\n+For a more in-depth explanation of how `HEAD` works in Git,\n+see linkgit:gitdatamodel[7] (`git help datamodel`).\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 2aefea0228..4e9e94e24d 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -376,135 +376,8 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n [[DETACHED_HEAD]]\n DETACHED HEAD\n -------------\n-`HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each\n-branch refers to a specific commit. Let's look at a repo with three\n-commits, one of them tagged, and with branch `master` checked out:\n \n-------------\n-           HEAD (refers to branch 'master')\n-            |\n-            v\n-a---b---c  branch 'master' (refers to commit 'c')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-When a commit is created in this state, the branch is updated to refer to\n-the new commit. Specifically, `git commit` creates a new commit `d`, whose\n-parent is commit `c`, and then updates branch `master` to refer to new\n-commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers\n-to commit `d`:\n-\n-------------\n-$ edit; git add; git commit\n-\n-               HEAD (refers to branch 'master')\n-                |\n-                v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is sometimes useful to be able to checkout a commit that is not at\n-the tip of any named branch, or even to create a new commit that is not\n-referenced by a named branch. Let's look at what happens when we\n-checkout commit `b` (here we show two ways this may be done):\n-\n-------------\n-$ git checkout v2.0  # or\n-$ git checkout master^^\n-\n-   HEAD (refers to commit 'b')\n-    |\n-    v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-Notice that regardless of which checkout command we use, `HEAD` now refers\n-directly to commit `b`. This is known as being in detached `HEAD` state.\n-It means simply that `HEAD` refers to a specific commit, as opposed to\n-referring to a named branch. Let's see what happens when we create a commit:\n-\n-------------\n-$ edit; git add; git commit\n-\n-     HEAD (refers to commit 'e')\n-      |\n-      v\n-      e\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-There is now a new commit `e`, but it is referenced only by `HEAD`. We can\n-of course add yet another commit in this state:\n-\n-------------\n-$ edit; git add; git commit\n-\n-\t HEAD (refers to commit 'f')\n-\t  |\n-\t  v\n-      e---f\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-In fact, we can perform all the normal Git operations. But, let's look\n-at what happens when we then checkout `master`:\n-\n-------------\n-$ git checkout master\n-\n-               HEAD (refers to branch 'master')\n-      e---f     |\n-     /          v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is important to realize that at this point nothing refers to commit\n-`f`. Eventually commit `f` (and by extension commit `e`) will be deleted\n-by the routine Git garbage collection process, unless we create a reference\n-before that happens. If we have not yet moved away from commit `f`,\n-any of these will create a reference to it:\n-\n-------------\n-$ git checkout -b foo  # or \"git switch -c foo\"  <1>\n-$ git branch foo                                 <2>\n-$ git tag foo                                    <3>\n-------------\n-<1> creates a new branch `foo`, which refers to commit `f`, and then\n-    updates `HEAD` to refer to branch `foo`. In other words, we'll no longer\n-    be in detached `HEAD` state after this command.\n-<2> similarly creates a new branch `foo`, which refers to commit `f`,\n-    but leaves `HEAD` detached.\n-<3> creates a new tag `foo`, which refers to commit `f`,\n-    leaving `HEAD` detached.\n-\n-If we have moved away from commit `f`, then we must first recover its object\n-name (typically by using git reflog), and then we can create a reference to\n-it. For example, to see the last two commits to which `HEAD` referred, we\n-can use either of these commands:\n-\n-------------\n-$ git reflog -2 HEAD # or\n-$ git log -g -2 HEAD\n-------------\n+include::detached-head.adoc[]\n \n [[ARGUMENT_DISAMBIGUATION]]\n ARGUMENT DISAMBIGUATION\ndiff --git a/Documentation/gitdetached-head.adoc b/Documentation/gitdetached-head.adoc\nnew file mode 100644\nindex 0000000000..a477060db2\n--- /dev/null\n+++ b/Documentation/gitdetached-head.adoc\n@@ -0,0 +1,14 @@\n+gitdetached-head(7)\n+===================\n+\n+NAME\n+----\n+gitdetached-head - How detached HEAD state works\n+\n+DESCRIPTION\n+-----------\n+include::detached-head.adoc[]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex cfa9c67609..6b3141647f 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -197,6 +197,7 @@ manpages = {\n   'gitcredentials.adoc' : 7,\n   'gitcvs-migration.adoc' : 7,\n   'gitdatamodel.adoc' : 7,\n+  'gitdetached-head.adoc' : 7,\n   'gitdiffcore.adoc' : 7,\n   'giteveryday.adoc' : 7,\n   'gitfaq.adoc' : 7,\ndiff --git a/advice.c b/advice.c\nindex 401d047391..3238e9b866 100644\n--- a/advice.c\n+++ b/advice.c\n@@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n \t\"\\n\"\n \t\"  git switch -\\n\"\n \t\"\\n\"\n+\t\"Run 'git help detached-head' to learn more.\\n\"\n \t\"Turn off this advice by setting config variable advice.detachedHead to false\\n\\n\");\n \n \tfprintf(stderr, fmt, new_name);\ndiff --git a/command-list.txt b/command-list.txt\nindex 63ae2a67c9..7fb57765fb 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -218,6 +218,7 @@ gitcore-tutorial                        guide\n gitcredentials                          guide\n gitcvs-migration                        guide\n gitdatamodel                            guide\n+gitdetached-head                        guide\n gitdiffcore                             guide\n giteveryday                             guide\n gitfaq                                  guide\ndiff --git a/t/t2020-checkout-detach.sh b/t/t2020-checkout-detach.sh\nindex 28bbbe6c05..b0bfd3191c 100755\n--- a/t/t2020-checkout-detach.sh\n+++ b/t/t2020-checkout-detach.sh\n@@ -228,6 +228,7 @@ test_expect_success 'describe_detached_head prints no SHA-1 ellipsis when not as\n \n \t  git switch -\n \n+\tRun 'git help detached-head' to learn more.\n \tTurn off this advice by setting config variable advice.detachedHead to false\n \n \tHEAD is now at \\$commit three\n@@ -310,6 +311,7 @@ test_expect_success 'describe_detached_head does print SHA-1 ellipsis when asked\n \n \t  git switch -\n \n+\tRun 'git help detached-head' to learn more.\n \tTurn off this advice by setting config variable advice.detachedHead to false\n \n \tHEAD is now at \\$commit... three\n\nbase-commit: 5a7d1e8045ce66c908f62598e26cbb8df7b39a90\n-- \ngitgitgadget\n\n"},{"id":"558366","messageId":"xmqqfqx5foxd.fsf@gitster.g","threadId":"66484","inReplyTo":"4d6f9b6a-e658-4797-bc4a-0cfc533056d8@jvns.ca","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-13T02:25:18Z","receivedAt":"2026-11-13T02:25:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Julia Evans <julia@jvns.ca> writes:\n\n>> I think the central difference is that you\n>> seem to consider detached HEAD state is only about pure sightseeing\n>> while it was designed to allow touching and breaking.  If the user\n>> is not making any changes, of course it does not make sense to talk\n>> about \"your current changes\" or \"next commit\".  But detached HEAD is\n>> not limited to such a world view.\n>\n> We say very clearly that you can make commits while in detached HEAD \n> state so I don't think there's any danger of readers not realizing \n> that's possible.\n>\n>    But it's important to know that if you create new commits while in\n>    detached HEAD state, those commits won't be on a branch.\n\nYeah, but that isn't the purpose of mentioning \"next commit\" etc. to\nmake readers realize that.  So I am not sure what you want to say\nwith that.\n\nThe mention of \"your current work\" (started at the HEAD) and \"next\ncommit\" is to lay groundwork to explain what happens when they make\nthat commit, and how it is different when they are on detached HEAD,\nin contrast to when they are on a branch.  After all, what we were\ndiscusssing is an improved explanation on detached HEAD, and your\ncommits not affecting any of your branch *is* the most important\naspect of what detached HEAD gives you.\n\n\n"},{"id":"558384","messageId":"36e73720-287f-47a5-bd3f-dc53629ac968@jvns.ca","threadId":"66484","inReplyTo":"xmqqfqx5foxd.fsf@gitster.g","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-13T12:45:22Z","receivedAt":"2026-11-13T12:45:22Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\nOn 2026-11-12 9:25 p.m., Junio C Hamano wrote:\n> Julia Evans <julia@jvns.ca> writes:\n>\n>>> I think the central difference is that you\n>>> seem to consider detached HEAD state is only about pure sightseeing\n>>> while it was designed to allow touching and breaking.  If the user\n>>> is not making any changes, of course it does not make sense to talk\n>>> about \"your current changes\" or \"next commit\".  But detached HEAD is\n>>> not limited to such a world view.\n>> We say very clearly that you can make commits while in detached HEAD\n>> state so I don't think there's any danger of readers not realizing\n>> that's possible.\n>>\n>>     But it's important to know that if you create new commits while in\n>>     detached HEAD state, those commits won't be on a branch.\n> Yeah, but that isn't the purpose of mentioning \"next commit\" etc. to\n> make readers realize that.  So I am not sure what you want to say\n> with that.\n>\n> The mention of \"your current work\" (started at the HEAD) and \"next\n> commit\" is to lay groundwork to explain what happens when they make\n> that commit, and how it is different when they are on detached HEAD,\n> in contrast to when they are on a branch.  After all, what we were\n> discusssing is an improved explanation on detached HEAD, and your\n> commits not affecting any of your branch *is* the most important\n> aspect of what detached HEAD gives you\n\nI read this a few times and it's hard for me to tell what the issue being raised is.\n\nAre you saying that we're not explaining all the details from \"`HEAD` can store either a branch or commit ID\" to \"if you create new commits while in detached HEAD state, those commits won't be on a branch\"?\n\nThat's intentional, and I can explain the reasons for it if you'd like. I don't think this is the appropriate document for that information.\n\nHere's an idea to resolve this:\n\n1. Add something to the commit message explaining why we're not giving a full detailed explanation anymore\n\n2. Add some extra info to gitdatamodel.adoc to make sure the information is incldued there, since I think that's the appropriate document.\n\n3. Add a \"see also gitdatamodel...\" to the end of the section for folks who want more information about how HEAD and branches work together.\n\n\n"},{"id":"558409","messageId":"xmqq33t4fxx7.fsf@gitster.g","threadId":"66484","inReplyTo":"36e73720-287f-47a5-bd3f-dc53629ac968@jvns.ca","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-13T17:23:16Z","receivedAt":"2026-11-13T17:23:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Julia Evans <julia@jvns.ca> writes:\n\n>> The mention of \"your current work\" (started at the HEAD) and \"next\n>> commit\" is to lay groundwork to explain what happens when they make\n>> that commit, and how it is different when they are on detached HEAD,\n>> in contrast to when they are on a branch.  After all, what we were\n>> discusssing is an improved explanation on detached HEAD, and your\n>> commits not affecting any of your branch *is* the most important\n>> aspect of what detached HEAD gives you\n>\n> I read this a few times and it's hard for me to tell what the issue \n> being raised is.\n>\n> Are you saying that we're not explaining all the details from \"`HEAD` \n> can store either a branch or commit ID\" to \"if you create new commits \n> while in detached HEAD state, those commits won't be on a branch\"?\n\nNo.  I do not expect an introductory document to tell *all* the\nthings that needs to be known about a topic.  That is an\nencyclopedia, not a technical manual.\n\nThe fact that you would not clobber any branches when you make a\ntemporary commit on a detached HEAD, however, is the most important\nconsequence of HEAD *not* recording what branch we are on that has\nreal *impact* to the end-users.  They can leave their temporary work\nbehind without explicit removal by just checking out a branch, which\nalso means they have to be careful about losing *if* they care about\nwhat they did during this temporary state.\n\nI view it as a disservice to deliberately avoid talking about it.\n\n\n"},{"id":"558411","messageId":"a70524b5-5ece-49fd-acd5-c97e21faa76d@jvns.ca","threadId":"66484","inReplyTo":"xmqq33t4fxx7.fsf@gitster.g","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-13T17:57:56Z","receivedAt":"2026-11-13T17:57:56Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\nOn 2026-11-13 12:23 p.m., Junio C Hamano wrote:\n> Julia Evans <julia@jvns.ca> writes:\n>\n>>> The mention of \"your current work\" (started at the HEAD) and \"next\n>>> commit\" is to lay groundwork to explain what happens when they make\n>>> that commit, and how it is different when they are on detached HEAD,\n>>> in contrast to when they are on a branch.  After all, what we were\n>>> discusssing is an improved explanation on detached HEAD, and your\n>>> commits not affecting any of your branch *is* the most important\n>>> aspect of what detached HEAD gives you\n>> I read this a few times and it's hard for me to tell what the issue\n>> being raised is.\n>>\n>> Are you saying that we're not explaining all the details from \"`HEAD`\n>> can store either a branch or commit ID\" to \"if you create new commits\n>> while in detached HEAD state, those commits won't be on a branch\"?\n> No.  I do not expect an introductory document to tell *all* the\n> things that needs to be known about a topic.  That is an\n> encyclopedia, not a technical manual.\n>\n> The fact that you would not clobber any branches when you make a\n> temporary commit on a detached HEAD, however, is the most important\n> consequence of HEAD *not* recording what branch we are on that has\n> real *impact* to the end-users.  They can leave their temporary work\n> behind without explicit removal by just checking out a branch, which\n> also means they have to be careful about losing *if* they care about\n> what they did during this temporary state.\n>\n> I view it as a disservice to deliberately avoid talking about it.\n\nOkay. How about this?  (the added sentence is between the **)\n\n  For example, a data scientist could use this to run an old version of a\n  data pipeline or a programmer could use this to figure out when a bug\n  was introduced. **You can also use this to make experimental commits\n  without being on a branch.** By detaching `HEAD`, you don't need to\n  create a temporary branch.\n\n\n"},{"id":"558413","messageId":"7cff0912-8d60-4a45-b32c-7f2b5b8691e9@jvns.ca","threadId":"66484","inReplyTo":"a70524b5-5ece-49fd-acd5-c97e21faa76d@jvns.ca","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-13T18:43:24Z","receivedAt":"2026-11-13T18:43:24Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\nOn 2026-11-13 12:57 p.m., Julia Evans wrote:\n>\n> On 2026-11-13 12:23 p.m., Junio C Hamano wrote:\n>> Julia Evans <julia@jvns.ca> writes:\n>>\n>>>> The mention of \"your current work\" (started at the HEAD) and \"next\n>>>> commit\" is to lay groundwork to explain what happens when they make\n>>>> that commit, and how it is different when they are on detached HEAD,\n>>>> in contrast to when they are on a branch.  After all, what we were\n>>>> discusssing is an improved explanation on detached HEAD, and your\n>>>> commits not affecting any of your branch *is* the most important\n>>>> aspect of what detached HEAD gives you\n>>> I read this a few times and it's hard for me to tell what the issue\n>>> being raised is.\n>>>\n>>> Are you saying that we're not explaining all the details from \"`HEAD`\n>>> can store either a branch or commit ID\" to \"if you create new commits\n>>> while in detached HEAD state, those commits won't be on a branch\"?\n>> No.  I do not expect an introductory document to tell *all* the\n>> things that needs to be known about a topic.  That is an\n>> encyclopedia, not a technical manual.\n>>\n>> The fact that you would not clobber any branches when you make a\n>> temporary commit on a detached HEAD, however, is the most important\n>> consequence of HEAD *not* recording what branch we are on that has\n>> real *impact* to the end-users.  They can leave their temporary work\n>> behind without explicit removal by just checking out a branch, which\n>> also means they have to be careful about losing *if* they care about\n>> what they did during this temporary state.\n>>\n>> I view it as a disservice to deliberately avoid talking about it.\n>\n> Okay. How about this?  (the added sentence is between the **)\n>\n>   For example, a data scientist could use this to run an old version of a\n>   data pipeline or a programmer could use this to figure out when a bug\n>   was introduced. **You can also use this to make experimental commits\n>   without being on a branch.** By detaching `HEAD`, you don't need to\n>   create a temporary branch. Also I should say that I do understand that making commits in detached HEAD state is very important to some Git users, I have a friend who loves detached HEAD state so much that he doesn't even use local branches in his Git workflow :)\n\n\n"},{"id":"558424","messageId":"c12bf331-0d11-497b-b5ae-874534a42385@jvns.ca","threadId":"66484","inReplyTo":"xmqq33t4fxx7.fsf@gitster.g","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-13T19:49:10Z","receivedAt":"2026-11-13T19:49:10Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\nOn 2026-11-13 12:23 p.m., Junio C Hamano wrote:\n> Julia Evans <julia@jvns.ca> writes:\n>\n>>> The mention of \"your current work\" (started at the HEAD) and \"next\n>>> commit\" is to lay groundwork to explain what happens when they make\n>>> that commit, and how it is different when they are on detached HEAD,\n>>> in contrast to when they are on a branch.  After all, what we were\n>>> discusssing is an improved explanation on detached HEAD, and your\n>>> commits not affecting any of your branch *is* the most important\n>>> aspect of what detached HEAD gives you\n>> I read this a few times and it's hard for me to tell what the issue\n>> being raised is.\n>>\n>> Are you saying that we're not explaining all the details from \"`HEAD`\n>> can store either a branch or commit ID\" to \"if you create new commits\n>> while in detached HEAD state, those commits won't be on a branch\"?\n> No.  I do not expect an introductory document to tell *all* the\n> things that needs to be known about a topic.  That is an\n> encyclopedia, not a technical manual.\n>\n> The fact that you would not clobber any branches when you make a\n> temporary commit on a detached HEAD, however, is the most important\n> consequence of HEAD *not* recording what branch we are on that has\n> real *impact* to the end-users.  They can leave their temporary work\n> behind without explicit removal by just checking out a branch, which\n> also means they have to be careful about losing *if* they care about\n> what they did during this temporary state.\n>\n> I view it as a disservice to deliberately avoid talking about it.\n\nSorry for the many replies.\n\nI think I've realized that the real conflict here is that we're trying to write to two very different audiences:\n\n1. Someone who's gotten into detached HEAD state by accident (maybe by running `git checkout <tag>`), is stressed, and just wants to understand what happened and what they should do. This is who I originally had in mind when I wrote the document.\n\n2. A more advanced user who's curious about using detached HEAD state and wants to learn more about what they can do with it and what the implications are.\n\nOf course these are both important audiences, but it's always hard to write a document for two very different audience at the same time. For example, one thing that came up in this thread is that creating commits while not on a branch is a problem for the first person and a good thing for the second person.\n\nIt could make sense to restructure it into two parts in the future (one along the lines of \"help! get me out!\"  and one more like \"here's a useful tool\"), but this thread has already gone on for a long time and I'm not sure that would be productive at this point. It might help to add a note in the commit message saying that this \"two audiences\" situation is an issue with the current state and suggesting that perhaps it could be restructured in the future.\n\n\n"},{"id":"558427","messageId":"xmqqpkw89yzi.fsf@gitster.g","threadId":"66484","inReplyTo":"c12bf331-0d11-497b-b5ae-874534a42385@jvns.ca","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-13T21:56:49Z","receivedAt":"2026-11-13T21:56:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Julia Evans <julia@jvns.ca> writes:\n\n> Of course these are both important audiences, but it's always hard to \n> write a document for two very different audience at the same time. For \n> example, one thing that came up in this thread is that creating commits \n> while not on a branch is a problem for the first person and a good thing \n> for the second person.\n\nThis is a manual page, which means it has to cater to both audiences.\nUnlike a tutorial or guide, we cannot say we target this audience\nprimarily and expect the other audience to figure things out\nthemselves.\n\nTo cover the \"oops, I got myself into a problem?  I do not even know\nif I am in trouble, or if Git is behaving as expected, and I am\ntotally lost.  I do not even know which commands I typed in the last\n5 minutes got me into this state\" situation, manual pages that are\norganized along commands to help quick look-up are a bad match.\n\nPerhaps a FAQ or \"survival guide\" that targets these inexperienced\nusers would help?  Unlike manual pages, guides have more freedom in\nchoosing the material covered and the order in which they are\npresented.  I dunno.\n\n"},{"id":"558433","messageId":"c5b53752-cfd8-4db0-b6ed-9fdeb83397fb@jvns.ca","threadId":"66484","inReplyTo":"xmqqpkw89yzi.fsf@gitster.g","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-13T22:17:53Z","receivedAt":"2026-11-13T22:17:53Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\nOn 2026-11-13 4:56 p.m., Junio C Hamano wrote:\n> Julia Evans <julia@jvns.ca> writes:\n>\n>> Of course these are both important audiences, but it's always hard to\n>> write a document for two very different audience at the same time. For\n>> example, one thing that came up in this thread is that creating commits\n>> while not on a branch is a problem for the first person and a good thing\n>> for the second person.\n> This is a manual page, which means it has to cater to both audiences.\n> Unlike a tutorial or guide, we cannot say we target this audience\n> primarily and expect the other audience to figure things out\n> themselves.\n\nMy main goal with this patch series was really to create a new guide that we can reference as `git help detached-head` in our advice to help users who are confused by detached HEAD state.\n\nI thought that it would make sense to frame it as as improvement to`git-checkout` as well (and that the goals of both sections were similar enough that you could easily view the content in both ways), but maybe those documents actually do have fairly different goals and it's too difficult to do that.\n\nI can remove the changes to `git-checkout.adoc` and reframe the series from the point of view of \"we want to help users who are confused by detached HEAD state\", it's an easy change.\n\n> To cover the \"oops, I got myself into a problem?  I do not even know\n> if I am in trouble, or if Git is behaving as expected, and I am\n> totally lost.  I do not even know which commands I typed in the last\n> 5 minutes got me into this state\" situation, manual pages that are\n> organized along commands to help quick look-up are a bad match.\n>\n> Perhaps a FAQ or \"survival guide\" that targets these inexperienced\n> users would help?  Unlike manual pages, guides have more freedom in\n> choosing the material covered and the order in which they are\n> presented.  I dunno.\n\n"},{"id":"558442","messageId":"xmqq8q2w89ee.fsf@gitster.g","threadId":"66484","inReplyTo":"a70524b5-5ece-49fd-acd5-c97e21faa76d@jvns.ca","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-14T01:54:49Z","receivedAt":"2026-11-14T01:54:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Julia Evans <julia@jvns.ca> writes:\n\n> Okay. How about this?  (the added sentence is between the **)\n>\n>    For example, a data scientist could use this to run an old version of a\n>    data pipeline or a programmer could use this to figure out when a bug\n>    was introduced. **You can also use this to make experimental commits\n>    without being on a branch.** By detaching `HEAD`, you don't need to\n>    create a temporary branch.\n\nYes, taking the \"data scientist\" example as a \"pure time machine\nwithout touching, just observing\" scenario, and the \"programmer\"\nexample as an \"inspect and experiment\" scenario, the addition of\nthis single sentence is sufficient to hint at the wide range of\nusefulness to which this feature applies.  Nicely done.\n\nI think this is short and thin enough to be good material to be\nshared between the manual for everybody (which would want to cover\nwider workflows with possibly thin coverage on some and thorough\ncoverage on others) and a survival guide for those who are lost\n(which can be more targeted towards specific audiences).\n\n"},{"id":"558443","messageId":"b19ec7d9-3c9d-46cf-9245-2aefead7adbb@jvns.ca","threadId":"66484","inReplyTo":"xmqq8q2w89ee.fsf@gitster.g","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-14T02:28:30Z","receivedAt":"2026-11-14T02:28:30Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\nOn 2026-11-13 8:54 p.m., Junio C Hamano wrote:\n> Julia Evans <julia@jvns.ca> writes:\n>\n>> Okay. How about this?  (the added sentence is between the **)\n>>\n>>     For example, a data scientist could use this to run an old version of a\n>>     data pipeline or a programmer could use this to figure out when a bug\n>>     was introduced. **You can also use this to make experimental commits\n>>     without being on a branch.** By detaching `HEAD`, you don't need to\n>>     create a temporary branch.\n> Yes, taking the \"data scientist\" example as a \"pure time machine\n> without touching, just observing\" scenario, and the \"programmer\"\n> example as an \"inspect and experiment\" scenario, the addition of\n> this single sentence is sufficient to hint at the wide range of\n> usefulness to which this feature applies.  Nicely done.\n>\n> I think this is short and thin enough to be good material to be\n> shared between the manual for everybody (which would want to cover\n> wider workflows with possibly thin coverage on some and thorough\n> coverage on others) and a survival guide for those who are lost\n> (which can be more targeted towards specific audiences).\n\nGreat to hear, I'll submit this with an updated commit message that says more clearly that this is supposed to serve both purposes.\n\n\n"},{"id":"558444","messageId":"xmqq4idk86me.fsf@gitster.g","threadId":"66484","inReplyTo":"xmqqpkw89yzi.fsf@gitster.g","subject":"Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-14T02:54:49Z","receivedAt":"2026-11-14T02:54:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> This is a manual page, which means it has to cater to both audiences.\n> Unlike a tutorial or guide, we cannot say we target this audience\n> primarily and expect the other audience to figure things out\n> themselves.\n\nThe detached-head.adoc is still a part of a manual page for the\ncheckout command, but gitdetached-head.adoc can have its own\nmaterial.  It does not need to stay \"just include detached-head.adoc\nand be done with it\" documentation at all.\n\n> Perhaps a FAQ or \"survival guide\" that targets these inexperienced\n> users would help?  Unlike manual pages, guides have more freedom in\n> choosing the material covered and the order in which they are\n> presented.  I dunno.\n\nSo the rest of the gitdetached-head.adoc, other than the \"include\ndetached-head.adoc\" line, can be the \"survival guide\" document, if\nwe wanted it to.\n\n\n"},{"id":"558553","messageId":"pull.2250.v7.git.1794843180501.gitgitgadget@gmail.com","threadId":"66484","inReplyTo":"pull.2250.git.1791384721919.gitgitgadget@gmail.com","subject":"[PATCH v7] doc: add new detached HEAD state guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-11-16T15:33:00Z","receivedAt":"2026-11-16T15:33:00Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nAdd a new guide (`git help detached-head`) to help users who\naccidentally end up in detached HEAD state without understanding why.\nMake it dual-purpose so that it can also be used as the DETACHED HEAD\nsection in `git-checkout.adoc`. The result is a shorter guide that\ncovers more material than the previous section.\n\nThis fixes the following issues with the current DETACHED HEAD section:\n\n- Says detached HEAD state is useful but doesn't explain why\n- Takes many paragraphs before explaining what detached HEAD state is\n- It's common for users to accidentally end up in detached HEAD state,\n  but it doesn't explain why that might happen\n- One of the UI improvements in `git switch` is to make it harder\n  to detach accidentally, but that isn't advertised.\n  See 7968bef06b (switch: only allow explicit detached HEAD, 2019-03-29)\n- Too many confusing diagrams\n\nTo help users who end up in detached HEAD state by accident, explain\nthe following, making all the explanations dual-purpose so they also\nwork in the context of `git-checkout.adoc`.\n\n1. What detached HEAD state is\n2. What the risks of detached HEAD state are, to help show folks that\n   the risks are pretty limited and there's no need to be afraid\n3. How you might end up there accidentally (or on purpose)\n4. How to avoid entering detached HEAD state accidentally by using\n   `git switch`\n5. The options for getting out of detached HEAD state\n\nThe framing that \"Git considers commits that aren't on a branch/other\nreference to be garbage\" is taken from Steve Klabnik's tutorial\nhttps://steveklabnik.github.io/jujutsu-tutorial/branching-merging-and-conflicts/anonymous-branches.html.\nIt's funny and it's consistent with the way Git uses the term\n\"garbage collection\".\n\nCo-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n    doc: checkout: rewrite detached HEAD state explanation\n    \n    This is a pretty quick rewrite where we didn't get any user feedback. If\n    we really want to make sure it's clear to users as possible, we should\n    IMO do a second stage later where we ask users which parts are unclear.\n    \n    Changes in v2:\n    \n     * Make the meson.build and Makefile changes (thanks to Kristoffer)\n     * Rename to gitdata-model (thanks to Kristoffer)\n     * Mention commits will be deleted after 90 days to make it seem less\n       scary (thanks to Kristoffer)\n     * Add an \"easily\" qualifier to \"it lets you look at an old version of\n       your code\", to avoid implying that this is the only way (thanks to\n       Junio)\n     * Mention that Git will warn you when switching branches if you're\n       leaving commits behind (thanks to Junio)\n     * Remove \"unintentionally\" (thanks to Junio)\n     * Mention git help datamodel (thanks to Junio)\n    \n    Changes in v3:\n    \n    I went through the style comments from v1.\n    \n    content changes:\n    \n     * Change \"90 days\" to \"30 days\" (thanks to Junio)\n     * Say that HEAD is where Git stores your \"current branch or commit\" to\n       make the first sentence read better (thanks to Junio)\n     * Mention git switch --detach a little earlier (thanks to Kristoffer)\n     * Replace \"the only problem\" with \"it's important to know that\" (thanks\n       to Junio)\n    \n    formatting changes etc:\n    \n     * Replace help detachedhead with help detached-head (thanks to Junio)\n     * Fix spacing in command-list.txt (thanks to Junio)\n     * Get Marie's signoff (thanks to Junio)\n    \n    non-changes: Left these phrases alone because I don't think the proposed\n    changes would make it more clear.\n    \n     * \"3 main ways you can end up in detached HEAD state\"\n     * \"to look at an old version of your code\"\n     * \"avoid accidentally ending up\"\n    \n    Changes in v4:\n    \n     * Fix commit message in example: \"fix bug\", not \"3\" (thanks to Junio)\n     * \"commit for that tag\" -> \"tagged commit\" (thanks to Junio)\n     * Move \"git checkout COMMIT_ID or git switch --detach COMMIT_ID\" down\n       to the \"3 main ways\" list to reduce duplication (thanks to Junio)\n     * Add some examples and be clearer about how detached HEAD state lets\n       you check out an old version of the project. (thanks to Junio)\n    \n    Changes in v5:\n    \n     * Explain HEAD's relationship to the current commit to make it feel\n       more uniform (thanks to Junio)\n     * Add a note about the benefits of detaching HEAD (thanks to Junio &\n       Ben)\n     * Change \"HEAD can either be a commit ID or a branch name\"\n    \n    Changes in v6:\n    \n     * Adjust some wording around \"stores\" (thanks to Junio)\n     * Change the quote style in advice.c (thanks to Junio)\n     * Update expected output in t2020-checkout-detach.sh (thanks to Junio)\n    \n    Changes in v7:\n    \n     * Add \"You can also use this to make experimental commits without being\n       on a branch.\"\n     * Update the commit message to explain that the goal is to help users\n       who get into detached HEAD state accidentally, and how the guide is\n       written to serve two purposes at the same time.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2250%2Fjvns%2Fdetached-head-v7\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2250/jvns/detached-head-v7\nPull-Request: https://github.com/gitgitgadget/git/pull/2250\n\nRange-diff vs v6:\n\n 1:  64f50b8248 ! 1:  020aac7cc4 doc: checkout: rewrite detached HEAD state explanation\n     @@ Metadata\n      Author: Julia Evans <julia@jvns.ca>\n      \n       ## Commit message ##\n     -    doc: checkout: rewrite detached HEAD state explanation\n     +    doc: add new detached HEAD state guide\n      \n     -    The current explanation has the following issues:\n     +    Add a new guide (`git help detached-head`) to help users who\n     +    accidentally end up in detached HEAD state without understanding why.\n     +    Make it dual-purpose so that it can also be used as the DETACHED HEAD\n     +    section in `git-checkout.adoc`. The result is a shorter guide that\n     +    covers more material than the previous section.\n     +\n     +    This fixes the following issues with the current DETACHED HEAD section:\n      \n          - Says detached HEAD state is useful but doesn't explain why\n          - Takes many paragraphs before explaining what detached HEAD state is\n     @@ Commit message\n            See 7968bef06b (switch: only allow explicit detached HEAD, 2019-03-29)\n          - Too many confusing diagrams\n      \n     -    Write a new explanation addressing these issues, and put it in a\n     -    standalone guide so that we can easily reference it from advice\n     -    (\"see `git help detached-head`\").\n     -    The result is a shorter guide that covers more material.\n     +    To help users who end up in detached HEAD state by accident, explain\n     +    the following, making all the explanations dual-purpose so they also\n     +    work in the context of `git-checkout.adoc`.\n     +\n     +    1. What detached HEAD state is\n     +    2. What the risks of detached HEAD state are, to help show folks that\n     +       the risks are pretty limited and there's no need to be afraid\n     +    3. How you might end up there accidentally (or on purpose)\n     +    4. How to avoid entering detached HEAD state accidentally by using\n     +       `git switch`\n     +    5. The options for getting out of detached HEAD state\n      \n          The framing that \"Git considers commits that aren't on a branch/other\n          reference to be garbage\" is taken from Steve Klabnik's tutorial\n     @@ Documentation/detached-head.adoc (new)\n      +it lets you easily check out an old version of your project. For\n      +example, a data scientist could use this to run an old version of a\n      +data pipeline or a programmer could use this to figure out when a bug\n     -+was introduced. By detaching `HEAD`, you don't need to create a\n     -+temporary branch.\n     ++was introduced. You can also use this to make experimental commits\n     ++without being on a branch. By detaching `HEAD`, you don't need to create\n     ++a temporary branch.\n      +\n      +But it's important to know that if you create new commits while in\n      +detached HEAD state, those commits won't be on a branch. This makes\n\n\n Documentation/Makefile              |   1 +\n Documentation/detached-head.adoc    |  65 ++++++++++++++\n Documentation/git-checkout.adoc     | 129 +---------------------------\n Documentation/gitdetached-head.adoc |  14 +++\n Documentation/meson.build           |   1 +\n advice.c                            |   1 +\n command-list.txt                    |   1 +\n t/t2020-checkout-detach.sh          |   2 +\n 8 files changed, 86 insertions(+), 128 deletions(-)\n create mode 100644 Documentation/detached-head.adoc\n create mode 100644 Documentation/gitdetached-head.adoc\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f8dea4b395..5892f48b06 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -54,6 +54,7 @@ MAN7_TXT += gitcore-tutorial.adoc\n MAN7_TXT += gitcredentials.adoc\n MAN7_TXT += gitcvs-migration.adoc\n MAN7_TXT += gitdatamodel.adoc\n+MAN7_TXT += gitdetached-head.adoc\n MAN7_TXT += gitdiffcore.adoc\n MAN7_TXT += giteveryday.adoc\n MAN7_TXT += gitfaq.adoc\ndiff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc\nnew file mode 100644\nindex 0000000000..36fa422753\n--- /dev/null\n+++ b/Documentation/detached-head.adoc\n@@ -0,0 +1,65 @@\n+In Git, you can always use `HEAD` to refer to the commit you have\n+checked out. But `HEAD` is also where Git stores the name of your\n+current branch. Internally in Git, `HEAD` can store either:\n+\n+1. A branch name, which is your current branch.\n+   The commit you have checked out is the latest commit on that branch.\n+2. A commit ID, when you don't have a current branch.\n+   This is called \"detached HEAD state\".\n+\n+It can sometimes be useful for `HEAD` to be a commit ID, because\n+it lets you easily check out an old version of your project. For\n+example, a data scientist could use this to run an old version of a\n+data pipeline or a programmer could use this to figure out when a bug\n+was introduced. You can also use this to make experimental commits\n+without being on a branch. By detaching `HEAD`, you don't need to create\n+a temporary branch.\n+\n+But it's important to know that if you create new commits while in\n+detached HEAD state, those commits won't be on a branch. This makes\n+those new commits much harder to find later. Also, Git considers commits\n+that aren't on any branch (or a tag or other reference) to be garbage.\n+Git will eventually permanently delete those \"garbage\" commits during\n+garbage collection. Those commits will be deleted after 30 days by\n+default, see linkgit:git-gc[1] for more.\n+\n+There are 3 main ways you can end up in detached HEAD state:\n+\n+1. `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`,\n+   where `COMMIT_ID` is a commit ID.\n+2. `git checkout v1.3`, where v1.3 is a tag name\n+3. `git checkout origin/main`, where `origin/main` is\n+   a remote-tracking branch\n+\n+Checking out a tag puts you in detached HEAD state because `HEAD` can\n+only be a branch or a commit, not a tag or any other reference.\n+So `git checkout TAG` will set HEAD to the tagged commit.\n+\n+The easiest way to avoid accidentally ending up in detached HEAD state\n+is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to\n+switch branches. `git switch` won't let you detach unless you explicitly\n+pass the `--detach` argument.\n+\n+To get back onto a branch, you can:\n+\n+1. Switch to the branch you want to be on, with `git switch BRANCHNAME`.\n+2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`.\n+   You might want to do this if you've created new commits, so that you can\n+   find the commit later and so that it won't be garbage collected.\n+\n+If you switch branches after making commits in detached HEAD state, Git\n+will warn you that you might be about to \"lose\" those commits and print\n+out the commit ID. You can also always find those commits later using\n+linkgit:git-reflog[1].\n+\n+Here's what that warning looks like:\n+\n+-------------------------\n+Warning: you are leaving 1 commit behind, not connected to\n+any of your branches:\n+\n+  48c09f6 fix bug\n+-------------------------\n+\n+For a more in-depth explanation of how `HEAD` works in Git,\n+see linkgit:gitdatamodel[7] (`git help datamodel`).\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 2aefea0228..4e9e94e24d 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -376,135 +376,8 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n [[DETACHED_HEAD]]\n DETACHED HEAD\n -------------\n-`HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each\n-branch refers to a specific commit. Let's look at a repo with three\n-commits, one of them tagged, and with branch `master` checked out:\n \n-------------\n-           HEAD (refers to branch 'master')\n-            |\n-            v\n-a---b---c  branch 'master' (refers to commit 'c')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-When a commit is created in this state, the branch is updated to refer to\n-the new commit. Specifically, `git commit` creates a new commit `d`, whose\n-parent is commit `c`, and then updates branch `master` to refer to new\n-commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers\n-to commit `d`:\n-\n-------------\n-$ edit; git add; git commit\n-\n-               HEAD (refers to branch 'master')\n-                |\n-                v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is sometimes useful to be able to checkout a commit that is not at\n-the tip of any named branch, or even to create a new commit that is not\n-referenced by a named branch. Let's look at what happens when we\n-checkout commit `b` (here we show two ways this may be done):\n-\n-------------\n-$ git checkout v2.0  # or\n-$ git checkout master^^\n-\n-   HEAD (refers to commit 'b')\n-    |\n-    v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-Notice that regardless of which checkout command we use, `HEAD` now refers\n-directly to commit `b`. This is known as being in detached `HEAD` state.\n-It means simply that `HEAD` refers to a specific commit, as opposed to\n-referring to a named branch. Let's see what happens when we create a commit:\n-\n-------------\n-$ edit; git add; git commit\n-\n-     HEAD (refers to commit 'e')\n-      |\n-      v\n-      e\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-There is now a new commit `e`, but it is referenced only by `HEAD`. We can\n-of course add yet another commit in this state:\n-\n-------------\n-$ edit; git add; git commit\n-\n-\t HEAD (refers to commit 'f')\n-\t  |\n-\t  v\n-      e---f\n-     /\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-In fact, we can perform all the normal Git operations. But, let's look\n-at what happens when we then checkout `master`:\n-\n-------------\n-$ git checkout master\n-\n-               HEAD (refers to branch 'master')\n-      e---f     |\n-     /          v\n-a---b---c---d  branch 'master' (refers to commit 'd')\n-    ^\n-    |\n-  tag 'v2.0' (refers to commit 'b')\n-------------\n-\n-It is important to realize that at this point nothing refers to commit\n-`f`. Eventually commit `f` (and by extension commit `e`) will be deleted\n-by the routine Git garbage collection process, unless we create a reference\n-before that happens. If we have not yet moved away from commit `f`,\n-any of these will create a reference to it:\n-\n-------------\n-$ git checkout -b foo  # or \"git switch -c foo\"  <1>\n-$ git branch foo                                 <2>\n-$ git tag foo                                    <3>\n-------------\n-<1> creates a new branch `foo`, which refers to commit `f`, and then\n-    updates `HEAD` to refer to branch `foo`. In other words, we'll no longer\n-    be in detached `HEAD` state after this command.\n-<2> similarly creates a new branch `foo`, which refers to commit `f`,\n-    but leaves `HEAD` detached.\n-<3> creates a new tag `foo`, which refers to commit `f`,\n-    leaving `HEAD` detached.\n-\n-If we have moved away from commit `f`, then we must first recover its object\n-name (typically by using git reflog), and then we can create a reference to\n-it. For example, to see the last two commits to which `HEAD` referred, we\n-can use either of these commands:\n-\n-------------\n-$ git reflog -2 HEAD # or\n-$ git log -g -2 HEAD\n-------------\n+include::detached-head.adoc[]\n \n [[ARGUMENT_DISAMBIGUATION]]\n ARGUMENT DISAMBIGUATION\ndiff --git a/Documentation/gitdetached-head.adoc b/Documentation/gitdetached-head.adoc\nnew file mode 100644\nindex 0000000000..a477060db2\n--- /dev/null\n+++ b/Documentation/gitdetached-head.adoc\n@@ -0,0 +1,14 @@\n+gitdetached-head(7)\n+===================\n+\n+NAME\n+----\n+gitdetached-head - How detached HEAD state works\n+\n+DESCRIPTION\n+-----------\n+include::detached-head.adoc[]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex cfa9c67609..6b3141647f 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -197,6 +197,7 @@ manpages = {\n   'gitcredentials.adoc' : 7,\n   'gitcvs-migration.adoc' : 7,\n   'gitdatamodel.adoc' : 7,\n+  'gitdetached-head.adoc' : 7,\n   'gitdiffcore.adoc' : 7,\n   'giteveryday.adoc' : 7,\n   'gitfaq.adoc' : 7,\ndiff --git a/advice.c b/advice.c\nindex 401d047391..3238e9b866 100644\n--- a/advice.c\n+++ b/advice.c\n@@ -291,6 +291,7 @@ void detach_advice(const char *new_name)\n \t\"\\n\"\n \t\"  git switch -\\n\"\n \t\"\\n\"\n+\t\"Run 'git help detached-head' to learn more.\\n\"\n \t\"Turn off this advice by setting config variable advice.detachedHead to false\\n\\n\");\n \n \tfprintf(stderr, fmt, new_name);\ndiff --git a/command-list.txt b/command-list.txt\nindex 63ae2a67c9..7fb57765fb 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -218,6 +218,7 @@ gitcore-tutorial                        guide\n gitcredentials                          guide\n gitcvs-migration                        guide\n gitdatamodel                            guide\n+gitdetached-head                        guide\n gitdiffcore                             guide\n giteveryday                             guide\n gitfaq                                  guide\ndiff --git a/t/t2020-checkout-detach.sh b/t/t2020-checkout-detach.sh\nindex 28bbbe6c05..b0bfd3191c 100755\n--- a/t/t2020-checkout-detach.sh\n+++ b/t/t2020-checkout-detach.sh\n@@ -228,6 +228,7 @@ test_expect_success 'describe_detached_head prints no SHA-1 ellipsis when not as\n \n \t  git switch -\n \n+\tRun 'git help detached-head' to learn more.\n \tTurn off this advice by setting config variable advice.detachedHead to false\n \n \tHEAD is now at \\$commit three\n@@ -310,6 +311,7 @@ test_expect_success 'describe_detached_head does print SHA-1 ellipsis when asked\n \n \t  git switch -\n \n+\tRun 'git help detached-head' to learn more.\n \tTurn off this advice by setting config variable advice.detachedHead to false\n \n \tHEAD is now at \\$commit... three\n\nbase-commit: 5a7d1e8045ce66c908f62598e26cbb8df7b39a90\n-- \ngitgitgadget\n\n"},{"id":"558577","messageId":"xmqqik1wjuoo.fsf@gitster.g","threadId":"66484","inReplyTo":"pull.2250.v7.git.1794843180501.gitgitgadget@gmail.com","subject":"Re: [PATCH v7] doc: add new detached HEAD state guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-16T22:08:39Z","receivedAt":"2026-11-16T22:08:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n>  1:  64f50b8248 ! 1:  020aac7cc4 doc: checkout: rewrite detached HEAD state explanation\n>      @@ Metadata\n>       Author: Julia Evans <julia@jvns.ca>\n>       \n>        ## Commit message ##\n>      -    doc: checkout: rewrite detached HEAD state explanation\n>      +    doc: add new detached HEAD state guide\n>       \n>      -    The current explanation has the following issues:\n>      +    Add a new guide (`git help detached-head`) to help users who\n>      +    accidentally end up in detached HEAD state without understanding why.\n>      +    Make it dual-purpose so that it can also be used as the DETACHED HEAD\n>      +    section in `git-checkout.adoc`. The result is a shorter guide that\n>      +    covers more material than the previous section.\n>      +\n>      +    This fixes the following issues with the current DETACHED HEAD section:\n\nThis makes it clearer what we are doing with this change.\n\n>       +it lets you easily check out an old version of your project. For\n>       +example, a data scientist could use this to run an old version of a\n>       +data pipeline or a programmer could use this to figure out when a bug\n>      -+was introduced. By detaching `HEAD`, you don't need to create a\n>      -+temporary branch.\n>      ++was introduced. You can also use this to make experimental commits\n>      ++without being on a branch. By detaching `HEAD`, you don't need to create\n>      ++a temporary branch.\n>       +\n>       +But it's important to know that if you create new commits while in\n>       +detached HEAD state, those commits won't be on a branch. This makes\n\nI've stared at this patch for too long that my eyes are\ncontaminated.  It would be great if somebody gave a hopefully final\npass with a fresh eye before we declare victory and merge it down to\n'next'.\n\nThanks.\n\n"}]}