Écrire de bons messages de commit avec Git

De Ensiwiki
Aller à : navigation, rechercher

Git conserve l'historique de toutes les révisions d'un projet. C'est entre autre ce qui permet de faire des fusions automatiques, et une utilisation évidente de l'historique est de pouvoir rattraper des bêtises a posteriori (« j'ai effacé la fonction f() la semaine dernière, je me rends compte aujourd'hui que j'en avais besoin, comment la récupérer ? »). Mais c'est loin d'être le seul intérêt :

  1. Il arrive parfois qu'on se demande pourquoi, et dans quelles conditions une ligne de code a été introduite. La commande git blame permet de trouver le commit qui a introduit chaque ligne d'un fichier, et on peut donc savoir quand et par qui la ligne a été introduite. Si le commit a été fait proprement, il est accompagné d'un message explicatif (message de commit, ou message de log).
  1. Quand une régression est détectée dans un projet (un bug présent mais qui n'existait pas avant), on peut remonter dans l'historique pour trouver quel commit a introduit le bug (la commande git bisect permet même de le faire automatiquement). Une fois le commit identifié, on peut regarder ce qu'il contient pour comprendre l'origine du bug.

Dans les deux cas, on apprécie d'avoir un message de commit détaillé. Ces messages sont presque aussi importants que les commentaires dans le code (certains diraient même « plus importants »). Cet article donne quelques pistes pour écrire de bons messages de commits.

Sur le fond : répondre à la question « Pourquoi ? »

Comme pour les commentaires dans le code, tenter de documenter ce que fait un commit est rarement une bonne idée. Vous savez déjà que commenter votre code à coups de

int i; // déclaration de variable i de type entier

est une mauvaise idée. Pour un message de commit, le principe est le même : ne pas s'attarder sur la question « Quoi ? ». Pour y répondre, le lecteur peut regarder le diff associé au commit. Par exemple, si un commit introduit une fonction f(), l'important est de documenter pourquoi cette fonction f() est intéressante, et quelle était l'intention de l'auteur en l'ajoutant.

Plus tard, un lecteur se demandant l'utilité de cette fonction existe pourra faire un git blame, et il ne serait pas très avancé si le message associé au commit disait « ajout de la fonction f() ».

Un testeur trouvant une regression et en cherchant l'origine avec git bisect pourrait tomber sur ce commit. Si le message explique correctement l'intention du programmeur, alors on peut examiner le diff associé et comprendre pourquoi ce commit n'est pas aussi bon qu'il le prétend (puisqu'on vient de remarquer qu'il introduisait un bug). Si le message de commit dit simplement « il est tard, je vais me coucher je finirai demain », on n'est pas très avancé non plus ...

Sur la forme : sommaire, et corps du message

La convention avec Git est de rédiger un message de commit comme on rédige un e-mail : une ligne courte de sommaire (la seule qui s'intéresse à la question « Quoi ? »), puis une ligne vide, puis un argumentaire rédigé expliquant pourquoi le changement est bon.

Le format est donc :

<ligne de sujet>

<un ou plusieurs paragraphe d'explications>

La ligne de sujet doit rester courte (si possible moins de 50 caractères, pour que la sortie de git log --oneline tienne dans un terminal de 80 colonnes). C'est l'équivalent du sujet d'un e-mail, et c'est cette ligne qui apparaitra dans gitk ou git log --oneline par exemple.

Il faut une ligne blanche pour séparer la ligne de sujet, sinon Git va afficher tout le premier paragraphe partout où il aurait affiché la ligne de sujet.

La suite est une explication rédigée sur le commit. Ne pas hésiter à faire une explication longue si c'est nécessaire (typiquement plusieurs paragraphes).

Sauf cas particulier, on préfèrera donc rédiger un message de commit depuis son éditeur de texte préféré (lancé par défaut par git commit) à l'option --message (-m) de git commit.

Lien avec un e-mail

En fait, l'analogie avec l'e-mail est plus qu'une analogie : les commandes git format-patch et git send-email permettent de transformer un commit en un e-mail, que le destinataire du message peut appliquer avec git apply ou git am. La ligne de sujet devient le sujet du mail, et la suite du message devient le corps de l'e-mail. Ce système peut être utilisé pour s'envoyer des commits entre développeurs dans une équipe de développement (le développement de l'outil Git lui-même utilise presque exclusivement le mail), ou bien par des systèmes de notification qui envoient le contenu des commits à toute l'équipe après un push (cf. par exemple Mettre en place un envoi de mail automatique à chaque push avec Git).

Dans les deux cas, on apprécie quand les messages sont bien formattés.

Et si le contenu du commit est difficile à documenter ?

Il arrive parfois qu'on code plusieurs choses en même temps (par exemple, une vrai fonctionnalité et une correction de typo remarquée par hasard dans un commentaire). Il est tentant d'écrire un message de commit décrivant toutes ces modifications. En pratique, c'est en général une meilleure idée de faire plusieurs commits, chacun ayant un message de commit clair et en rapport avec les modifications apportées par le commit. Si vous êtes tentés d'utiliser une liste à puces dans votre message de commit, posez-vous la question : ne faudrait-il pas mieux faire plusieurs commits séparés ?

Techniquement, vous trouverez des explications sur la manière de séparer votre historique en une succession de commits propres sur la page Maintenir un historique propre avec Git.

Exemples

Pour donner quelques exemples concrets, quoi de mieux que de regarder les commits d'un vrai projet ?

Regardez par exemple comment sont rédigés les messages de commit de Git, en prenant n'importe quel commit (de préférence pas un merge commit) dans cette liste : https://github.com/git/git/commits/master

Pour donner un exemple un peu caricatural, regardons le commit make color.ui default to 'auto'. Ce commit active l'affichage des couleurs dans Git par défaut. Le code a proprement parler est trivial (2 lignes modifiées), et même la mise à jour de la documentation est assez simple. Pourtant, la décision d'activer les couleurs par défaut n'est pas anodine, et méritait bien les 6 paragraphes d'argumentaires.

(On peut d'ailleurs remarquer que même si les 2 lignes modifiées paraissaient triviales, elles introduisaient tout de même une régression, qui a été corrigée plus tard dans 7f3b8c628e !)

Plus de documentation

  • on commitmessages, sur le blog Who-T. Également un peu long, mais très instructif,