From: Julia Evans Date: Wed, 14 Oct 2026 21:10:40 GMT Subject: Re: [PATCH v2] doc: checkout: rewrite detached HEAD state explanation Message-ID: <18556e31-d85b-4b28-b01f-91ae99cbe9cc@app.fastmail.com> In-Reply-To: On Wed, Oct 14, 2026, at 2:52 PM, Junio C Hamano wrote: > "Julia Evans via GitGitGadget" 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? Will fix. >> Co-authored-by: Marie Claire LeBlanc Flanagan >> Signed-off-by: Julia Evans > > Can the other author also sign it off? Will do. >> +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? Yes, I wasn't sure how it works exactly. > 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. Will change to "30 days", I think "30 days" makes it a tiny bit easier for someone to figure out where that number might come from. >> 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. Will do. >> 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. Will do.