Introduction

HEAD est la référence la plus importante dans Git. Il indique à Git de quel commit votre prochain commit descendra. La plupart du temps, HEAD pointe vers une branche, et cette branche pointe vers un commit ; mais HEAD peut aussi pointer directement vers un commit (HEAD détaché).

Où il vit

HEAD est un fichier unique à .git/HEAD. Inspectez-le :

cat .git/HEAD
# ref: refs/heads/main

Cette ligne unique dit « HEAD pointe actuellement sur la branche main ». Quand vous commitez, Git fait avancer main et HEAD suit.

Inspecter HEAD

git rev-parse HEAD              # SHA du commit
git symbolic-ref HEAD           # nom de la ref sous-jacente
git log -1 HEAD --oneline

HEAD détaché

Faire un checkout d'un commit, d'un tag ou d'une branche de tracking distant directement met HEAD en état détaché :

git checkout v1.2.3
# You are in 'detached HEAD' state.

.git/HEAD contient maintenant un SHA brut. Les nouveaux commits ne vont nulle part sauf dans le reflog ; revenez à une vraie branche (ou créez-en une) avant de les perdre :

git switch -c experiment

Raccourcis HEAD

• HEAD : le commit courant.
• HEAD^ ou HEAD~1 : parent.
• HEAD~3 : trois commits en arrière via le premier parent.
• HEAD^2 : second parent d'un merge commit.
• HEAD@{1} : position précédente depuis le reflog.

git log HEAD~5..HEAD --oneline
git diff HEAD^ HEAD

Autres HEAD spéciaux

• ORIG_HEAD : HEAD précédent avant une opération « dangereuse » (merge, reset).
• MERGE_HEAD : pointe de la branche en cours de merge.
• FETCH_HEAD : pointe de ce qui vient d'être fetché.
• CHERRY_PICK_HEAD : commit en cours de cherry-pick.

HEAD dans les scripts

Les scripts ont souvent besoin de connaître le nom de la branche courante. Utilisez la plomberie plutôt que de parser la sortie porcelain :

branch=$(git symbolic-ref --short -q HEAD) || branch="(detached)"
sha=$(git rev-parse HEAD)
short=$(git rev-parse --short HEAD)

symbolic-ref --short -q HEAD sort avec un code non nul en état détaché, ce qui en fait un détecteur parfait. git branch --show-current (Git 2.22+) est une alternative plus conviviale qui affiche une sortie vide en état détaché. Les deux sont stables entre versions ; la sortie de git status ne l'est pas.

HEAD et worktrees

Les worktrees liés ont chacun leur propre HEAD. Le .git/HEAD du dépôt principal est l'un de plusieurs ; chaque worktree a le sien sous .git/worktrees/<name>/HEAD. Cela signifie que deux worktrees du même dépôt peuvent être sur des branches différentes simultanément :

git worktree add ../wt-feature feature/login
git -C ../wt-feature rev-parse HEAD
git -C . rev-parse HEAD

Les deux HEADs sont indépendants. Le checkout de branche est exclusif entre worktrees : une branche ne peut être extraite que dans un worktree à la fois, ce qui empêche les éditions concurrentes accidentelles à la même branche depuis deux endroits.

Erreurs fréquentes

Croire que HEAD est synonyme de « branche courante ». Ce n'est pas le cas ; c'est un pointeur qui pointe généralement vers une. Traiter HEAD~3 et HEAD^3 comme équivalents : ils diffèrent sur les merge commits. Éditer .git/HEAD à la main pour changer de branche ; utilisez plutôt git switch ou git checkout. Et enfin, ignorer les avertissements « detached HEAD » et commiter dans le vide ; si vous vous y trouvez avec de nouveaux commits, faites git switch -c <newbranch> immédiatement pour les ancrer.