git essentials – 1 – log

Ceci est le premier article d’une série consacrée aux commandes de git, le sytème de gestion de révisions décentralisé. Le sujet de cet article est la commande log, qui permet de visualiser l’historique d’un dépôt. Visualiser clairement l’historique d’un dépôt est essentiel pour comprendre l’évolution d’un projet : quelle fonctionnalité a été développée à quel moment, par qui, quel commit a introduit quel changement, etc.

Nous partirons de la commande de base et étudierons les options qui font de cette commande un outil indispensable pour comprendre l’histoire d’un projet. Nous verrons qu’en combinant les options, nous pouvons obtenir un résultat visuel en local, dans un terminal, aussi pratique et bien plus flexible que les graphes offerts par les outils tels que github, gitlab ou les extensions git des EDI.

À la fin de cet article, vous saurez plier les logs à votre volonté, visualisant uniquement les informations qui vous intéressent, sur la portion de temps voulue et avec la forme désirée.

Lorsque vous voulez visualiser l’historique d’un projet versionné sous git, c’est-à-dire les commits qui ont été effectués, la commande à utiliser est git log. Parmi les informations utiles que celle-ci pourra vous fournir, il y aura l’identifiant du commit, le nom de l’auteur, la date, le commentaire, à quelle(s) branche(s) il appartient et bien d’autres.

Pour le reste de cet article, nous allons prendre un exemple de projet simple. Il contient quelques commits, et deux branches, master et featureF :

[java]* C4 (featureF): Début de la feature F
| * C3 (master): Add powerful script
|/
* C2: Modify a.txt
|
* C1: Initial commit[/java]

Comme nous pouvons l’observer, le commit C3 ne se trouve que sur la branche master et le commit C4 que sur la branche featureF.

Si le dépôt central se trouve sur github, on peut avoir un joli graphe de ce genre :

Notre objectif est d’obtenir un résultat similaire aux commandes git, en local, dans le terminal (donc utilisable à distance lors d’une session SSH par exemple), avec plus d’informations utiles, à afficher à la demande.

La commande de base

Lorsque l’on utilise la commande de base :

[java]git log[/java]

On obtient :

Nous pouvons alors voir, pour chaque commit de la branche courante (master), l’identifiant, l’auteur, la date précise et le commentaire. Ces informations peuvent servir, mais la plupart du temps, l’identifiant complet du commit n’est pas nécessaire, ainsi que les coordonnées email de l’auteur et la date précise. C’est pourquoi nous allons voir comment obtenir une information plus concise.

Soyons plus synthétiques

L’option --oneline de git log permet de visualiser chaque commit sous un format compact d’une ligne :

[java]git log –oneline[/java]

On obtient :

Nous avons la même liste de commit que précédemment, avec seulement les informations indispensables : l’identifiant abrégé du commit, ainsi que le commentaire.

Maintenant que nous avons une vue plus synthétique, nous pourrions souhaiter visualiser toutes les branches, pas seulement la branche courante.

Visualiser toutes les branches du projet

Pour visualiser l’historique de toutes les branches, git log offre l’option --all :

[java]git log –oneline –all[/java]

On obtient :

Nous voyons alors apparaitre, en plus des commits présents sur la branche courante master, les commits présents sur les autres branches. Dans l’exemple de cet article, il n’y en a qu’un seul, celui dont le commentaire est « Début de la feature F », qui est un commit appartenant uniquement à la branche featureF. Cependant, une telle vue n’est pas très pratique pour comprendre à quelle(s) branche(s) appartient un commit.

Visualiser sous forme de graphe

Il est possible de visualiser l’arborescence des commits sous forme de graphe avec l’option --graph :

[java]git log –oneline –all –graph[/java]

On obtient :

Et là, nous voyons bien que le projet est constitué de deux branches. Toutefois, même si les commentaires nous aident, il serait pratique de pouvoir ajouter au graphe les étiquettes des branches.

Ajouter les informations de branche et révision courante

L’option --decorate permet d’enrichir la sortie de la commande avec les informations relatives aux branches, tags et révision courante (HEAD) :

[java]git log –oneline –all –graph –decorate[/java]

On obtient :

Grâce à cette nouvelle option, nous pouvons voir les noms des branches locales, distantes, ainsi que la révision courante, c’est-à-dire le pointeur HEAD.

Avec de la couleur, c’est mieux

Pour ajouter des couleurs améliorant la lisibilité du tout, l’option --color est disponible :

[java]git log –oneline –all –graph –decorate –color[/java]

On obtient :

La colorisation permet de distinguer d’un coup d’œil les branches locales (vert) des branches distantes (rouge).

Ajouter le résumé des fichiers modifiés

Pour lister de manière concise les fichiers qui ont été modifiés dans chaque commit, on peut utiliser l’option --name-status :

[java]git log –oneline –all –graph –decorate –color –name-status[/java]

On obtient :

Cette option nous permet d’avoir un résumé du contenu du commit : quel fichier a été modifié et quelle était la nature de cette modification (A pour Ajout, M pour Modification…).

Mettre en forme plus finement

Les options --oneline et --decorate sont des options de formatage « rapide ». Elles vous permettent d’obtenir un résultat mis en forme avec un minimum d’options à spécifier. Il est toutefois possible de paramétrer très finement la mise en forme de la sortie de git log. Pour ce faire, l’option --format=STRING est disponible, où STRING est une chaine de caractères composée de balises prédéfinies dans la documentation de git log.

Prenons un exemple qui permet d’obtenir le même résultat que précédemment (à la couleur près, nous allons y revenir), sans les options --oneline et --decorate mais avec --format :

[java]git log –all –graph –color –name-status –format="%h %d %s"[/java]

On obtient :

Quelques explications sur la chaine de mise en forme « %h %d %s » : elle est composée de paramètres fictifs (en anglais, « placeholders ») qui signifient :

• %h : hash du commit ( = identifiant) abrégé
• %d : informations de branches, comme le ferait l’option --decorate
• %s : sujet du commit

De nombreux autres paramètres fictifs sont disponibles, comme le nom de l’auteur ou la date, pour choisir les informations que vous voulez afficher. Pour obtenir la liste complète des informations disponibles, man git-log, section PRETTY FORMATS.

Par exemple, des balises de couleur sont disponibles :

[java]git log –all –graph –color –name-status –format="%C(yellow)%h%C(reset) %C(auto)%d%C(reset) %s"[/java]

On obtient :

Maintenant, voici celui que j’utilise personnellement tous les jours :

[java]git log –all –graph –color –name-status –format=’%C(yellow)%h%Creset %cr %C(blue)%cn%Creset -%C(auto)%d%Creset %s'[/java]

Il utilise, en plus de ce que nous venons de voir, les paramètres fictifs suivants :

• %cr : pour la date relative (car je préfère par rapport à une date absolue) de commit (« commit relative date »)
• %cn : pour le nom du de la personne ayant effectué le commit (« committer name »)

On obtient alors :

Conclusion

Nous avons vu comment visualiser l’historique d’un projet de manière synthétique. C’est un outil indispensable pour comprendre ce qu’il se passe sur son projet, en particulier lors des opérations de fusion (« merge ») ou de création de branches. Comme il peut être long de se souvenir de toutes les options utiles, on peut créer un alias git pour une utilisation régulière :

[java]git config –global alias.la "log –all –graph –color –name-status –format=’%C(yellow)%h%Creset %cr %C(blue)%cn%Creset -%C(auto)%d%Creset %s’"[/java]

Cela rendra accessible la (longue) commande du dernier exemple de l’article via :

[java]git la[/java]

Les alias et la configuration locale git feront d’ailleurs l’objet d’un prochain article dans cette série.

En attendant, usez et abusez de la commande git log, entre chaque commande si vous débutez en git !