Sur la liste de diffusion officielle de Git, un patch signé Julia Evans a été soumis pour refondre la documentation sur l'état « detached HEAD ». L'auteur pointe du doigt l'ancienne explication : elle mettait des paragraphes avant de définir le terme, omettait de expliquer pourquoi on pouvait se retrouver dans cet état par erreur, et surchargeait le texte de schémas confus.

Le patch introduit un nouveau document autonome, `detached-head.adoc`, accessible via la commande `git help detachedhead`. Ce guide explique que HEAD peut être soit une branche, soit un identifiant de commit. Lorsqu'il s'agit d'un commit isolé, on parle de « HEAD détaché ». L'intérêt ? Consulter un ancien état du code sans obligatoirement être sur une branche.

Le problème, rappelle le document, c'est que les commits créés en mode détaché ne sont pas rattachés à une branche. Git les considère alors comme des rebuts et les supprime définitivement lors du nettoyage automatique. Le patch liste trois façons de tomber dans le piège : `git checkout` avec un commit, une étiquette (tag) ou une branche distante.

Pour y échapper, Julia Evans recommande d'utiliser `git switch` à la place de `git checkout`. Cette commande, introduite récemment, exige un argument `--detach` explicite pour autoriser la séparation de HEAD. Pour retrouver une branche, il suffit de faire `git switch BRANCH` ou `git switch -c BRANCH`.

Le patch est accompagné d'une note d'humour : l'idée que Git traite les commits orphelins comme des « poubelles » provient du tuto de Steve Klabnik, où le terme « garbage » est utilisé de façon cohérente avec la terminologie interne de Git. Un petit clin d'œil bienveillant dans un monde de documentation souvent austère.