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

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

From
Junio C Hamano <gitster@pobox.com>
Date
Oct 14, 2026, 18:52 UTC
Message-ID
<xmqqecdsru6l.fsf@gitster.g>
In-Reply-To
<pull.2250.v2.git.1791896486100.gitgitgadget@gmail.com>
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> Write a new explanation addressing these issues, and put it in a
> standalone guide so that we can easily reference it from advice
> ("see `git help detachedhead`").
Isn't it 'git help detached-head' in this edition?
> Co-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
> Signed-off-by: Julia Evans <julia@jvns.ca>
Can the other author also sign it off?
> +Git will eventually permanently delete those "garbage" commits during
> +garbage collection. Those commits will be deleted after 90 days by
> +default, see linkgit:git-gc[1] for more.
Does this say 90 days because that is the gc.reflogExpire retention?

If you create a commit, change your mind, rewind the tip of the branch (e.g., with "git commit --amend"), and then keep working, the original commit before amending would be unreachable from the tip of that branch. Its reflog entry would then expire after gc.reflogExpireUnreachable, which defaults to 30 days. If your commit were created on a detached HEAD, I am not sure offhand how the thresholds for gc.reflogExpire and gc.reflogExpireUnreachable come into play for HEAD, as HEAD by default flips back and forth regularly across branch tips that are not reachable from each other. When "gc" kicks in, the commit HEAD currently points to is unlikely to reach the abandoned commit.

It might be safer to either say "after 30 days by default" or generalize it to "after a few weeks by default" to avoid being overly prescriptive.

Show 9 quoted lines
> diff --git a/advice.c b/advice.c
> index 401d047391..43f86c2eaf 100644
> --- a/advice.c
> +++ b/advice.c
> @@ -291,6 +291,7 @@ void detach_advice(const char *new_name)
>  	"\n"
>  	"  git switch -\n"
>  	"\n"
> +	"Run `git help detachedhead` to learn more.\n"
"git help deatched-head" here, too.
Show 13 quoted lines
>  	fprintf(stderr, fmt, new_name);
> diff --git a/command-list.txt b/command-list.txt
> index 63ae2a67c9..922a1dbd84 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -218,6 +218,7 @@ gitcore-tutorial                        guide
>  gitcredentials                          guide
>  gitcvs-migration                        guide
>  gitdatamodel                            guide
> +gitdetached-head                         guide
>  gitdiffcore                             guide
>  giteveryday                             guide
>  gitfaq                                  guide

This seems to be manually aligned with SP, so compensate the addition of "-" between detached and head by removing one SP before guide on the same line.

Thanks.
Previous: Julia Evans via GitGitGadgetNext: Julia Evans
Message 14 of 53 in “doc: checkout: rewrite detached HEAD state explanation”
  1. doc: checkout: rewrite detached HEAD state explanationJulia Evans via GitGitGadget, Oct 7, 2026
  2. Junio C HamanoOct 7, 2026
  3. Julia EvansOct 13, 2026
  4. Julia EvansOct 19, 2026
  5. Junio C HamanoOct 19, 2026
  6. Julia EvansOct 20, 2026
  7. Julia EvansOct 20, 2026
  8. Kristoffer HaugsbakkOct 7, 2026
  9. Julia EvansOct 13, 2026
  10. Kristoffer HaugsbakkOct 13, 2026
  11. Julia EvansOct 13, 2026
  12. Julia EvansOct 13, 2026
  13. doc: checkout: rewrite detached HEAD state explanationJulia Evans via GitGitGadget, Oct 13, 2026
  14. Junio C HamanoOct 14, 2026
  15. Julia EvansOct 14, 2026
  16. doc: checkout: rewrite detached HEAD state explanationJulia Evans via GitGitGadget, Oct 15, 2026
  17. Junio C HamanoOct 15, 2026
  18. Julia EvansOct 16, 2026
  19. Junio C HamanoOct 16, 2026
  20. Julia EvansOct 16, 2026
  21. Junio C HamanoOct 16, 2026
  22. doc: checkout: rewrite detached HEAD state explanationJulia Evans via GitGitGadget, Oct 16, 2026
  23. Junio C HamanoOct 16, 2026
  24. D. Ben KnobleNov 7, 2026
  25. Junio C HamanoNov 8, 2026
  26. Julia EvansNov 9, 2026
  27. Junio C HamanoNov 10, 2026
  28. Julia EvansNov 10, 2026
  29. Julia EvansNov 11, 2026
  30. Ben KnobleNov 12, 2026
  31. Junio C HamanoNov 12, 2026
  32. Julia EvansNov 12, 2026
  33. Junio C HamanoNov 12, 2026
  34. Julia EvansNov 12, 2026
  35. Junio C HamanoNov 13, 2026
  36. Julia EvansNov 13, 2026
  37. Junio C HamanoNov 13, 2026
  38. Julia EvansNov 13, 2026
  39. Julia EvansNov 13, 2026
  40. Junio C HamanoNov 14, 2026
  41. Julia EvansNov 14, 2026
  42. Julia EvansNov 13, 2026
  43. Junio C HamanoNov 13, 2026
  44. Julia EvansNov 13, 2026
  45. Junio C HamanoNov 14, 2026
  46. Junio C HamanoOct 16, 2026
  47. doc: checkout: rewrite detached HEAD state explanationJulia Evans via GitGitGadget, Nov 11, 2026
  48. Junio C HamanoNov 11, 2026
  49. Julia EvansNov 12, 2026
  50. Junio C HamanoNov 12, 2026
  51. doc: checkout: rewrite detached HEAD state explanationJulia Evans via GitGitGadget, Nov 12, 2026
  52. doc: add new detached HEAD state guideJulia Evans via GitGitGadget, Nov 16, 2026
  53. Junio C HamanoNov 16, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.