Garder les commits de reformatage hors de git blame : -w et les fichiers ignore-revs

Ce que c'est

git blame annote chaque ligne avec le commit qui l'a modifiée en dernier. Un passage de formateur, un changement d'indentation ou une normalisation des fins de ligne « modifie » chaque ligne, et blame pointe alors vers le commit de nettoyage au lieu du changement qui a introduit la logique. La documentation propose trois outils contre cela :

• -w ignore les espaces lors de la comparaison entre la version parente et la version enfant pour déterminer l'origine des lignes.
• --ignore-rev <rev> traite un commit comme s'il n'avait jamais existé ; les lignes qu'il a touchées sont attribuées au commit antérieur qui les a modifiées. --ignore-revs-file <file> lit de tels commits depuis un fichier, et blame.ignoreRevsFile dans la configuration applique un fichier automatiquement. Avec blame.markIgnoredLines, les lignes réattribuées sont marquées d'un ? ; avec blame.markUnblamableLines, les lignes qui ne peuvent être attribuées à aucun autre commit sont marquées d'un *.
• -M détecte les lignes déplacées ou copiées à l'intérieur d'un fichier, et -C détecte en plus les lignes déplacées ou copiées depuis d'autres fichiers modifiés dans le même commit, de sorte qu'un refactoring qui déplace du code conserve l'auteur d'origine.

La documentation de GitHub indique qu'un fichier nommé .git-blame-ignore-revs à la racine du dépôt est appliqué automatiquement à sa vue blame.

Pourquoi c'est important

Le blame est le moyen par lequel les relecteurs, les ingénieurs d'astreinte et les agents retrouvent le raisonnement derrière une ligne : le message de commit, la pull request, le ticket. Un historique où chaque ligne pointe vers « apply black » ou « prettier 3.0 » perd cette piste précisément au moment où elle est nécessaire.

Comment l'appliquer

• Garder les changements mécaniques de grande ampleur dans leurs propres commits, sans rien d'autre dedans, afin qu'ils puissent être ignorés en bloc.
• Ajouter le hash complet de chaque commit de ce type à .git-blame-ignore-revs, avec une ligne de commentaire l'expliquant, et versionner ce fichier.
• Définir git config blame.ignoreRevsFile .git-blame-ignore-revs dans chaque clone (script d'installation ou commande documentée) ; le fichier n'est pas appliqué en ligne de commande sans cela.
• Utiliser git blame -w -M -C par défaut lors des investigations, et -L <start>,<end> pour limiter la plage.
• Les éditeurs et les hébergeurs de code lisent le même fichier ; vérifier lesquels le font avant de s'y fier.

Pièges

Ignorer un commit qui contenait aussi de vrais changements masque ces changements au blame. Les hashes doivent être non abrégés (la documentation de configuration demande un nom d'objet complet par ligne), et après une réécriture de l'historique, les identifiants listés ne correspondent plus à rien, si bien que le fichier doit être régénéré. git log -S et git bisect ne sont pas affectés et retrouvent toujours le commit en cas de besoin.