Si seulement 1 arbre est spécifié, git read-tree fonctionne comme si l’utilisateur n’avait pas spécifié -m, sauf que si l’index original a une entrée pour un chemin donné, et que le contenu du chemin correspond à l’arbre en cours de lecture, les informations stat de l’index sont utilisées. (En d’autres termes, les stat() de l’index ont la priorité sur celles de l’arbre fusionné).

Cela signifie que si vous faites un git read-tree -m <nouvel-arbre> suivi d’un git checkout-index -f -u -a, git checkout-index n’extrait que les éléments qui ont vraiment changé.

Ceci est utilisé pour éviter les faux positifs inutiles quand git diff-files est exécuté après git read-tree.

Typiquement, ceci est invoqué comme git read-tree -m $H $M, où $H est le commit de tête du dépôt actuel, et $M est la tête d’un arbre étranger, qui est simplement en avance sur $H (c’est-à-dire que nous sommes dans une situation d’avance rapide).

Quand deux arbres sont spécifiés, l’utilisateur indique à git read-tree ce qui suit :

Dans ce cas, la commande git read-tree -m $H $M s’assure qu’aucune modification locale n’est perdue à la suite de cette « fusion ». Voici les règles de « report en avant », où « I » désigne l’index, « clean » signifie que l’index et l’arbre de travail coïncident, et « exists »/« nothing » font référence à la présence d’un chemin dans le commit spécifié :

Dans tous les cas « garder l’index », l’entrée d’index reste telle qu’elle était dans le fichier d’index original. Si l’entrée n’est pas à jour, git read-tree garde la copie dans l’arbre de travail intacte lors du fonctionnement avec l’option -u.

Quand cette forme de git read-tree retourne avec succès, vous pouvez voir lesquelles des « modifications locales » que vous avez faites ont été reportées en exécutant git diff-index --cached $M. Notez que cela ne correspond pas nécessairement à ce que git diff-index --cached $H aurait produit avant une telle fusion à deux arbres. Ceci est dû aux cas 18 et 19 — si vous aviez déjà les modifications dans $M (par exemple si vous les avez récupérées par courriel sous forme de patch), git diff-index --cached $H vous aurait informé de la modification avant cette fusion, mais cela n’apparaîtrait pas dans la sortie de git diff-index --cached $M après la fusion à deux arbres.

Le cas 3 est légèrement délicat et nécessite une explication. Le résultat de cette règle devrait logiquement être de supprimer le chemin si l’utilisateur a indexé la suppression du chemin puis bascule vers une nouvelle branche. Cela empêcherait cependant l’extraction initiale de se produire, donc la règle est modifiée pour utiliser M (le nouvel arbre) uniquement quand le contenu de l’index est vide. Sinon, la suppression du chemin est conservée tant que $H et $M sont identiques.

Chaque entrée « d’index » possède deux bits d’état de « phase ». La phase 0 est la normale, et c’est la seule que vous verriez dans tout usage normal.

Cependant, quand vous faites git read-tree avec trois arbres, la « phase » commence à 1.

Cela signifie que vous pouvez faire

et vous vous retrouverez avec un index contenant toutes les entrées de <arbre1> en « phase1 », toutes les entrées de <arbre2> en « phase2 » et toutes les entrées de <arbre3> en « phase3 ». Lors d’une fusion d’une autre branche dans la branche courante, on utilise l’arbre ancêtre commun comme <arbre1>, la tête de la branche courante comme <arbre2>, et la tête de l’autre branche comme <arbre3>.

De plus, git read-tree possède une logique de cas particulier qui dit : si vous voyez un fichier qui correspond sous tous les aspects dans les états suivants, il « s’effondre » en « phase0 » :

La commande git write-tree refuse d’écrire un arbre absurde, et se plaindra des entrées non fusionnées si elle voit une seule entrée qui n’est pas en phase 0.

OK, tout cela ressemble à un ensemble de règles totalement absurdes, mais c’est exactement ce que vous voulez pour effectuer une fusion rapide. Les différentes phases représentent l'« arbre résultat » (phase 0, alias « merged »), l’arbre original (phase 1, alias « orig »), et les deux arbres que vous essayez de fusionner (phases 2 et 3 respectivement).

L’ordre des phases 1, 2 et 3 (et donc l’ordre des trois arguments <arbre-esque> en ligne de commande) est important quand vous démarrez une fusion à 3 sens avec un fichier d’index déjà rempli. Voici un aperçu du fonctionnement de l’algorithme :

Vous utiliseriez normalement git merge-index avec le git merge-one-file fourni pour effectuer cette dernière étape. Le script met à jour les fichiers dans l’arbre de travail au fur et à mesure qu’il fusionne chaque chemin et à la fin d’une fusion réussie.

Quand vous démarrez une fusion à 3 sens avec un fichier d’index déjà rempli, il est supposé qu’il représente l’état des fichiers dans votre arbre de travail, et vous pouvez même avoir des fichiers avec des modifications non enregistrées dans le fichier d’index. Il est de plus supposé que cet état est « dérivé » de l’arbre de phase 2. La fusion à 3 sens refuse de s’exécuter si elle trouve une entrée dans le fichier d’index original qui ne correspond pas à la phase 2.

Ceci est fait pour vous empêcher de perdre vos modifications en cours, et de mélanger vos modifications aléatoires dans un commit de fusion sans rapport. Pour illustrer, supposons que vous partiez de ce qui a été commis en dernier dans votre dépôt :

Vous faites des modifications aléatoires, sans exécuter git update-index. Et puis vous remarquez que le sommet de votre arbre « amont » a avancé depuis que vous avez tiré depuis lui :

Votre arbre de travail est toujours basé sur votre HEAD ($JC), mais vous avez quelques modifications depuis. La fusion à trois sens s’assure que vous n’avez pas ajouté ou modifié d’entrées d’index depuis $JC, et si c’est le cas, fait ce qu’il faut. Donc avec la séquence suivante :

ce que vous valideriez serait un commit pur entre $JC et $LT sans vos modifications en cours, et votre arbre de travail serait mis à jour avec le résultat de la fusion.

Cependant, si vous avez des modifications locales dans l’arbre de travail qui seraient écrasées par cette fusion, git read-tree refusera de s’exécuter pour empêcher la perte de vos modifications.

En d’autres termes, il n’est pas nécessaire de s’inquiéter de ce qui n’existe que dans l’arbre de travail. Quand vous avez des modifications locales dans une partie du projet qui n’est pas impliquée dans la fusion, vos modifications n’interfèrent pas avec la fusion et sont conservées intactes. Quand elles interfèrent effectivement, la fusion ne démarre même pas (git read-tree se plaint bruyamment et échoue sans rien modifier). Dans ce cas, vous pouvez simplement continuer ce que vous étiez en train de faire, et quand votre arbre de travail est prêt (c’est-à-dire que vous avez terminé votre travail en cours), tentez à nouveau la fusion.