Git/Écrire des messages de commit

< Git

Rédaction

modifier

Les bonnes pratiques sont[1][2] :

  1. 50 caractères maximum pour le titre, résumant les changements.
  2. Selon le contexte, la première ligne est traitée comme le sujet d'un email et le reste séparé par une ligne blanche, comme le corps du message.
  3. Utiliser le présent des verbes.
  4. Les listes à puces sont autorisées, typiquement avec un moins ou une astérisque.
  5. Le corps du message doit comprendre des lignes de 72 caractères maximum pour plusieurs raisons :
    • git format-patch --stdout convertit une série de soumission en une série d'emails.
    • Le log Git ne revient pas automatiquement à la ligne, sans retour chariot il est donc étalé sur une seule ligne donc difficile à lire. Le nombre 72 est le résultat du calcul des 80 du terminal (selon la nétiquette des mails), moins les 4 de l'indentation et les 4 de sa symétrie à droite.


Les utilisateurs de Vim peuvent rencontrer ce prérequis lors de l'installation de vim-git, ou bien en le définissant dans la configuration des messages de soumission Git :

:set textwidth=72

Ceux de TextMate peuvent ajuster l'option colonne "Wrap" du menu "view", puis utiliser ^Q pour revenir à la ligne des paragraphes (s'assurer qu'il y a une ligne blanche après pour éviter le mélange avec les commentaires). Voici une commande shell pour ajouter 72 au menu afin de ne pas avoir à le faire glisser à chaque fois :

$ defaults write com.macromates.textmate OakWrapColumns '( 40, 72, 78 )'

Consultation

modifier

Ces résumés peuvent ensuite être lus via :

  • git log --pretty=oneline affiche une courte liste des historiques avec identifiants et résumés.
  • git rebase --interactive fournit les résumés de ses propres soumissions.
  • Si l'option de configuration merge.summary est définie, les sommaires de toutes les soumissions seront fusionnés.
  • git shortlog n'affiche que les résumés des précédentes soumissions.
  • git format-patch, git send-email.
  • git reflog, un historique local est accessible pour aider à retrouver d'éventuels erreurs.
  • git blame
  • Des interfaces graphiques :
    • gitk, une interface qui a une colonne résumé.
    • Gitweb
    • Les interfaces web de la forge qui héberge le dépôt affichent également les résumés (ex : GitHub, Bitbucket ou GitLab).

La distinction sujet/corps de texte de Git permet donc un confort de recherche d'historique par rapport à d'autres logiciels similaires comme Subversion.

Références

modifier
  1. http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
  2. https://www.midori-global.com/blog/2018/04/02/git-50-72-rule