L'objectif d'un système de contrôle de version est d'enregistrer les changements apportés à votre code. Il vous permet de consulter l'historique de votre projet pour voir qui a contribué à quoi, de déterminer où des bugs ont été introduits et d'annuler les changements problématiques. Toutefois, disposer de cet historique est inutile si vous ne savez pas comment le parcourir. C'est là que la commande git log entre en scène.

Vous devez maintenant connaître la commande git log de base pour afficher les commits. Mais vous pouvez modifier cette sortie en transmettant différents paramètres à la commande git log.

Les fonctionnalités avancées de la commande git log peuvent être réparties en deux catégories : le formatage de l'affichage de chaque commit et le filtrage des commits inclus dans la sortie. Ces deux compétences combinées vous donnent la capacité de revenir en arrière dans votre projet et de trouver les informations dont vous pourriez avoir besoin.

Formater la sortie du journal

Dans un premier temps, cet article explorera les possibilités de formatage de la sortie de git log. La plupart d'entre elles se présentent sous la forme d'options, qui vous permettent de demander plus ou moins d'informations issues de git log.

Si le format par défaut de git log ne vous plaît pas, utilisez l'outil de création d'alias de git config pour créer un raccourci vers toutes les options de formatage décrites ci-dessous. Pour savoir comment créer un alias, consultez la section Commande git config.

Oneline

Le flag --oneline rassemble tous les commits sur une seule ligne. Par défaut, il affiche uniquement la référence du commit et la première ligne du message du commit. La sortie de votre git log --oneline devrait ressembler à cela :

0e25143 Merge branch 'feature'
ad8621a Fix a bug in the feature
16b36c6 Add a new feature
23ad9ad Add the initial code base

Ceci est très utile pour obtenir un aperçu général de votre projet.

Utilisation de -decorate

Dans de nombreuses situations, il est utile de savoir à quelle branche ou option chaque commit est associé. Le flag --decorate ordonne à git log d'afficher toutes les références (p. ex. les branches, les options, etc.) qui pointent vers chaque commit.

Rien ne vous empêche de la combiner avec d'autres options de configuration. Par exemple, lancez git log --oneline --decorate pour formater l'historique des commits comme suit :

0e25143 (HEAD, master) Merge branch 'feature'
ad8621a (feature) Fix a bug in the feature
16b36c6 Add a new feature
23ad9ad (tag: v0.9) Add the initial code base

Ainsi, vous pouvez vérifier que le commit du dessus a aussi été extrait (marqué par HEAD) et qu'il se situe à la pointe de la branche master. Le deuxième commit comporte une autre branche qui pointe dans sa direction, nommée feature. Enfin, le quatrième commit est marqué comme v0.9.

Les branches, les tags, HEAD et l'historique des commits constituent la grande majorité des informations contenues dans votre dépôt Git. Ainsi, vous avez une vision plus détaillée de la structure logique de votre dépôt.

Diffs

La commande git log comporte de nombreuses fonctionnalités servant à afficher les différences pour chaque commit. Deux des options les plus courantes sont --stat et -p.

L'option --stat affiche le nombre d'ajouts et de suppressions effectués dans chaque fichier modifié par chaque commit (remarque : la modification d'une ligne est considérée à la fois comme un ajout et une suppression). Cette fonctionnalité est utile lorsque vous souhaitez obtenir un bref résumé des changements apportés par chaque commit. Par exemple, le commit suivant a ajouté 67 lignes au fichier hello.py et en a supprimé 38 :

commit f2a238924e89ca1d4947662928218a06d39068c3
Author: John <john@example.com>
Date: Fri Jun 25 17:30:28 2014 -0500
Add a new feature
hello.py | 105 ++++++++++++++++++++++++-----------------
1 file changed, 67 insertion(+), 38 deletions(-)

Le nombre de signes + et - situés en regard du nom du fichier indique le nombre relatif de changements apportés à chaque fichier modifié par le commit. Vous obtenez ainsi un aperçu de l'emplacement des changements associés à chaque commit.

Si vous souhaitez consulter les changements réellement apportés par chaque commit, ajoutez l'option -p à git log. De cette manière, vous générez le patch entier qui représente ce commit :

commit 16b36c697eb2d24302f89aa22d9170dfe609855b
Author: Mary <mary@example.com>
Date: Fri Jun 25 17:31:57 2014 -0500
Fix a bug in the feature
diff --git a/hello.py b/hello.py
index 18ca709..c673b40 100644
--- a/hello.py
+++ b/hello.py
@@ -13,14 +13,14 @@ B
-print("Hello, World!")
+print("Hello, Git!")

Lorsque de nombreux changements sont apportés à des commits, la sortie résultante peut devenir longue et complexe. Le plus souvent, lorsque vous affichez un patch complet, c'est parce que vous recherchez un changement spécifique. Pour cela, utilisez l'option de « pioche ».

Shortlog

La commande git shortlog constitue une version spécifique de git log destinée à créer des annonces de livraison. Elle regroupe les commits par auteur et affiche la première ligne de chaque message de commit. C'est une manière simple de voir qui a travaillé dessus.

Par exemple, si deux développeurs ont ajouté cinq commits à un projet, la sortie de git shortlog devrait se présenter comme suit :

Marie (2) :
      A corrigé un bug dans la fonctionnalité
      A corrigé une faille de sécurité grave dans notre framework

Jean (3) :
      A ajouté la base de code initiale
      A ajouté une nouvelle fonctionnalité
      A fait un merge de la branche de fonctionnalité

Par défaut, la commande git shortlog trie les sorties par nom d'auteur, mais il vous est également possible d'ajouter l'option -n pour les trier selon le nombre de commits par auteur.

Graphiques

L'option --graph crée un graphique ASCII représentant la structure de branche de l'historique des commits. Elle est souvent utilisée en association avec les commandes --oneline et --decorate pour mieux visualiser à quelle branche un commit est associé, et vice versa :

git log --graph --oneline --decorate

Pour un dépôt simple qui ne comprend que deux branches, cette commande aura le résultat suivant :

* 0e25143 (HEAD, master) Merge branch 'feature'
|\
| * 16b36c6 Fix a bug in the new feature
| * 23ad9ad Start a new feature
* | ad8621a Fix a critical security issue
|/
* 400e4b7 Fix typos in the documentation
* 160e224 Add the initial code base

L'astérisque indique la branche sur laquelle le commit était situé. Ainsi, le graphique ci-dessus nous apprend que les commits 23ad9ad et 16b36c6 sont sur une branche topic et que les autres se trouvent sur la branche master.

Si cette option est pratique en cas de dépôts simples, il est préférable d'utiliser un outil de visualisation plus complet comme gitk ou Sourcetree si vous travaillez sur des projets contenant beaucoup de branches.

Formatage personnalisé

Pour tous vos autres besoins de formatage git log, vous pouvez utiliser l'option --pretty=format:"<chaîne>". Vous pourrez ainsi afficher les commits au format de votre choix en utilisant des caractères génériques de type printf.

Par exemple, les caractères %cn, %h et %cd de la commande suivante sont respectivement remplacés par le nom du commiteur, l'empreinte abrégée du commit et la date du commit.

git log --pretty=format:"%cn committed %h on %cd"

Le format de chaque commit sera donc le suivant :

John committed 400e4b7 on Fri Jun 24 12:30:04 2014 -0500
John committed 89ab2cf on Thu Jun 23 17:09:42 2014 -0500
Mary committed 180e223 on Wed Jun 22 17:21:19 2014 -0500
John committed f12ca28 on Wed Jun 22 13:50:31 2014 -0500

Consultez la liste complète des caractères génériques dans la section Formats utiles de la page consacrée à git log.

L'option --pretty=format:"<string>" vous permet non seulement d'accéder aux informations qui vous intéressent, mais elle est particulièrement utile lorsque vous souhaitez ajouter la sortie git log à une autre commande.

Filtrer l'historique des commits

Maintenant que le formatage des commits n'a plus de secrets pour vous, vous avez parcouru la moitié du chemin pour connaître git log. Il ne vous reste plus qu'à apprendre à naviguer dans l'historique des commits. Le reste de cet article présente quelques fonctionnalités avancées de la commande git log qui vous permettent de sélectionner des commits spécifiques dans votre historique de projet. Toutes ces fonctionnalités peuvent être combinées avec chacune des options de formatage décrites ci-dessus.

Par somme

Pour filtrer avec git log, la solution la plus simple est de limiter le nombre de commits affichés. Si seuls les quelques commits les plus récents vous intéressent, cela vous évitera de voir tous les commits s'afficher sur une page.

Vous pouvez limiter la sortie de git log en y ajoutant l'option -<n>. Par exemple, la commande suivante affichera uniquement les trois commits les plus récents.

git log -3

Par date

Si vous recherchez un commit correspondant à une période précise, utilisez le flag --after ou --before pour filtrer les commits par date. Ces deux flags peuvent être paramétrés selon toutes sortes de formats de date. Par exemple, la commande suivante n'affiche que les commits créés après le 1er juillet 2014 (inclus) :

git log --after="2014-7-1"

Vous pouvez y ajouter des références relatives, comme « il y a une semaine » et « hier » :

git log --after="yesterday"

Pour rechercher des commits créés entre deux dates précises, indiquez les dates --before et --after. Par exemple, pour afficher tous les commits ajoutés entre le 1er et le 4 juillet 2014, exécutez la commande suivante :

git log --after="2014-7-1" --before="2014-7-4"

Notez que les flags --since et --until sont respectivement synonymes de --after et --before.

Par auteur

Si vous recherchez uniquement des commits créés par un utilisateur en particulier, utilisez le flag --author. Celui-ci peut être défini dans une expression régulière. Il renvoie tous les commits dont l'auteur correspond au modèle. Si vous savez exactement quel utilisateur vous cherchez, utilisez une bête chaîne de caractères brute plutôt qu'une expression régulière.

git log --author="John"

Cela affiche tous les commits dont l'auteur inclut le nom John. Le nom de l'auteur ne doit pas correspondre exactement, il doit juste contenir la phrase spécifiée.

Vous pouvez également utiliser des expressions régulières pour créer des recherches plus complexes. Par exemple, la commande suivante recherche les commits par Marie ou Jean.

git log --author="John\|Mary"

Notez que l'adresse e-mail de l'auteur est également incluse avec son nom. Vous pouvez donc utiliser cette option pour faire une recherche par adresse e-mail.

Si votre workflow fait la distinction entre les commiteurs et les auteurs, le flag --committer opérera de la même façon.

Par message

Pour filtrer les commits en fonction de leur message, utilisez le flag --grep. Celui-ci fonctionne exactement comme le flag --author mentionné ci-dessus, à cela près qu'il se base sur les messages de commit plutôt que sur les auteurs.

Par exemple, si votre équipe inclut des numéros de ticket correspondants dans chaque message de commit, vous pouvez utiliser une commande similaire à celle qui suit pour faire un pull de tous les commits liés à ce ticket :

git log --grep="JRA-224:"

Il vous est également possible d'ajouter le paramètre -i à git log pour que la commande ignore les différences de casse lorsque les modèles correspondent.

Par fichier

La plupart du temps, seuls les changements apportés à un fichier en particulier vous intéresseront. Pour afficher l'historique relatif à un fichier, il vous suffit d'ajouter le chemin d'accès. Par exemple, la commande suivante renvoie tous les commits qui affectaient soit le fichier foo.py ou bar.py :

git log -- foo.py bar.py

Le paramètre -- permet de signaler à git log que les arguments ultérieurs sont des chemins d'accès, et non des noms de branches. Si aucune confusion avec une branche n'est possible, vous pouvez omettre --.

Par contenu

Il est également possible de rechercher des commits qui ajoutent ou suppriment une ligne de code source en particulier. Cet outil est appelé pioche, et il se présente sous la forme de -S"<chaîne>". Par exemple, si vous voulez savoir quand la chaîne Hello, World! a été ajoutée à un fichier du projet, utilisez la commande suivante :

git log -S"Hello, World!"

Si vous souhaitez effectuer une recherche en utilisant une expression régulière plutôt qu'une chaîne, optez pour le flag -G"<expression_régulière>".

Il s'agit d'un outil de débogage très puissant qui vous permet de localiser tous les commits qui impactent une ligne de code spécifique. Vous pouvez également voir à quel moment une ligne a été copiée ou déplacée vers un autre fichier.

Par plage

Ajoutez une plage de commits à git log pour n'afficher que les commits qui font partie de cette plage. La plage est spécifiée au format suivant, où <since> et <until> sont des références de commit :

git log <since>..<until>

Cette commande est particulièrement utile lorsque vous utilisez des références de branche en tant que paramètres. Il s'agit d'un moyen simple d'afficher les différences entre deux branches. Voyez la commande suivante :

git log master..feature

La plage master..feature contient tous les commits qui se trouvent dans la branche feature, mais qui ne sont pas dans la branche master. En d'autres termes, il s'agit du niveau d'avancement de feature depuis la création d'un fork à partir de master. Ceci peut être visualisé comme suit :

Détecter un fork dans l'historique en utilisant des plages

Remarque : si vous changez l'ordre de la plage (feature..master), tous les commits apparaîtront dans master, mais pas dans feature. Si git log génère des commits pour les deux versions, cela signifie que votre historique a divergé.

Filtrer les commits de merge

Par défaut, la sortie de git log comporte des commits de merge. Cependant, si votre équipe est partisane du merge à tout prix (en d'autres termes, vous faites des merges des changements en amont dans des branches topic plutôt que de rebaser la branche topic sur la branche en amont), votre historique de projet comportera de nombreux commits de merge extérieurs.

Empêchez git log d'afficher ces commits de merge en ajoutant le flag --no-merges :

git log --no-merges

D'un autre côté, si seuls les commits de merge vous intéressent, utilisez le flag --merges :

git log --merges

Ceci renvoie tous les commits qui ont au moins deux parents.

Summary

À présent, vous ne devriez avoir aucun mal à utiliser les paramètres avancés de git log pour formater sa sortie et choisir les commits à afficher. Ainsi, vous avez les clés pour extraire des éléments précis de votre historique de projet.

Ces nouvelles connaissances constituent un volet important de votre champ de compétences Git. Souvenez-vous cependant que git log est souvent utilisée conjointement avec d'autres commandes Git. Une fois que vous aurez trouvé le commit que vous cherchiez, vous l'ajouterez généralement à git checkout, git revert ou à tout autre outil vous permettant de gérer votre historique de commits. Veillez donc à mettre vos connaissances à jour concernant les fonctionnalités avancées de Git.

Ready to learn git log?

Essayez ce tutoriel interactif.

Démarrez maintenant