Introduction

git log parcourt le graphe de commits depuis un point de départ (par défaut : HEAD) en remontant les parents, et affiche chaque commit. C'est l'outil principal pour explorer l'historique du projet.

Utilisation de base

git log
git log --oneline
git log --oneline --graph --decorate --all

La dernière forme est la vue couteau-suisse : un graphe compact de chaque branche avec les refs décorées.

Filtrer par date, auteur, message

git log --since="2 weeks ago"
git log --until=2025-01-01
git log --author="Ada"
git log --grep="bugfix"
git log -S "deprecated_function"   # pickaxe : quand une chaîne est-elle apparue ?

-S est précieux pour l'archéologie : il trouve les commits qui changent le nombre d'occurrences d'une chaîne dans un fichier.

Afficher les diffs

git log -p                 # patch complet par commit
git log --stat             # fichiers modifiés plus compteurs +/-
git log --shortstat        # ligne de résumé seulement
git log -p -- path/to/file # uniquement les commits touchant un chemin

Formats personnalisés

--pretty=format: accepte des espaces réservés. Un one-liner utile :

git log --pretty=format:"%h %an %ad %s" --date=short

%h hachage abrégé, %an nom de l'auteur, %ad date de l'auteur, %s sujet. Voir git help log pour la liste complète.

Limites et plages

git log -n 5                       # 5 derniers commits
git log main..feature              # commits sur feature, pas sur main
git log main...feature             # différence symétrique
git log feature ^main              # équivalent à main..feature

Suivre les renommages de fichiers

Git n'enregistre pas les renommages, il les détecte. Pour suivre l'historique à travers un renommage :

git log --follow -- path/to/file

Alias utiles

Quelques alias git log sont rentabilisés dès la première semaine. Deux particulièrement bons :

git config --global alias.lg "log --oneline --graph --decorate --all"
git config --global alias.last "log -1 HEAD --stat"
git config --global alias.recent "log --since='2 weeks ago' --author=$(git config user.email)"

git lg donne la vue d'ensemble du graphe ; git last montre ce qui vient de se passer ; git recent répond à « sur quoi ai-je travaillé récemment ? ». Ajoutez un alias pour toute invocation de log que vous tapez plus de deux fois.

Inverser et limiter

Par défaut, git log parcourt du plus récent au plus ancien. Parfois (notes de version, archéologie de code), vous voulez l'inverse, associé à un format propre :

git log --reverse --oneline v1.0.0..v1.1.0
git log --reverse --pretty=format:"* %s (%h)" v1.0.0..HEAD > CHANGELOG.draft

C'est aussi là que pickaxe et les filtres de chemin gagnent leur place : git log --reverse -S "old_api" -- src/ montre l'historique chronologique de l'apparition et de la disparition d'une chaîne, parfait pour tracer les dépréciations.

Erreurs fréquentes

Ne lire que l'historique de HEAD et manquer les commits sur d'autres branches ; passez --all pour les voir. Confondre --author (une regex sur le champ auteur) avec une correspondance littérale exacte ; échappez le motif soigneusement. Utiliser git log file au lieu de git log -- file : le séparateur -- désambiguïse les chemins des refs, surtout si une branche et un fichier partagent un nom. Enfin, attendre de git log qu'il affiche les commits supprimés après un reset forcé ; utilisez git reflog pour cela. git log ne parcourt que l'historique atteignable.