Git mailmap ou comment identifier les contributeurs d'un projet

Vous êtes-vous déjà demandé, après avoir lancé un git blame sur un fichier, qui est le collègue qui se cache derrière cet obscur pseudo ? Vous est-il déjà arrivé de pousser un commit avec une mauvaise configuration ou depuis la mauvaise machine ?

❯ git blame README.md
53e6ebfb (Mr Robot 2020-11-03 10:13:42 +0200  1) # Read me
...

Lorsque l’on travaille sur un projet dont le code est versionné avec Git, il est recommandé de définir son nom et son adresse email :

git config user.name "Ada Lovelace"
git config user.email "alovelace@cam.ac.uk"

Ceci peut être fait à l’échelle d’un projet, comme ici, ou de manière globale en ajoutant l’option --global aux commandes ci-dessus. Ce qui en résultera, c’est que vos informations seront stockées dans un fichier ~/.gitconfig, dans votre répertoire personnel donc, plutôt que dans un fichier .gitconfig à la racine du projet. Et pour connaître les valeurs associées à une clé, l’option --get-all est disponible.

❯ git config --local user.email
alovelace@cam.ac.uk

❯ git config --global user.email
alovelace@example.org

❯ git config --get-all user.email
alovelace@example.org
alovelace@cam.ac.uk

Seulement voilà, parfois, par mégarde, on pousse un commit avec la mauvaise configuration et on se retrouve avec ceci dans les logs de Git :

Merge branch 'draft/dont-repeat-yourself' into 'master'

Commit: acfb98ff6bf4743ae9788cb530b1a482bf88fff5
Author: Ada <alovelace@alovelace-cambridge-univ.local>
Date:   2020-07-02 14:32:58 +0200 (il y a 4 mois)

Et évidemment, le temps qu’on s’en rende compte, il n’est plus question de réécrire l’arbre des commits ! Alors que faire ?

Rien. Ce n’est pas si grave, tu peux laisser ça comme ça !
— un lecteur qui a déjà oublié le sujet de l’article

En effet, il n’y a pas péril en la demeure, mais…

ça brouille la lecture des statistiques
ça peut rendre git blame assez cryptique
ça nous empêche de savoir à quelle adresse contacter un contributeur

❯ git shortlog -sne
   267  Augusta Ada King, Countess of Lovelace <alovelace@example.org>
   ...
   130  Ada Lovelace <alovelace@cam.ac.uk>
   ...
    32  Augusta Ada King <ada.lovelace@example.org>

❯ git blame dont_repeat_yourself.md
...
acfb98ff (Ada Lovelace 1843-07-02 14:32:58 +0200  52)
acfb98ff (Ada Lovelace 1843-07-02 14:32:58 +0200  53)
984e8d96 (alovelace    1843-07-02 14:30:37 +0200  54)
984e8d96 (alovelace    1843-07-02 14:30:37 +0200  55)
...

Mailmap à la rescousse !

Sachez que rien n’est perdu ! Pour pallier cette situation, Git nous offre la possibilité de déclarer un fichier .mailmap dans lequel nous pourrons déclarer le nom et l’adresse email de chaque contributeur.

Il s’agit d’un simple fichier à plat dont voici le format attendu pour chaque ligne :

Prénom Nom <prenom.nom@example.com>   Pseudo <pseudo@example.org>

Il s’agit donc de déclarer les coordonnées attendues, suivies de celles à remplacer. Ici, on voudra donc remplacer toute occurrence de Pseudo <pseudo@example.org> par Prénom Nom <prenom.nom@example.com>.

Il est aussi possible de ne déclarer que la première partie. Cela peut être suffisant, par exemple, quand seul le nom d’un contributeur change d’un commit à l’autre, mais que son adresse email reste la même.

Pour nous assurer que notre fichier .mailmap est pris en compte comme attendu, Git nous met à disposition une petite commande :

❯ git check-mailmap "<pseudo@example.org>"
Prénom Nom <prenom.nom@example.com>

Si l’on reprend les exemples ci-dessus, nous pourrions écrire ce .mailmap :

Ada Lovelace <alovelace@cam.ac.uk> <alovelace@example.org>
Ada Lovelace <alovelace@cam.ac.uk> <ada.lovelace@example.org>

Notez que je n’ai pas précisé le nom associé à l’adresse email à remplacer ! Cela signifie que, peu importe le nom associé à cette adresse, on souhaite utiliser le nom déclaré en début de ligne.

Et nos problèmes sont ainsi résolus !

❯ git shortlog -sne
   429  Ada Lovelace <alovelace@cam.ac.uk>
   ...

❯ git blame dont_repeat_yourself.md
...
acfb98ff (Ada Lovelace 2020-07-02 14:32:58 +0200  52)
acfb98ff (Ada Lovelace 2020-07-02 14:32:58 +0200  53)
984e8d96 (Ada Lovelace 2020-07-02 14:30:37 +0200  54)
984e8d96 (Ada Lovelace 2020-07-02 14:30:37 +0200  55)
...

Voilà, c’était un petit article sans prétention pour vous présenter une fonctionnalité méconnue de Git. J’espère que cette pastille vous a plu ! Et si vous êtes curieux, n’hésitez pas à faire un tour sur la documentation officielle de Git qui traite précisément de ce sujet.