git-range-diff - Comparer deux plages de commits (par exemple deux versions d’une branche)

Cette commande affiche les différences entre deux versions d’une série de rustines, ou plus généralement, entre deux plages de commits (en ignorant les commits de fusion).

En présence d’arguments <chemin>, ces plages de commits sont restreintes en conséquence.

À cette fin, elle recherche les paires de commits depuis les deux plages de commits qui se correspondent. Deux commit sont dits correspondre quand les diffs entres leurs rustines (c-à-d. les information d’auteur, les messages de commit et les diffs des commits) sont raisonnablement petites par rapport à la taille des rustines. Voir ``Algorithme`` ci-dessous pour plus de détails.

Enfin, la liste des commits en correspondance est affichée dans l’ordre de la deuxième plage de commits, avec les commits sans correspondance insérés après que tous leurs ancêtres ont été affichés.

Il existe trois moyens de spécifier les plages de commit :

git range-diff accepte aussi les options normales de diff (voir git-diff[1]), notablement les options --color=[<quand>] et --no-color. Ces options sont utilisées lors de la génération du " diff entre rustines", c-à-d pour comparer l’auteur, le message de validation et la diff de commits anciens/nouveaux correspondants. Il n’y a actuellement aucun moyen de bricoler la plupart des options de diff passées à git log lors de la génération de ces rustines.

La sortie de la commande range-diff est sujette à changement. Elle est destiné à être la production de porcelaine humainement lisible, pas quelque chose qui peut être utilisé à travers les versions de Git pour obtenir un range-diff textuellement stable (par opposition à quelque chose comme l’option --stable de git-patch-id[1]). Il n’y a pas d’équivalent de git-apply[1] pour range-diff, la sortie n’est pas destinée à être consommable par une machine.

C’est particulièrement vrai lors du passage d’options à diff. Actuellement, certaines options comme --stat peuvent, comme effet émergent, produire des sorties qui sont assez inutiles dans les contexte de range-diff. Des versions futures de range-diff peuvent apprendre à intercepter de telles options d’un manière spécifique à range-diff (c-à-d pour --stat produisant une sortie humaine qui résume comment les stats de diff ont changé).

Cette commande utilise les réglages diff.color.* et pager.range-diff (ce dernier activé par défaut). Voir git-config[1].

Quand un rebasage nécessite la résolution d’un conflit de fusion, comparer les modifications introduites par le rebasage directement après, en utilisant :

Une sortie typique de git range-diff ressemblerait à ceci  :

Dans cet exemple, il y a 3 commits anciens et 3 nouveaux, où le développeur a supprimé le 3^ème, en ajouté un nouveau avant les deux premiers, et a modifié le message de validation du 2^ème commit ainsi que son diff.

Lorsque la sortie va à un terminal, elle est codée en couleur par défaut, tout comme la sortie git diff' normale. En outre, la première ligne (ajout d'un commit) est verte, la dernière ligne (suppression d'un commit) est rouge, la deuxième ligne (avec une correspondance parfaite) est jaune comme l'en-tête de commit de la sortie de `git show, et la troisième ligne colore l’ancien commit en rouge, le nouveau en vert et le reste comme l’en-tête de commit git show.

Une diff naïve de diffs codée en couleur est en fait un peu difficile à lire, cependant, car elle colorie l’ensemble des lignes rouges ou vertes. La ligne qui a ajouté "Ce qui est inattendu" dans l’ancien commit, par exemple, est complètement rouge, même si l’intention de l’ancien commit était d’ajouter quelque chose.

Pour arranger cela, range utilise le mode --dual-color par défaut. Dans ce mode, la diff de diffs conservera les couleurs diff originales, et préfixera les lignes avec des marqueurs -/+ qui ont leur fond en rouge ou vert, pour rendre plus évident qu’ils décrivent comment la diff elle-même a changé.

L’idée générale est ceci : nous générons une matrice de coûts entre les commits dans les deux plages de commits, puis résolvons l’affectation la moins coûteuse.

La matrice de coûts est peuplée ainsi : pour chaque paire de commits, les deux diffs sont générés et le « diff des diffs » est généré, avec 3 lignes de contexte, puis le nombre de lignes dans ce diff est utilisé comme coût.

Pour éviter les faux positifs (par exemple lorsqu’une rustine a été enlevée, et qu’une rustine non liée a été ajoutée entre deux itérations de la même série de rustines), la matrice de coût est étendue pour permettre cela, en ajoutant des entrées à coût fixe pour les grosses suppressions/ajouts.

Exemple : supposons que les commits 1--2 sont la première itération d’une série de rustines et que A--C sont ceux de la deuxième itération. Supposons que A est un picorage de 2, et C est un picorage de 1 mais avec une petite modification (disons, une correction de frappe). Visualisons les commits comme un graphique bipartite :

Nous cherchons une « meilleure » explication de la nouvelle série à partir de l’ancienne. Nous pouvons représenter une « explication » comme un lien dans le graphe :

Cette explication est « gratuite » parce qu’il n’y avait pas de changement. De même C peut être expliqué en utilisant 1, mais cela vient à un certain coût c>0 en raison de la modification :

En termes mathématiques, ce que nous cherchons est une sorte de coût minimum bipartite correspondant ; 1 est égal à C à un certain coût, etc. Le graphe sous-jacent est en fait un graphe bipartite complet ; le coût que nous associons à chaque arête est la taille de la diff entre les rustines des deux commits. Pour expliquer aussi les nouveaux commits, nous présentons des nœuds vides des deux côtés :

Le coût d’une arête o--C est la taille de la diff c, modifiée d’un facteur d’adaptation qui devrait être inférieur à 100%. Une arête o--o est gratuite. Le facteur d’adaptation est nécessaire parce que même si 1 et`C` n’ont rien en commun, ils peuvent tout de même contenir des lignes vides et autres, rendant probablement l’affectation 1--C, o--o légèrement moins chère que 1--o, o--C même si 1 et C n’ont rien en commun. Avec le facteur d’adaptation, nous exigeons qu’une part plus importante soit commune pour considérer les rustines comme correspondantes.

Le temps total nécessaire au calcul de cet algorithme est le temps nécessaire au calcul de n+m diffs de commits, suivi de m*n diffs de rustines, plus le temps nécessaire au calcul de l’affectation de moindre coût entre n et m diffs. Git utilise un implantation de l’algorithme de Jonker-Volgenant pour résoudre le problème d’affectation, qui de complexité cubique. La correspondance trouvée dans ce cas ressemble à ceci :

git-log[1]

Fait partie de la suite git[1]

Cette page de manuel a été traduite par Jean-Noël Avila <jn.avila AT free DOT fr> et les membres du projet git-manpages-l10n. Veuillez signaler toute erreur de traduction par un rapport de bogue sur le site https://github.com/jnavila/git-manpages-l10n .