Introduction

Une ref symbolique est une référence dont la valeur est un autre nom de ref plutôt qu'un hachage d'objet. L'exemple canonique est HEAD, qui contient généralement ref: refs/heads/main. Les refs symboliques permettent à Git de suivre « la branche courante » comme donnée, pas comme état.

Lire et écrire

git symbolic-ref HEAD
# refs/heads/main

git symbolic-ref refs/remotes/origin/HEAD
# refs/remotes/origin/main

git symbolic-ref HEAD refs/heads/feature/login   # changer sans checkout
git symbolic-ref --short HEAD                      # forme courte : main
git symbolic-ref --delete refs/remotes/origin/HEAD

HEAD comme ref symbolique

Quand vous commitez, Git résout HEAD pour trouver la branche courante et met à jour la pointe de cette branche. Quand HEAD est détaché, il cesse d'être symbolique et contient un SHA brut.

cat .git/HEAD
# ref: refs/heads/main         (symbolique)
# vs après détachement :
# a1b2c3d4...                  (brut)

HEAD distant

Chaque remote peut avoir un HEAD symbolique indiquant sa branche par défaut. Définir ou rafraîchir :

git remote set-head origin --auto       # interroger le serveur
git remote set-head origin main         # définir explicitement
git remote set-head origin --delete

C'est ce qui fait que git log origin résout vers origin/main.

Pourquoi les utiliser

• La « branche courante » peut changer sans réécrire l'historique.
• Les outils peuvent demander « quelle est la branche par défaut ? » sans coder en dur les noms.
• Les hooks peuvent cibler la branche actuellement extraite de manière générique.

Worktrees et HEAD par worktree

Chaque worktree lié (git worktree add) a son propre HEAD, stocké sous .git/worktrees/<name>/HEAD. Chacun peut pointer vers une branche différente :

git worktree add ../wt-feature feature/login
cat ../wt-feature/.git
# gitdir: /path/to/main/.git/worktrees/wt-feature
cat .git/worktrees/wt-feature/HEAD
# ref: refs/heads/feature/login

Détection

git symbolic-ref -q HEAD && echo "sur une branche" || echo "détaché"

Renommer la branche par défaut

Pour renommer master en main en sécurité :

git branch -m master main
git symbolic-ref HEAD refs/heads/main
git push -u origin main
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main

Inspecter la résolution symbolique

git rev-parse résout un nom à travers les refs symboliques jusqu'à un SHA, tandis que git symbolic-ref ne suit qu'un niveau. La paire est utile pour les scripts :

git symbolic-ref HEAD                       # refs/heads/main
git symbolic-ref --short HEAD               # main
git rev-parse HEAD                          # SHA
git rev-parse --symbolic-full-name HEAD     # refs/heads/main
git rev-parse --symbolic-full-name @{u}     # refs/remotes/origin/main

Utilisez --symbolic-full-name quand vous voulez le nom de ref canonique peu importe le raccourci tapé par l'utilisateur.

Erreurs fréquentes

Éditer .git/HEAD à la main et oublier le saut de ligne final, laissant Git incapable de l'analyser. Utilisez git symbolic-ref. Traiter refs/remotes/origin/HEAD comme faisant autorité alors qu'il est en réalité mis en cache ; rafraîchissez avec git remote set-head origin --auto. Confondre une ref symbolique pointant vers une branche manquante avec une vraie erreur ; git symbolic-ref -q sort avec un code non nul, que les scripts peuvent gérer. Enfin, supprimer la ref sous-jacente sans mettre à jour la symbolique, laissant un symref pendant ; les outils peuvent le signaler mais c'est inoffensif et facile à corriger avec un autre symbolic-ref.