HEAD détaché : naviguer sans branche

Un HEAD détaché signifie que vous n’êtes plus sur une branche. Git vous a positionné directement sur un commit. Tout commit que vous créez dans cet état risque d’être perdu si vous basculez sur une branche sans précaution. Ce guide explique pourquoi ça arrive et comment en sortir.

Prérequis : Les branches en bref.

Ce que vous allez apprendre

Comprendre l’état HEAD détaché et ce qu’il signifie concrètement
Savoir quand et pourquoi vous vous retrouvez en HEAD détaché
Récupérer des commits réalisés en HEAD détaché avant qu’ils disparaissent
Revenir sur une branche proprement après une exploration

Qu’est-ce que HEAD ?

En temps normal, HEAD pointe vers une branche, qui elle-même pointe vers un commit :

Mode normal :
HEAD → main → C5

Quand vous faites un commit, la branche avance et HEAD suit.

En mode détaché, HEAD pointe directement vers un commit, sans passer par une branche :

Mode détaché :
HEAD → C3    (main reste sur C5)

Vous voyez le code de C3, mais aucun nom de branche n’est associé à votre position.

Quand ça arrive

Plusieurs situations provoquent un HEAD détaché :

Commande	Raison
`git checkout abc1234`	Vous consultez un ancien commit
`git checkout v2.0.0`	Vous consultez un tag
`git rebase` (en cours)	Git rejoue les commits un par un
`git bisect`	Git navigue dans l’historique pour trouver un bug

Git vous avertit clairement :

Note: switching to 'abc1234'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

Explorer en mode détaché (sans risque)

Le HEAD détaché est parfait pour explorer l’historique :

# Consulter un ancien commit
git checkout abc1234

# Observer le code, exécuter les tests...
cat config.yaml
make test

# Revenir sur votre branche
git switch main

Tant que vous ne faites pas de commit, rien n’est perdu. Vous repartez simplement sur votre branche.

Le danger : commiter en mode détaché

Si vous créez des commits en HEAD détaché, ils ne sont rattachés à aucune branche :

           main
            ↓
C1 ← C2 ← C3 ← C4 ← C5

     HEAD → C6 ← C7  (orphelins !)
            ↑
         (branché depuis C2)

Si vous faites git switch main, les commits C6 et C7 deviennent orphelins : ils existent encore dans le dépôt mais aucune branche ne pointe vers eux. Au bout d’un certain temps, le garbage collector de Git les supprimera.

Sortir du HEAD détaché

Cas 1 : vous n’avez pas fait de commit

Retournez simplement sur votre branche :

git switch main

Cas 2 : vous avez fait des commits à conserver

Créez une branche sur votre position actuelle :
Fenêtre de terminal
```
git switch -c ma-decouverte
```
Les commits sont maintenant rattachés à ma-decouverte. Plus aucun risque de perte.

Vérifiez que la branche contient vos commits :

git log --oneline -5
git status
# Doit afficher "On branch ma-decouverte"

Mergez ou rebasez cette branche si nécessaire :
Fenêtre de terminal
```
git switch main
git merge ma-decouverte
```

Cas 3 : vous avez déjà quitté le HEAD détaché (commits orphelins)

Si vous avez basculé sur main sans créer de branche, les commits semblent perdus. Le reflog les retrouve :

Consultez le reflog :

git reflog

abc1234 HEAD@{0}: checkout: moving from abc1234 to main
def5678 HEAD@{1}: commit: Mon travail en détaché
ghi9012 HEAD@{2}: commit: Premier commit détaché

Créez une branche sur le dernier commit orphelin :
Fenêtre de terminal
```
git switch -c recuperation def5678
```
Vérifiez que tout est là :
Fenêtre de terminal
```
git log --oneline -5
```

Éviter le HEAD détaché par accident

Au lieu de…	Faites…
`git checkout abc1234`	`git log abc1234 --oneline -5` (consulter sans détacher)
`git checkout v2.0.0`	`git switch -c explore-v2 v2.0.0` (créer une branche directement)
Rien (après un bisect)	`git bisect reset` pour revenir à la branche

Dépannage : problèmes courants

Symptôme	Cause probable	Solution
`HEAD detached at abc1234`	Checkout sur un commit ou tag	`git switch main` ou `git switch -c ma-branche`
Commits disparus après switch	Commits orphelins	`git reflog` pour retrouver le hash, puis `git switch -c nom hash`
`git push` échoue en détaché	Pas de branche de tracking	Créez d’abord une branche avec `git switch -c`
Detached HEAD pendant rebase	Comportement normal de rebase	`git rebase --continue` ou `--abort`

À retenir

HEAD détaché = HEAD pointe directement sur un commit, sans branche
C’est normal et utile pour explorer l’historique ou tester du code ancien
Danger : les commits créés en mode détaché deviennent orphelins si vous changez de branche
git switch -c ma-branche crée une branche sur le commit actuel (la sortie sûre)
git reflog retrouve les commits orphelins pendant 90 jours
git switch main revient en mode normal sans risque (si pas de commit détaché)

Prochaines étapes

Cherry-pick Récupérez un commit spécifique sans merger.

Rebase fondamental Comprenez pourquoi le rebase provoque un HEAD détaché.

Consulter l'historique Explorez l'historique sans détacher HEAD.