Comment lire un résultat de diff : comprendre les fichiers patch et les changements

Comment lire un résultat de diff : comprendre les fichiers patch et les changements

Le résultat de diff est le langage universel des systèmes de contrôle de version. Chaque développeur rencontre régulièrement un résultat de diff — lors d'une revue de code, en résolvant des conflits de fusion ou en appliquant des patchs issus de contributions open source. Pourtant, de nombreux développeurs n'apprennent jamais à lire efficacement un résultat de diff.

Ce guide explique comment lire un résultat de diff dans ses formats les plus courants, comment fonctionnent les fichiers patch et comment interpréter les changements en toute confiance.

Qu'est-ce qu'un résultat de diff ?

Un résultat de diff est une représentation structurée des différences entre deux fichiers ou ensembles de fichiers. L'utilitaire diff, créé par Douglas McIlroy aux Bell Labs dans les années 1970, reste le fondement de Git, Mercurial et de la plupart des autres systèmes de contrôle de version.

Lorsque vous exécutez git diff ou toute commande de diff, le résultat montre précisément ce qui a changé, où cela a changé et comment — dans un format lisible aussi bien par les humains que par les machines.

Comprendre le format de diff unifié

Le format de diff unifié est aujourd'hui le format de sortie le plus utilisé. Il regroupe les changements en hunks, chacun étant précédé de lignes de contexte qui vous aident à situer le changement dans le fichier.

Anatomie d'un en-tête de hunk

Chaque hunk commence par un en-tête qui ressemble à ceci :

@@ -start,count +start,count @@

Détaillons ceci :

| Partie | Signification | |------|---------| | @@ | Délimiteurs marquant le début d'un hunk | | -3,7 | Dans le fichier d'origine, ce hunk commence à la ligne 3 et s'étend sur 7 lignes | | +3,8 | Dans le nouveau fichier, ce hunk commence à la ligne 3 et s'étend sur 8 lignes | | @@ | Délimiteurs de fin |

La ligne de contexte juste après l'en-tête (généralement un nom de fonction ou un commentaire proche) vous aide à identifier à quelle partie du fichier appartient le changement.

Les lignes dans un hunk

Chaque ligne à l'intérieur d'un hunk est précédée d'un seul caractère :

 context line (unchanged)
-added line    (present in new file, absent in old)
+added line    (present in new file, absent in old)

• Lignes de contexte : elles commencent par un espace. Elles sont identiques dans les deux versions et fournissent des points de repère.
• Lignes supprimées : elles commencent par un signe moins (-). Elles existent dans l'ancien fichier mais ont été supprimées.
• Lignes ajoutées : elles commencent par un signe plus (+). Elles sont nouvelles dans le fichier modifié.

Exemple pratique

Voici un diff montrant une fonction en cours de modification :

@@ -5,7 +5,9 @@
 def greet(name):
-    print("Hello, " + name)
-    print("Welcome!")
+    message = f"Hello, {name}!"
+    print(message)
+    print("We are glad to see you.")
+
     if name == "admin":
         print("You have admin privileges.")

Lecture de ce diff :

• L'ancienne version affichait « Hello, » suivi du nom, puis « Welcome! ».
• La nouvelle version construit une chaîne de message formatée, l'affiche, ajoute une ligne de salutation supplémentaire et conserve inchangée la vérification admin.
• Deux lignes ont été supprimées (les lignes -), trois lignes ont été ajoutées (les lignes +), et la ligne + vide préserve une ligne vierge pour la lisibilité.

Fichiers patch : des diff que vous pouvez appliquer

Un fichier patch n'est rien d'autre qu'un diff enregistré dans un fichier — conventionnellement avec une extension .patch ou .diff. Les fichiers patch constituent un moyen portable de partager des changements sans partager l'intégralité du code source.

Créer un patch

Avec Git, créez un patch à partir de votre dernier commit :

git format-patch HEAD~1

Ou créez un patch à partir de changements non commités :

git diff > my-changes.patch

Appliquer un patch

Appliquez un patch à un dépôt cible :

git apply my-changes.patch

Ou utilisez la commande classique patch :

patch -p1 < my-changes.patch

L'option -p1 supprime la première composante de répertoire des chemins de fichiers, ce qui tient compte des différences de structure de répertoires entre le créateur du patch et la personne qui l'applique.

Formats courants de résultat de diff

Au-delà du diff unifié, vous pouvez rencontrer ces formats :

Diff normal

Le résultat par défaut de la commande diff d'origine. Les changements sont présentés comme des instructions pour modifier, ajouter ou supprimer des lignes à l'aide de commandes comme a (ajouter), c (modifier) et d (supprimer).

3c3
< Hello world
---
> Hello beautiful world

Diff contextuel

Un format plus ancien qui fournit trois lignes de contexte autour de chaque changement. Il utilise des points d'exclamation pour indiquer les lignes modifiées.

Diff côte à côte

Ce n'est pas un format de fichier unique — il affiche plutôt deux colonnes côte à côte. C'est courant dans les outils de diff graphiques et les vérificateurs de diff en ligne.

Lire un résultat de diff lors des revues de code

Lors de la revue d'une pull request, concentrez-vous sur ces éléments :

1. Les en-têtes de hunk : ils vous indiquent quels fichiers et fonctions sont concernés.
2. Le rapport entre lignes ajoutées et supprimées : un grand nombre de changements dans des fichiers critiques mérite une attention particulière.
3. Les lignes de contexte : elles montrent la logique environnante, ce qui vous aide à évaluer si le changement est correct.
4. Les changements d'espaces uniquement : de nombreux outils de diff les mettent en évidence différemment, car ils peuvent encombrer la revue.

Bonnes pratiques pour interpréter les diff

• Lisez les diff de haut en bas, fichier par fichier — cela correspond à l'ordre dans lequel les changements ont été effectués.
• Prêtez attention aux lignes de contexte inchangées près du code modifié ; elles révèlent la relation structurelle entre l'ancien et le nouveau code.
• Utilisez un outil prenant en charge la coloration syntaxique dans la vue diff — la couleur rend les motifs plus faciles à repérer.
• Lors de la revue de grands diff, commencez par les fichiers de test pour comprendre quel comportement l'auteur a voulu modifier.

Comprendre un résultat de diff est une compétence fondamentale pour le développement collaboratif. Une fois que vous êtes à l'aise pour lire les diff, vous naviguerez dans les revues de code, les conflits de fusion et les fichiers patch avec beaucoup plus de confiance.