3.9 : git reflog : la boîte noire de Git

La commande qui change le rapport à Git

Beaucoup d’administrateurs manipulent Git avec une prudence excessive : ils recopient leur dossier avant chaque opération, évitent les commandes qu’ils ne maîtrisent pas, et travaillent avec la crainte diffuse de tout casser.

Cette leçon devrait mettre fin à cela.

Git conserve la trace de chacun de vos déplacements, y compris ceux que vous avez annulés, y compris les enregistrements qui n’appartiennent plus à aucune branche. Ce journal s’appelle le reflog, et il est actif par défaut, sans que vous ayez rien à configurer.

Il ne vous rendra pas tout. Mais il vous rendra bien plus que vous ne le croyez.


Ce que Git enregistre réellement

À chaque fois que la position de votre branche change — un enregistrement, une fusion, un changement de branche, un reset —, Git écrit une ligne dans un journal local.

git reflog
e5b1c93 HEAD@{0}: commit: Ajout du lecteur Q: pour la paie
7d2e881 HEAD@{1}: pull: Fast-forward
a3f9c21 HEAD@{2}: reset: moving to HEAD~2
b91c4f2 HEAD@{3}: commit: Correction du chemin de sauvegarde
f2a7e14 HEAD@{4}: commit: Ajout de SRV-BDD02 à l'inventaire
a3f9c21 HEAD@{5}: checkout: moving from test to main

Trois colonnes : l’empreinte, une référence de position, l’action réalisée.

La notation HEAD@{3} se lit « là où se trouvait HEAD il y a trois déplacements ». Elle s’utilise partout où Git attend un enregistrement.

Regardez la ligne HEAD@{2} : un reset a ramené la branche deux crans en arrière. Les enregistrements b91c4f2 et f2a7e14 n’appartiennent donc plus à aucune branche — ils sont invisibles dans git log.

Et pourtant ils sont là, dans le reflog, parfaitement récupérables.


Pourquoi ça fonctionne

Un point de modèle mental qui éclaire beaucoup de choses.

Git ne supprime jamais un enregistrement lorsque vous déplacez une branche. Il déplace simplement l’étiquette. L’enregistrement reste dans la base d’objets, il devient seulement inatteignable — plus aucune branche ne mène jusqu’à lui.

   AVANT le reset                   APRÈS le reset

   a3f9c21 ── b91c4f2 ── f2a7e14    a3f9c21     b91c4f2 ── f2a7e14
                            ▲          ▲              (orphelins,
                          main       main           mais toujours là)

Un ramasse-miettes finit par nettoyer ces objets orphelins, mais pas immédiatement : les valeurs par défaut sont d’environ 90 jours pour les enregistrements encore atteignables, et 30 jours pour les orphelins.

Vous disposez donc, dans la pratique, de plusieurs semaines pour récupérer une manipulation malheureuse.


La méthode de récupération

Toujours la même, en trois temps.

1. Retrouver le point de départ

git reflog

Cherchez la ligne correspondant à l’état d’avant la bêtise. Les descriptions aident : commit:, pull:, reset: moving to, checkout: moving from.

2. Vérifier avant d’agir

git show HEAD@{3}
git log --oneline HEAD@{3} -5

Ne sautez pas cette étape. Vous vous apprêtez à déplacer votre branche : autant être certain de la destination.

3. Récupérer

Deux façons, et je vous recommande vivement la première.

La méthode sûre — créer une branche de secours :

git branch recuperation HEAD@{3}

Vous créez une étiquette sur l’ancien état. Rien d’autre ne bouge : votre branche courante, vos fichiers, tout reste en place. Vous pouvez ensuite examiner tranquillement, récupérer ce qui vous intéresse, puis supprimer la branche de secours.

La méthode directe — y ramener la branche :

git reset --hard HEAD@{3}

Efficace, mais c’est un reset --hard : avec les mêmes précautions qu’en leçon 3.8.


Les quatre cas réels

« J’ai fait un reset --hard et j’ai perdu deux enregistrements »

git reflog
# repérer la ligne juste AVANT le reset
git branch recuperation HEAD@{1}
git log --oneline recuperation -5     # vérifier que tout est là

Vos enregistrements sont sur la branche recuperation. Vous pouvez les fusionner, ou simplement y ramener main.

« J’ai supprimé une branche par erreur »

git reflog

Cherchez la dernière ligne mentionnant cette branche.

9c3f81a HEAD@{7}: checkout: moving from correction-gpo to main

9c3f81a était le sommet de la branche. Recréez-la :

git branch correction-gpo 9c3f81a

Elle est de retour, avec tout son contenu.

Variante utile : git reflog show <nom-de-branche> affiche l’historique des déplacements d’une branche précise, ce qui est parfois plus lisible que le reflog de HEAD.

« Mon --amend a écrasé le bon enregistrement »

Souvenez-vous de la leçon 3.3 : --amend ne modifie pas un enregistrement, il en crée un nouveau. L’ancien existe toujours.

git reflog
# la ligne « commit (amend): » — celle juste avant contient l'original
git show HEAD@{1}

« Un pull a produit quelque chose que je ne comprends pas »

git reflog
git reset --hard HEAD@{1}     # revenir à l'état d'avant le pull

Vous retrouvez la situation exacte d’avant l’intégration, et vous pouvez recommencer calmement — en appliquant cette fois la méthode de la leçon 3.4 : fetch, regarder, puis intégrer.


Les limites, très concrètement

Le reflog est puissant, mais il faut connaître ses quatre frontières.

Il est strictement local. Il vit dans votre dossier .git. Il n’est ni publié sur la forge, ni partagé avec vos collègues. Le reflog de Nicolas ne vous aidera jamais, et réciproquement.

Un clone frais n’a pas de reflog. Si vous supprimez votre dossier de travail et que vous re-clonez, vous repartez de zéro : le journal des déplacements ne se transmet pas.

Il expire. Environ trente jours pour les enregistrements orphelins. Ce n’est pas une sauvegarde à long terme.

Il ne contient que ce qui a été enregistré. C’est la limite la plus importante, et nous l’avons déjà rencontrée en 3.8 : un fichier modifié mais jamais enregistré, effacé par git restore, n’est nulle part. Le reflog ne connaît que les enregistrements.

Ce qui donne tout son sens au conseil de la leçon 3.3 : enregistrez avant toute manipulation risquée. Dix secondes de git commit, et vous passez du côté récupérable de la frontière.


Quand le reflog ne suffit plus

Cas rare, mais bon à connaître : un enregistrement orphelin dont vous n’avez plus la trace dans le reflog — par exemple créé dans un état détaché puis abandonné.

git fsck --lost-found

Cette commande parcourt la base d’objets et signale tout ce qui n’est rattaché à rien :

dangling commit 4a7f2c9e1b3d5f8a0c2e4b6d8f0a2c4e6b8d0f2a

Vous pouvez alors l’examiner et le récupérer comme les autres :

git show 4a7f2c9
git branch recuperation 4a7f2c9

C’est la dernière cartouche. Elle fonctionne plus souvent qu’on ne le croit.


Les erreurs classiques

Symptôme Cause
git reflog ne montre rien d’utile Vous êtes dans un clone frais : le reflog ne se transmet pas
L’enregistrement cherché a disparu Plus de 30 jours : essayez git fsck --lost-found
Le travail perdu n’apparaît nulle part Il n’avait jamais été enregistré — irrécupérable
HEAD@{5} renvoie une erreur Le reflog est plus court que cela : vérifiez avec git reflog
Vous récupérez, mais la branche est bizarre Vous avez ramené la branche au lieu de créer une branche de secours

Ce qu’il faut retenir

  • Git journalise chaque déplacement de vos branches, localement et par défaut.
  • Un enregistrement « supprimé » devient seulement inatteignable — il reste dans la base plusieurs semaines.
  • La méthode : git reflog, vérifier avec git show, puis récupérer.
  • Créez une branche de secours (git branch recuperation HEAD@{n}) plutôt que de déplacer votre branche courante.
  • git reflog show <branche> cible les déplacements d’une branche précise.
  • Le reflog est local, non partagé, expire, et ne connaît que ce qui a été enregistré.
  • git fsck --lost-found est la dernière cartouche pour les objets orphelins.
  • Enregistrez avant toute manipulation risquée : c’est ce qui vous place du côté récupérable.

Dans la leçon suivante

Vous avez maintenant l’essentiel de Git en ligne de commande, et le filet de sécurité qui va avec.

La leçon 3.10 fait le tour des interfaces graphiques : celle que vous avez déjà dans VS Code, les clients dédiés, l’intégration dans l’explorateur Windows, et l’interface web de la forge. Nous verrons ce que chacune fait mieux que le terminal, ce qu’aucune ne remplacera, et pourquoi il était important de commencer par les commandes.

Ce sera aussi l’occasion de dire un mot du client que j’utilise personnellement au quotidien — parce qu’après avoir appris au terminal, il n’y a aucun mérite à s’en priver.