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

["Julia Evans" <julia@jvns.ca>]

On Wed, Oct 14, 2026, at 2:52 PM, Junio C Hamano wrote:
> "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.

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