Écrire de bons messages de commit avec Git : Différence entre versions

De Ensiwiki
Aller à : navigation, rechercher
(catégories)
(comment écrire de bons messages)
Ligne 9 : Ligne 9 :
 
== Sur le fond : répondre à la question « Pourquoi ? » ==
 
== 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
 +
 
 +
<pre>
 +
int i; // déclaration de variable i de type entier
 +
</pre>
 +
 
 +
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 <code>f()</code>, l'important est de documenter ''pourquoi'' cette fonction <code>f()</code> 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 <code>git blame</code>, 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 <code>git bisect</code> 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 ==
 
== 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 :
 +
 
 +
<pre>
 +
<ligne de sujet>
 +
 
 +
<un ou plusieurs paragraphe d'explications>
 +
</pre>
 +
 
 +
La ligne de sujet doit rester courte (si possible moins de 50 caractères, pour que la sortie de <code>git log --oneline</code> 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 <code>gitk</code> ou <code>git log --oneline</code> 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).
 +
 
 +
== Lien avec un e-mail ==
 +
 
 +
En fait, l'analogie avec l'e-mail est plus qu'une analogie : les commandes <code>git format-patch</code> et <code>git send-email</code> permettent de transformer un commit en un e-mail, que le destinataire du message peut appliquer avec <code>git apply</code> ou <code>git am</code>. 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.
 +
 
 +
== 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 prennant 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 carricatural, regardons le commit [https://github.com/git/git/commit/4c7f1819b3c142ace98269a556bc929c80e7c9fd 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 regression, qui a été corrigée plus tard dans 7f3b8c628e !)
 +
 
 +
== Plus de documentation ==
 +
 
 +
* [http://who-t.blogspot.de/2009/12/on-commit-messages.html on commitmessages], sur le blog Who-T. Un peu long, mais très instructif.
 +
 
 +
* [http://git-scm.com/docs/git-commit man git-commit], section DISCUSSION.
  
 
[[Catégorie:Projet GL]]
 
[[Catégorie:Projet GL]]
 
[[Catégorie:Git]]
 
[[Catégorie:Git]]

Version du 5 décembre 2013 à 20:46

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).

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.

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 prennant 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 carricatural, 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 regression, qui a été corrigée plus tard dans 7f3b8c628e !)

Plus de documentation