Re: [PATCH v2] doc: checkout: rewrite detached HEAD state explanation
- From
Julia Evans <julia@jvns.ca>
- Date
- Oct 14, 2026, 21:10 UTC
- Message-ID
- <18556e31-d85b-4b28-b01f-91ae99cbe9cc@app.fastmail.com>
- In-Reply-To
- <xmqqecdsru6l.fsf@gitster.g>
On Wed, Oct 14, 2026, at 2:52 PM, Junio C Hamano wrote:
Show 7 quoted lines
> "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?Will fix.
>> 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?
Will do.
Show 5 quoted lines
>> +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.
Show 15 quoted lines
> 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.
Show 11 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.
Will do.
Show 17 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.
Will do.