Git Notes : la fonctionnalité la plus cool et la plus mal-aimée de Git (2022)

• Git notes est un outil puissant qui permet d’ajouter des métadonnées à des commits et à d’autres objets
• Cette fonctionnalité permet de stocker des informations complémentaires lorsqu’il n’est pas possible de modifier le message de commit
• Elle peut servir à enregistrer diverses informations, comme l’historique des revues de code ou les résultats de tests
• Il est même possible de mettre en place un système de revue de code distribué, mais l’ergonomie et la notoriété de la fonctionnalité restent faibles
• Le support étant limité, notamment avec sa désactivation sur GitHub, son adoption au quotidien reste faible

---

Qu’est-ce que Git notes ?

• Git notes est une fonctionnalité de git qui permet d’ajouter des métadonnées à n’importe quel objet suivi par git (commit, blob, tree)
• En général, un message de commit une fois enregistré ne peut pas être modifié, mais avec git notes il est possible d’ajouter de nouvelles informations sans changer le corps du commit
• Par exemple, on peut ajouter des notes à un commit comme ceci
  • git notes add -m 'Acked-by: <이메일>'
• Les notes s’affichent dans git log dans une section séparée

Cas d’usage réels

• Le projet git lui-même utilise git notes pour relier les commits aux fils de discussion de la mailing list
• Voici quelques exemples d’usage concrets des notes
  • suivi du temps de travail par commit ou par branche
  • stockage des journaux de revue de code et des résultats de tests
  • conception d’un système de revue de code entièrement distribué

Stockage des revues de code et des résultats de tests

• De plus en plus de forges de code et de systèmes de revue prennent en charge le stockage hors ligne des métadonnées de revue de code, c’est-à-dire directement dans git
• Le plugin reviewnotes de Gerrit affiche dans git log, via des notes, les personnes ayant effectué la revue ainsi que l’historique d’exécution des tests
  • L’utilisateur peut ainsi consulter localement l’historique de revue du code sans avoir à ouvrir son navigateur

Système de revue de code distribué

• Il existe des exemples de revue de code distribuée fondée sur git notes, comme git-appraise, développé chez Google
• git-appraise enregistre dans git notes l’ensemble du processus — demande de revue de code, commentaires sur les modifications, puis fusion après revue — et fonctionne de manière indépendante de tout service d’hébergement de code en ligne
• Toute la collaboration est possible en local, et l’outil fournit même une interface web

Faible ergonomie et faible notoriété

• Git notes est peu utilisé, car son interface est peu pratique et peu intuitive pour l’utilisateur moyen
• GitHub a cessé d’exposer les notes de commit depuis 2014, ce qui a encore réduit les occasions de les utiliser
• La gestion des notes sur les commits peut être un peu simplifiée via la configuration de git, mais pour attacher des notes à des objets blob ou tree, il faut mieux comprendre la structure interne de git (plumbing)
• En conséquence, git notes reste une fonctionnalité de niche, très peu connue

Indépendance vis-à-vis des forges

• git lui-même peut prendre en charge la gestion de versions distribuée et la revue de code, mais une grande partie de la valeur ajoutée, comme l’historique des revues, tend à dépendre de services d’hébergement tels que GitHub
• En exploitant Git notes, il devient possible de stocker et de distribuer de manière décentralisée non seulement l’historique du code lui-même, mais aussi celui de l’ensemble du projet
• Cela a une importance majeure pour un écosystème de développement pleinement distribué et pour la préservation des traces du projet

[GN⁺]

Commentaires sur Hacker News

• Partage d’information sur une fonctionnalité peu connue appelée les trailers Git : ils permettent d’insérer des métadonnées sous forme de paires clé-valeur lors de la création d’un commit. Utilisé notamment par Gerrit pour ajouter un Change-Id. Lien vers l’article associé

  • PostgreSQL a une fonctionnalité similaire appelée COMMENT, ce qui est mentionné pour comparaison ; COMMENT permet d’ajouter du texte à des objets de base de données. Souhait que PostgreSQL propose aussi une édition de métadonnées structurées en paires clé-valeur. Lien vers la documentation associée

  • Partage d’expérience avec git notes pour marquer, lors d’un travail upstream open source, les commits dont les tests unitaires étaient terminés ; c’était utile pour nettoyer une branche avec git rebase -i, mais les trailers semblent aujourd’hui être une meilleure approche. Si une fonctionnalité comme Change-Id était intégrée directement à Git, les outils pourraient probablement mieux l’interpréter. Distinguer les commits par leur message est subtilement fragile ; l’ID de commit est bien unique, mais perd de sa valeur comme identifiant quand on déplace le même changement sur un autre commit. Édition : les trailers font partie du commit et ne peuvent donc pas complètement remplacer les notes

  • Avoir récemment découvert que GitHub utilise un trailer dédié au lieu de [skip ci], probablement pour pouvoir le séparer plus facilement du message de commit. Pas certain de savoir pourquoi GitHub exige uniquement le dernier trailer, hypothèse d’un traitement par expression régulière. Lien vers la documentation associée

  • Découverte des trailers à cette occasion ; en tant qu’adepte de Conventional Commits, impression qu’ils conviennent mieux pour ajouter ce type de métadonnées. Question sur l’équivalence fonctionnelle entre un ajout manuel dans le message de commit et l’utilisation du drapeau --trailer

  • Envie naturelle d’intégrer cela à un système de suivi d’issues, mais mettre ces informations dans des trailers semble inefficace car trop éloigné de l’issue tracker. Les issue trackers suivent les tendances et ajoutent souvent certaines fonctions tardivement. Agacement face aux règles imposant de reprendre comme titre de PR un nom de branche dérivé du ticket, et envie de relier commits et issues via d’autres métadonnées pour rendre les titres de PR plus significatifs. Sujet difficile à faire évoluer, bon surtout pour se plaindre sur Internet

• Partage d’information : Forgejo a commencé à prendre en charge les trailers à partir de la version 10 sortie en janvier de cette année. Notes de version Pull request

• Question sur l’interaction entre git notes et la réécriture d’historique (amend, rebase, etc.) : comme les notes sont attachées aux ID de commit / tree / blob, demande si elles sont copiées ou disparaissent lorsqu’un commit est remplacé par un nouveau, et ce qui se passe quand plusieurs commits sont fusionnés via un rebase interactif. Partage aussi de l’idée que les notes, attachées au « contenu » des fichiers/répertoires, ne correspondent pas tout à fait à l’intuition ; par exemple, si on attache une note à un blob contenant la chaîne Hello world!, est-ce que tous les fichiers ayant le même contenu héritent de cette note, et est-ce que la note est perdue si le fichier change ?

  • Lors de git rebase et opérations similaires, la copie des notes peut être configurée pour être activée par défaut ; voir l’option notes.rewrite dans git-config(1)

• Utilisation active de git notes dans l’entreprise actuelle, avec pour objectif de garder une trace interne de revue de code sans alourdir les messages de commit ni créer une PR pour chaque changement. Le contexte est laissé sur la branche pour chaque commit : ticket associé, contraintes d’infrastructure, et, dans le cas de correctifs, lien vers le fil d’incident. Le fait de stocker ces informations dans le dépôt permet de comprendre plus facilement pourquoi une ligne a changé, sans devoir chercher dans Slack ou Jira. À grande échelle, cela peut clairement réduire le besoin d’une UI de plateforme. Opinion selon laquelle la reproductibilité doit concerner non seulement les builds, mais aussi l’« intention »

  • Question de savoir si ce type d’information n’aurait pas plutôt sa place dans le message de commit, ou s’il s’agit de pouvoir aussi créer des liens vers des éléments futurs, comme « ce commit a introduit le bug #123 »

• git notes n’est vraiment utile que lorsqu’on a besoin d’ajouter des informations après le commit. Des exemples comme Acked-By ou des liens vers des discussions sur liste de diffusion sont des informations déjà connues au moment du commit, donc autant les ajouter au message de commit. Le vrai avantage des git notes serait plutôt, selon cet avis, d’ajouter plus tard des explications annexes à des commits finalement annulés, par exemple

  • Il arrive souvent qu’un message de commit affirme avoir corrigé un bug alors que ce n’est pas le cas. Cela peut entraîner des bugs en cascade, et les collègues passent parfois dessus sans vraiment respecter l’intention initiale. Après avoir vécu des clients en colère et des régressions, sentiment qu’il faut être prudent avec l’expression bug fix. Parfois, on corrige plusieurs bugs d’un coup, ou bien un refactoring ouvre aussi des possibilités d’amélioration de performances ou de nouvelles fonctionnalités

  • Acked-By, les revues et les discussions ne peuvent souvent se poursuivre qu’après le commit ; on ne les connaît pas forcément au moment où le commit est créé. En revanche, les cas de commit revert sont plutôt utiles dans le message de commit, puisque la fonction blame montre le changement le plus récent et fournit donc naturellement une forme de traçabilité des commits revertés

  • Il est fréquent que la discussion continue après le commit

• Considère que c’est un point intéressant à explorer pour fournir davantage de contexte aux agents de code via la fonctionnalité notes

• Ce n’est pas un manque de connaissance mais un problème d’UI ; si l’UI de GitHub affichait correctement les notes, elles seraient probablement beaucoup plus utilisées

  • Souhait que GitHub prenne en charge les notes

• Git possède beaucoup de fonctionnalités « les plus cool et les moins aimées » comme bisect, pickaxe, reflog, range-diff, archive, les tags annotés, etc., mais la plupart des gens l’utilisent juste comme Google Drive

  • git notes donne de toute façon une impression de redondance, puisque le contexte non technique comme les features ou la roadmap est déjà suivi dans des outils de gestion de projet séparés, par exemple Jira ; selon la philosophie Unix, chacun devrait se concentrer sur son rôle

  • pickaxe est une fonctionnalité jamais entendue auparavant, ce qui surprend ; rappel à ne pas devenir trop sûr de soi

  • Vision selon laquelle ce genre de fonctionnalités décoratives n’est pas si utile en pratique, et relève plutôt de techniques annexes autour de l’essentiel

• Avis que git notes n’est pas vraiment une fonctionnalité « cool » mais délaissée : elle n’a été utile que dans des situations très limitées et spécifiques. Le fait de mettre toutes les informations réellement nécessaires dans le message de commit, puis de les référencer depuis un autre système comme JIRA, est présenté plutôt comme un avantage. Des systèmes comme JIRA servent aussi d’interface de communication avec des business analysts ou le support, qui ne sont pas développeurs ; il est jugé raisonnable que ces personnes n’aient pas accès au dépôt ni au code. Quand on travaille en parallèle sur plusieurs services et dépôts, référencer des features avec de simples notes n’est pas réaliste ; il faut une intégration avec un système externe

  • Remarque qu’il est inefficace que des business analysts n’aient pas accès au code ou au dépôt, car on reçoit alors sans cesse des questions auxquelles une seule ligne de code permettrait de répondre. Mention qu’il existe bien des analystes techniquement compétents, mais que la culture change difficilement

• Découverte de notes via la page de manuel vers 2020 ; par défaut, les notes ne s’appliquent qu’au dépôt local, donc pas d’expérience d’usage réel. Il faut configurer séparément le push/fetch et décider au niveau de l’équipe de les utiliser, mais l’équipe en question n’a pas adopté cela