git diff

Ce que fait git diff

La commande git diff vous montre exactement ce qui a changé, ligne par ligne, entre deux sources de votre projet. Elle prend deux ensembles de données et affiche les différences sous la forme d'un patch.

Ces deux sources peuvent être n'importe quelle paire parmi : votre arbre de travail (les fichiers que vous modifiez actuellement), la zone de staging (l'index, ce que git add a capturé), et n'importe quel instantané validé. Comme toutes les autres commandes Git vous indiquent seulement *qu'*une modification a eu lieu, git diff est l'outil qui vous dit ce qui a changé avant que vous ne le stagiez ou ne le validiez.

Elle est couramment utilisée conjointement avec git status et git log pour inspecter l'état d'un dépôt git : git status liste les fichiers qui ont changé, et git diff affiche le contenu de ces modifications.

Quelles deux sources sont comparées

La forme de la commande détermine ce qui est comparé :

Un git diff nu affiche uniquement ce que vous n'avez pas encore stagé avec git add. C'est le piège le plus courant : si vous avez déjà exécuté git add, git diff paraît vide même si vous avez des modifications — utilisez git diff --staged pour les voir.

Lire la sortie de diff

Un diff comporte plusieurs parties distinctes. Les sections ci-dessous en construisent un et expliquent chaque ligne.

Format de sortie brut

Examinons les commandes ci-dessous pour créer un dépôt simple :

mkdir test_repo
cd test_repo
touch test.txt
echo "this is a git diff test example" > test.txt
git init .
#Initialized empty Git repository in /Users/kev/code/test/.git/
git add test.txt
git commit -am "add diff test file"
#[master (root-commit) 9e2dcac] add diff test file
#1 file changed, 1 insertion(+)
#create mode 100644 test.txt

Pour que git diff produise une sortie, vous devez modifier le contenu de test.txt après l'avoir validé. Exécutez la commande suivante :

echo "this is a diff example" > test.txt

Ce n'est qu'à ce moment que nous pouvons afficher un diff et discuter de sa sortie. L'exécution de git diff produira ce qui suit :

diff --git a/test.txt b/test.txt
index 6b0c6cf..b37e70a 100644
--- a/test.txt
+++ b/test.txt
@@ -1 +1 @@
-this is a git diff test example
+this is a diff example

Sources d'entrée du diff

La première ligne indique les deux sources comparées. Ici, a/test.txt (la version « avant ») et b/test.txt (la version « après ») sont passées au diff. Les préfixes a/ et b/ marquent toujours les deux côtés, même s'il s'agit du même fichier.

diff --git a/test.txt b/test.txt

Métadonnées

Cette ligne affiche les métadonnées internes de Git. Les deux nombres sont les hachages abrégés des objets (blobs) du fichier avant et après la modification, et 100644 est le mode du fichier (un fichier ordinaire non exécutable).

index 6b0c6cf..b37e70a 100644

Symboles de modification

Ces lignes attribuent un symbole à chaque source d'entrée du diff. Les lignes provenant de a/test.txt (l'original) sont marquées par ---, et les lignes provenant de b/test.txt (la nouvelle version) sont marquées par +++.

--- a/test.txt
+++ b/test.txt

Blocs de diff

Un diff ne montre pas l'intégralité du fichier — uniquement les régions modifiées. Chaque région de ce type est appelée un bloc (ou hunk). Les blocs comprennent quelques lignes inchangées de contexte environnant afin que vous puissiez voir où se situe la modification.

@@ -1 +1 @@
-this is a git diff test example
+this is a diff example

La première ligne est l'en-tête du bloc, encadrée par des symboles @@. Elle résume les plages de lignes concernées : -1 signifie « à partir de la ligne 1 de l'ancien fichier » et +1 signifie « à partir de la ligne 1 du nouveau fichier ». Sous l'en-tête, un - en début de ligne marque une ligne supprimée et un + en début de ligne marque une ligne ajoutée. Une ligne modifiée apparaît donc sous la forme d'une suppression suivie d'un ajout.

Options courantes

Git propose plusieurs options utiles pour différents flux de travail :

• --staged (ou --cached) : Compare les modifications stagées dans l'index avec le commit HEAD — ce qu'un git commit enregistrerait.
• --stat : Affiche un résumé condensé des fichiers modifiés (insertions/suppressions par fichier) au lieu du diff complet.
• --name-only : Affiche uniquement les noms des fichiers modifiés.
• --name-status : Comme --name-only, mais préfixe chaque fichier avec sa lettre de statut (M modifié, A ajouté, D supprimé).
• -w (ou --ignore-all-space) : Ignore les modifications portant uniquement sur les espaces blancs, ce qui est pratique lorsqu'une réindentation masque les vraies modifications.

Par exemple, pour obtenir un aperçu rapide de combien chaque fichier a changé :

git diff --stat
# test.txt | 2 +-
# 1 file changed, 1 insertion(+), 1 deletion(-)

Mettre en évidence les modifications

Pour les modifications au niveau des lignes, la sortie par défaut peut être bruyante, car Git affiche une ligne supprimée complète et une ligne ajoutée complète même lorsqu'un seul mot diffère. Les deux outils ci-dessous mettent en évidence les parties exactes qui ont changé.

git diff --color-words

La première méthode est un mode spécial intégré à git diff : --color-words. Il tokenise les lignes ajoutées et supprimées par espaces blancs, puis compare ces tokens, de sorte que seuls les mots modifiés sont colorés au lieu des lignes entières.

git diff --color-words
diff --git a/test.txt b/test.txt
index 6b0c6cf..b37e70a 100644
--- a/test.txt
+++ b/test.txt
@@ -1 +1 @@
-this is a git diff test example
+this is a diff example

(Remarque : --color-words met en évidence les modifications en ligne à l'aide des couleurs du terminal. En texte brut, le format de sortie correspond au diff standard.)

git diff-highlight

Lorsque vous clonez le code source de Git, un sous-répertoire appelé contrib est livré avec. Il contient des outils liés à Git, dont l'un est diff-highlight. Il met en évidence les parties modifiées au niveau des sous-mots, allant plus finement que --color-words. Notez que cet outil filtre l'entrée standard (vous lui passez un diff par pipe) et nécessite la coloration du terminal pour être visible.

git diff | git diff-highlight
diff --git a/test.txt b/test.txt
index 6b0c6cf..b37e70a 100644
--- a/test.txt
+++ b/test.txt
@@ -1 +1 @@
-this is a git diff test example
+this is a diff example

Diff sur des fichiers binaires

git diff peut être exécuté non seulement sur des fichiers texte, mais aussi sur des fichiers binaires. Par défaut, le résultat n'est pas très utile — Git vous indique seulement que le fichier a changé, pas comment :

git diff
# Binary files a/script.pdf and b/script.pdf differ

Git dispose d'une fonctionnalité qui vous permet de spécifier une commande shell pour convertir le contenu du fichier binaire en texte avant d'effectuer le diff. Une petite configuration est nécessaire. Tout d'abord, définissez un filtre textconv qui décrit comment convertir un certain type binaire en texte. Par exemple, l'utilitaire pdftohtml (disponible via Homebrew) peut transformer un PDF en HTML. Il y a deux endroits pour configurer cela : par dépôt dans .git/config, ou globalement dans ~/.gitconfig.

[diff "pdfconv"]
textconv=pdftohtml -stdout

Ensuite, reliez un ou plusieurs patterns de fichiers au filtre pdfconv en créant un fichier .gitattributes à la racine du dépôt :

*.pdf diff=pdfconv

Après cette configuration, git diff exécute d'abord chaque fichier binaire correspondant à travers le convertisseur et compare la sortie texte du convertisseur. En utilisant la même technique, vous pouvez obtenir des diffs lisibles à partir de nombreux formats binaires (zips, jars et autres archives).

Comparer un seul fichier

git diff accepte également un chemin de fichier explicite. Lorsqu'un chemin est passé, l'opération est limitée à ce seul fichier. Dans l'exemple ci-dessous, l'argument ./path/to/file compare les modifications dans le répertoire de travail avec le commit HEAD :

git diff HEAD ./path/to/file

Comparer toutes les modifications

Pour comparer les modifications dans l'ensemble du dépôt, exécutez git diff sans chemin de fichier. N'importe laquelle des formes ci-dessus peut être invoquée sans l'argument ./path/to/file pour appliquer la même comparaison à chaque fichier du dépôt local.

Modifications depuis le commit le plus récent

Un git diff nu compare le répertoire de travail avec la zone de staging (index), il n'affiche donc que les modifications non stagées. Pour voir toutes les modifications non validées depuis le commit le plus récent — à la fois stagées et non stagées — comparez avec HEAD :

git diff HEAD

Comparer deux commits

git diff accepte des références Git, telles que des noms de branches, des tags et des hachages de commits. Chaque commit possède un identifiant unique, que vous pouvez trouver avec git log. Passez deux identifiants de commit pour les comparer directement :

git diff <commit-hash-1> <commit-hash-2>

La sortie montre ce qui a changé en allant du premier commit vers le second.

Comparer des branches

Comparer des branches fonctionne comme n'importe quelle autre entrée de référence dans git diff. Il y a deux opérateurs à connaître.

L'opérateur à deux points compare les extrémités des deux branches :

git diff branch1..branch2

Vous obtenez le même résultat si les points sont omis et qu'un espace est utilisé entre les noms de branches. Il existe également un opérateur à trois points :

git diff branch1...branch2

L'opérateur à trois points base la comparaison sur l'historique commun : il remplace branch1 par l'ancêtre commun (base de fusion) des deux branches, tandis que la seconde entrée reste l'extrémité de branch2. En d'autres termes, branch1...branch2 répond à la question « que s'est-il passé sur branch2 depuis qu'elle a divergé de branch1 », ce qui est généralement ce que vous souhaitez lorsque vous examinez une branche de fonctionnalité avant un git merge.

Comparer un fichier entre deux branches

Pour comparer un fichier spécifique entre des branches, passez le chemin du fichier comme troisième argument :

git diff master new_branch ./test.txt

Commandes associées

• git status — voir quels fichiers ont changé avant d'utiliser git diff pour voir ce qui a changé en eux.
• git add — une fois qu'un diff semble correct, stagez-le ; ensuite, utilisez git diff --staged pour revoir ce qui est stagé.
• git commit — enregistrer les modifications stagées.
• git log — trouver les hachages de commits que vous passez à git diff <commit> <commit>.
• git show — afficher le diff introduit par un seul commit.

Pratique