Si Git indique HEAD detached, vos fichiers sont toujours extraits à un commit précis, mais les nouveaux commits ne feront pas avancer de branche tant que vous n'en aurez pas créé une. Sur un Mac, ouvrez le Terminal, accédez au dépôt, vérifiez la présence de modifications non validées, puis associez votre travail actuel à une nouvelle branche ou revenez en toute sécurité à la branche que vous souhaitiez utiliser. La commande switch de Git prend en charge ces deux méthodes. Le guide d'Apple sur Terminal explique comment ouvrir Terminal ; la documentation de Git sur switch détaille le fonctionnement des branches et de l'état HEAD détaché.

1. Vérifier ce que Git a extrait

Ouvrez le Terminal depuis Applications > Utilitaires, puis accédez à votre dépôt. Remplacez le chemin d'exemple par le dossier où se trouve votre projet ; les guillemets permettent de gérer les espaces dans le chemin. Le Terminal de macOS utilise zsh par défaut, et ces commandes fonctionnent sous zsh ainsi que dans les shells courants.

cd "/path/to/your/repository"
git status

Si git status affiche « HEAD détachée » (HEAD detached) ou « n'est sur aucune branche » (not on any branch), vous êtes dans l'état HEAD détaché. Git a extrait directement un commit plutôt qu'une branche. Le commit et les fichiers de travail restent disponibles ; le risque est que les commits effectués ici ne soient pas automatiquement rattachés à une branche. Le manuel de checkout de Git décrit cet état et la manière dont une branche permet de préserver les commits qui y sont réalisés.

Avant de basculer où que ce soit, lisez le reste de git status. S'il liste des fichiers modifiés ou non suivis, il s'agit de modifications qui n'ont pas été validées (committées). Vous pouvez continuer à travailler sur place, ou créer une branche dès maintenant ; créer une branche sur le commit actuel ne supprime pas vos modifications. Évitez les options de force ou d'abandon pendant la récupération.

2. Conserver le travail actuel sur une branche

Si vous avez créé un commit en état détaché — ou si vous souhaitez continuer à travailler à partir de cet instantané exact — créez une branche là où vous vous trouvez actuellement :

git switch -c recovered-work
git status

Utilisez un nom de branche explicite à la place de recovered-work. Git crée la branche au niveau du commit actuel et bascule dessus, de sorte que les commits ultérieurs appartiendront à cette branche. Vérifiez que git status indique bien le nom de la branche désormais. C'est la solution de récupération la plus rapide lorsque l'instantané détaché correspond au travail que vous souhaitez conserver. Git documente switch -c comme la création et le basculement vers une branche.

Si vous avez des modifications non validées, elles restent généralement dans l'arbre de travail lorsque vous créez la branche. Exécutez git status ensuite pour vous assurer qu'elles sont toujours là. Si la commande refuse de s'exécuter car une branche portant ce nom existe déjà, choisissez un autre nom ; n'ajoutez pas -C, ce qui pourrait réinitialiser une branche existante vers un nouveau point de départ.

3. Revenir à la branche que vous aviez l'intention d'utiliser

Si vous avez seulement inspecté un commit et n'avez aucune modification à préserver, basculez vers la branche souhaitée en utilisant son nom. Par exemple :

git switch main

Utilisez le nom réel de la branche de votre dépôt s'il ne s'agit pas de main. Si Git indique que des modifications locales seraient écrasées, arrêtez-vous et préservez-les d'abord : créez une branche de récupération comme indiqué ci-dessus, ou committez votre travail. Git bloque normalement le changement de branche lorsqu'il risque de faire perdre des modifications locales ; évitez --discard-changes pendant la récupération, car cette commande réinitialise l'index et l'arbre de travail pour correspondre à la branche cible. Le manuel de git switch explique ces sécurités et options.

Si vous venez de quitter une branche par erreur, git switch - permet de revenir à la branche ou au commit précédent enregistré par l'historique récent de basculement de Git. Vérifiez git status après le basculement pour confirmer où vous vous trouvez.

4. Retrouver un commit détaché quitté plus tôt

Si vous avez déjà changé de branche et ne savez plus où se trouve votre commit détaché, inspectez le reflog local :

git reflog

Le reflog enregistre les mises à jour récentes des références locales, et le reflog de HEAD enregistre également les changements de branche. Cherchez une entrée dont le message de commit ou l'horodatage correspond à votre travail. Pour inspecter un commit potentiel sans rien modifier, copiez son identifiant court depuis le reflog et exécutez :

git show --stat COMMIT_ID

Remplacez COMMIT_ID par l'identifiant réel — ne tapez pas l'espace réservé textuellement. S'il s'agit du bon commit, conservez-le en créant une branche sur ce commit :

git switch -c recovered-work COMMIT_ID

Cela rend le commit de nouveau accessible via une branche. Les reflogs sont des enregistrements locaux, et les entrées peuvent expirer ; la documentation de Git les décrit comme des historiques des récentes mises à jour de références et précise leurs règles d'expiration. Voir git reflog.

5. Vérifier avant de continuer

Exécutez git status et git log -1 --oneline pour confirmer la branche actuelle et le dernier commit. Si votre travail n'a pas été committé, vérifiez que ses fichiers apparaissent toujours dans la sortie du statut. Si aucun candidat n'apparaît dans le reflog, la récupération peut nécessiter l'examen des objets orphelins (dangling objects) ; c'est une étape distincte et plus minutieuse, et vous devez éviter d'exécuter des commandes de nettoyage comme git gc pendant vos recherches.

Un HEAD détaché ne signifie pas que votre travail a disparu. La bonne méthode de récupération dépend de votre situation : conserver le commit actuel, revenir à une branche existante ou retrouver un commit après avoir changé de branche. Une branche créée sur le bon commit donne à Git une référence nommée à suivre pour continuer votre travail.

Sources