Git
Chapters ▾ 2nd Edition

2.3 Les bases de Git - Visualiser l’historique des validations

Visualiser l’historique des validations

Après avoir créé plusieurs commits ou si vous avez cloné un dépôt ayant un historique de commits, vous souhaitez probablement revoir le fil des évènements. Pour ce faire, la commande git log est l’outil le plus basique et le plus puissant.

Les exemples qui suivent utilisent un projet très simple nommé simplegit utilisé pour les démonstrations. Pour récupérer le projet, lancez :

git clone https://github.com/schacon/simplegit-progit

Lorsque vous lancez git log dans le répertoire de ce projet, vous devriez obtenir un résultat qui ressemble à ceci :

$ git log
commit ca82a6dff817ec66f44342007202690a93763949
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Mar 17 21:52:11 2008 -0700

    changed the version number

commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Sat Mar 15 16:40:33 2008 -0700

    removed unnecessary test

commit a11bef06a3f659402fe7563abf99ad00de2209e6
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Sat Mar 15 10:31:28 2008 -0700

    first commit

Par défaut, git log invoqué sans argument énumère en ordre chronologique inversé les commits réalisés. Cela signifie que les commits les plus récents apparaissent en premier. Comme vous le remarquez, cette commande indique chaque commit avec sa somme de contrôle SHA-1, le nom et l’e-mail de l’auteur, la date et le message du commit.

git log dispose d’un très grand nombre d’options permettant de paramétrer exactement ce que l’on cherche à voir. Nous allons détailler quelques-unes des plus utilisées.

Une des options les plus utiles est -p, qui montre les différences introduites entre chaque validation. Vous pouvez aussi utiliser -2 qui limite la sortie de la commande aux deux entrées les plus récentes :

$ git log -p -2
commit ca82a6dff817ec66f44342007202690a93763949
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Mar 17 21:52:11 2008 -0700

    changed the version number

diff --git a/Rakefile b/Rakefile
index a874b73..8f94139 100644
--- a/Rakefile
+++ b/Rakefile
@@ -5,7 +5,7 @@ require 'rake/gempackagetask'
 spec = Gem::Specification.new do |s|
     s.platform  =   Gem::Platform::RUBY
     s.name      =   "simplegit"
-    s.version   =   "0.1.0"
+    s.version   =   "0.1.1"
     s.author    =   "Scott Chacon"
     s.email     =   "schacon@gee-mail.com"
     s.summary   =   "A simple gem for using Git in Ruby code."

commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Sat Mar 15 16:40:33 2008 -0700

    removed unnecessary test

diff --git a/lib/simplegit.rb b/lib/simplegit.rb
index a0a60ae..47c6340 100644
--- a/lib/simplegit.rb
+++ b/lib/simplegit.rb
@@ -18,8 +18,3 @@ class SimpleGit
     end

 end
-
-if $0 == __FILE__
-  git = SimpleGit.new
-  puts git.show
-end
\ No newline at end of file

Cette option affiche la même information mais avec un diff suivant directement chaque entrée. C’est très utile pour des revues de code ou pour naviguer rapidement à travers l’historique des modifications qu’un collaborateur a apportées. Vous pouvez aussi utiliser une liste d’options de résumé avec git log. Par exemple, si vous souhaitez visualiser des statistiques résumées pour chaque commit, vous pouvez utiliser l’option --stat :

$ git log --stat
commit ca82a6dff817ec66f44342007202690a93763949
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Mar 17 21:52:11 2008 -0700

    changed the version number

 Rakefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Sat Mar 15 16:40:33 2008 -0700

    removed unnecessary test

 lib/simplegit.rb | 5 -----
 1 file changed, 5 deletions(-)

commit a11bef06a3f659402fe7563abf99ad00de2209e6
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Sat Mar 15 10:31:28 2008 -0700

    first commit

 README           |  6 ++++++
 Rakefile         | 23 +++++++++++++++++++++++
 lib/simplegit.rb | 25 +++++++++++++++++++++++++
 3 files changed, 54 insertions(+)

Comme vous pouvez le voir, l’option --stat affiche sous chaque entrée de validation une liste des fichiers modifiés, combien de fichiers ont été changés et combien de lignes ont été ajoutées ou retirées dans ces fichiers. Elle ajoute un résumé des informations en fin de sortie.

Une autre option utile est --pretty. Cette option modifie le journal vers un format différent. Quelques options incluses sont disponibles. L’option oneline affiche chaque commit sur une seule ligne, ce qui peut s’avérer utile lors de la revue d’un long journal. En complément, les options short (court), full (complet) et fuller (plus complet) montrent le résultat à peu de choses près dans le même format mais avec plus ou moins d’informations :

$ git log --pretty=oneline
ca82a6dff817ec66f44342007202690a93763949 changed the version number
085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7 removed unnecessary test
a11bef06a3f659402fe7563abf99ad00de2209e6 first commit

L’option la plus intéressante est format qui permet de décrire précisément le format de sortie. C’est spécialement utile pour générer des sorties dans un format facile à analyser par une machine — lorsqu’on spécifie intégralement et explicitement le format, on s’assure qu’il ne changera pas au gré des mises à jour de Git : 

$ git log --pretty=format:"%h - %an, %ar : %s"
ca82a6d - Scott Chacon, 6 years ago : changed the version number
085bb3b - Scott Chacon, 6 years ago : removed unnecessary test
a11bef0 - Scott Chacon, 6 years ago : first commit

Options utiles pour git log --pretty=format liste les options de formatage les plus utiles.

Tableau 1. Options utiles pour git log --pretty=format
Option Description du formatage

%H

Somme de contrôle du commit

%h

Somme de contrôle abrégée du commit

%T

Somme de contrôle de l’arborescence

%t

Somme de contrôle abrégée de l’arborescence

%P

Sommes de contrôle des parents

%p

Sommes de contrôle abrégées des parents

%an

Nom de l’auteur

%ae

E-mail de l’auteur

%ad

Date de l’auteur (au format de l’option -date=)

%ar

Date relative de l’auteur

%cn

Nom du validateur

%ce

E-mail du validateur

%cd

Date du validateur

%cr

Date relative du validateur

%s

Sujet

Vous pourriez vous demander quelle est la différence entre auteur et validateur. L'auteur est la personne qui a réalisé initialement le travail, alors que le validateur est la personne qui a effectivement validé ce travail en gestion de version. Donc, si quelqu’un envoie un patch à un projet et un des membres du projet l’applique, les deux personnes reçoivent le crédit — l’écrivain en tant qu’auteur, et le membre du projet en tant que validateur. Nous traiterons plus avant de cette distinction dans le Git distribué.

Les options oneline et format sont encore plus utiles avec une autre option log appelée --graph. Cette option ajoute un joli graphe en caractères ASCII pour décrire l’historique des branches et fusions :

$ git log --pretty=format:"%h %s" --graph
* 2d3acf9 ignore errors from SIGCHLD on trap
*  5e3ee11 Merge branch 'master' of git://github.com/dustin/grit
|\
| * 420eac9 Added a method for getting the current branch.
* | 30e367c timeout code and tests
* | 5a09431 add timeout protection to grit
* | e1193f8 support for heads with slashes in them
|/
* d6016bc require time for xmlschema
*  11d191e Merge branch 'defunkt' into local

Ces options deviendront plus intéressantes quand nous aborderons les branches et les fusions dans le prochain chapitre.

Les options ci-dessus ne sont que des options simples de format de sortie de git log — il y en a de nombreuses autres. Options usuelles de git log donne une liste des options que nous avons traitées ainsi que d’autres options communément utilisées accompagnées de la manière dont elles modifient le résultat de la commande log.

Tableau 2. Options usuelles de git log
Option Description

-p

Affiche le patch appliqué par chaque commit

--stat

Affiche les statistiques de chaque fichier pour chaque commit

--shortstat

N’affiche que les ligne modifiées/insérées/effacées de l’option --stat

--name-only

Affiche la liste des fichiers modifiés après les informations du commit

--name-status

Affiche la liste des fichiers affectés accompagnés des informations d’ajout/modification/suppression

--abbrev-commit

N’affiche que les premiers caractères de la somme de contrôle SHA-1

--relative-date

Affiche la date en format relatif (par exemple "2 weeks ago" : il y a deux semaines) au lieu du format de date complet

--graph

Affiche en caractères ASCII le graphe de branches et fusions en vis-à-vis de l’historique

--pretty

Affiche les commits dans un format alternatif. Les formats incluent oneline, short, full, fuller, et format (où on peut spécifier son propre format)

--oneline

Option de convenance correspondant à --pretty=oneline --abbrev-commit

Limiter la longueur de l’historique

En complément des options de formatage de sortie, git log est pourvu de certaines options de limitation utiles — des options qui permettent de restreindre la liste à un sous-ensemble de commits. Vous avez déjà vu une de ces options — l’option -2 qui ne montre que les deux derniers commits. En fait, on peut utiliser -<n>, où n correspond au nombre de commits que l’on cherche à visualiser en partant des plus récents. En vérité, il est peu probable que vous utilisiez cette option, parce que Git injecte par défaut sa sortie dans un outil de pagination qui permet de la visualiser page à page.

Cependant, les options de limitation portant sur le temps, telles que --since (depuis) et --until (jusqu’à) sont très utiles. Par exemple, la commande suivante affiche la liste des commits des deux dernières semaines :

$ git log --since=2.weeks

Cette commande fonctionne avec de nombreux formats — vous pouvez indiquer une date spécifique (2008-01-05) ou une date relative au présent telle que "2 years 1 day 3 minutes ago".

Vous pouvez aussi restreindre la liste aux commits vérifiant certains critères de recherche. L’option --author permet de filtrer sur un auteur spécifique, et l’option --grep permet de chercher des mots clés dans les messages de validation.

Note

Vous pouvez spécifier à la fois des instances --author et --grep, ce qui limitera la sortie aux commits correspondant à au moins un des critères ; cependant l’ajout de l’option --all-match limite la sortie aux seuls commits qui correspondent à la fois à tous les critères des motifs --grep.

Un autre filtre vraiment utile est l’option -S qui prend une chaîne de caractères et ne retourne que les commits qui introduisent des modifications qui ajoutent ou retirent du texte comportant cette chaîne. Par exemple, si vous voulez trouver la dernière validation qui a ajouté ou retiré une référence à une fonction spécifique, vous pouvez lancer :

$ git log -S nom_de_fonction

La dernière option vraiment utile à git log est la spécification d’un chemin. Si un répertoire ou un nom de fichier est spécifié, le journal est limité aux commits qui ont introduit des modifications aux fichiers concernés. C’est toujours la dernière option de la commande, souvent précédée de deux tirets (--) pour séparer les chemins des options précédentes.

$ git log -- chemin/vers/le/fichier

Le tableau Options pour limiter la sortie de git log récapitule les options que nous venons de voir ainsi que quelques autres pour référence.

Tableau 3. Options pour limiter la sortie de git log
Option Description

-(n)

N’affiche que les n derniers commits

--since, --after

Limite l’affichage aux commits réalisés après la date spécifiée

--until, --before

Limite l’affichage aux commits réalisés avant la date spécifiée

--author

Ne montre que les commits dont le champ auteur correspond à la chaîne passée en argument

--committer

Ne montre que les commits dont le champ validateur correspond à la chaîne passée en argument

--grep

Ne montre que les commits dont le message de validation contient la chaîne de caractères

-S

Ne montre que les commits dont les ajouts ou retraits contient la chaîne de caractères

Par exemple, si vous souhaitez visualiser quels commits modifiant les fichiers de test dans l’historique du code source de Git ont été validés par Junio C Hamano et n’étaient pas des fusions durant le mois d’octobre 2008, vous pouvez lancer ce qui suit :

$ git log --pretty="%h - %s" --author='Junio C Hamano' --since="2008-10-01" \
   --before="2008-11-01" --no-merges -- t/
5610e3b - Fix testcase failure when extended attributes are in use
acd3b9e - Enhance hold_lock_file_for_{update,append}() API
f563754 - demonstrate breakage of detached checkout with symbolic link HEAD
d1a43f2 - reset --hard/read-tree --reset -u: remove unmerged new paths
51a94af - Fix "checkout --track -b newbranch" on detached HEAD
b0ad11e - pull: allow "git pull origin $something:$current_branch" into an unborn branch

À partir des 40 000 commits constituant l’historique des sources de Git, cette commande extrait les 6 qui correspondent aux critères.

Astuce
Empêcher l’affichage de commits de fusion

En fonction du mode de gestion de votre dépôt, il est possible qu’un pourcentage certain des commits dans votre historique local soient juste des commits de fusion, ce qui n’apporte généralement que peu d’information. Pour empêcher l’affichage des commits de fusion qui encombrent le journal, ajoutez simplement l’option --no-merges.
scroll-to-top