Comment mettre en place un merge driver git conscient de Salesforce

En bref : Un merge driver est un programme que git appelle à la place de sa propre fusion ligne à ligne, pour les motifs de fichiers que vous désignez. Pointez-en un vers vos métadonnées Salesforce dans .gitattributes, déclarez-le dans la config git de chaque clone, et les changements de nœuds XML indépendants fusionnent seuls au lieu d'arriver sous forme de marqueurs de conflit. C'est un réglage par clone, il faut donc une étape d'amorçage, et il ne s'exécute jamais sur le bouton de fusion de votre hébergeur.

Ceci est le guide de mise en place, pas le guide de résolution. Si vous avez déjà des marqueurs de conflit sous les yeux, lisez d'abord Résoudre les conflits de métadonnées Salesforce sans perdre le travail de personne, puis revenez ici pour éviter la prochaine fournée.

Que fait vraiment un merge driver ?

Lors d'une fusion à trois voies, git a besoin de trois versions du fichier : l'ancêtre commun, votre côté et le côté entrant. Par défaut il les réconcilie ligne à ligne. Un merge driver remplace cette étape par une commande de votre choix, et git lui passe les trois versions sous forme de fichiers temporaires.

Le contrat est court. Git substitue les placeholders dans votre ligne de commande :

%O la version ancêtre commune
%A votre version, et le fichier où le driver doit écrire le résultat
%B la version entrante
%P le vrai chemin du fichier fusionné
%L la taille des marqueurs de conflit

Sortie 0 et git enregistre le contenu de %A comme une fusion propre. Sortie non nulle et git y voit un conflit et laisse %A à un humain. C'est toute l'interface, et c'est pourquoi un driver conscient de Salesforce peut se réduire à un script qui parse les deux côtés en XML, réunit les nœuds enfants sous chaque parent, et n'abandonne que lorsque le même élément clé porte des valeurs différentes de chaque côté.

Comment le configurer dans git ?

Deux fichiers, dont un seul est versionné.

D'abord, déclarez le driver dans la config git. Elle vit dans .git/config, local au clone :

git config merge.sfxml.name "Salesforce metadata XML merge"
git config merge.sfxml.driver "sf-xml-merge %O %A %B %P"

Ensuite, dites à git quels fichiers lui reviennent, dans .gitattributes à la racine du dépôt. Celui-là est commité, donc tous vos coéquipiers l'obtiennent :

force-app/**/*.profile-meta.xml      merge=sfxml
force-app/**/*.permissionset-meta.xml merge=sfxml
force-app/**/*.layout-meta.xml       merge=sfxml
force-app/**/*.translation-meta.xml  merge=sfxml

Commencez étroit. Ajoutez les deux ou trois types de métadonnées qui génèrent le plus de conflits, vivez avec pendant un sprint, puis élargissez les motifs. Un driver qui traite mal, en silence, un type que vous n'avez jamais testé vaut moins que le conflit qu'il remplace.

Pourquoi chaque clone doit-il être configuré, et comment l'automatiser ?

.gitattributes est versionné, merge.sfxml.driver ne l'est pas, et git refuse d'exécuter une commande qu'il ne connaît que par un fichier cloné. Cette séparation est un choix de sécurité délibéré : un dépôt que vous clonez ne peut pas faire exécuter des commandes arbitraires à votre machine.

Conséquence pratique : un coéquipier qui saute la configuration n'a aucune erreur. Git retombe silencieusement sur sa fusion textuelle et cette personne voit des marqueurs de conflit, tandis que tous les autres voient des fusions propres. Réglez cela avec une étape d'amorçage que personne n'a à retenir : commitez un scripts/setup-merge-driver.sh qui lance les deux commandes git config, appelez-le depuis le hook post-install de votre gestionnaire de paquets, et faites-le échouer bruyamment si le binaire du driver manque.

Quelles fusions le driver ne voit-il jamais ?

Trois angles morts à connaître avant de compter dessus :

Les fusions côté serveur. Le bouton de fusion de GitHub, GitLab ou Bitbucket tourne sur leur infrastructure, sans accès à votre .git/config. Une pull request qui fusionnerait proprement sur votre poste peut quand même y signaler des conflits. Le contournement est classique : fusionnez la branche cible dans votre branche de fonctionnalité en local, là où le driver tourne, et poussez la résolution.
Les changements d'un seul côté. Git n'invoque un driver que si les deux côtés ont touché le fichier. Si un seul côté l'a changé, git prend ce côté et votre driver ne démarre jamais.
Le XML généré. Un driver sait réunir des nœuds, mais il ne peut pas savoir que deux versions de Flow décrivent une logique incompatible. Gardez *.flow-meta.xml hors de vos motifs et résolvez-les dans Flow Builder.

Existe-t-il une version sans installation ?

Oui, pour les cas purement additifs. Git embarque un driver union intégré qui conserve toutes les lignes des deux côtés, et il ne demande aucune entrée de config :

force-app/**/labels/*.labels-meta.xml merge=union

Il est brutal. La fusion union concatène au lieu de dédupliquer : un nœud ajouté par les deux branches atterrit deux fois et le fichier peut revenir invalide. Réservez-le aux listes plates et purement additives comme les custom labels, et gardez une validation de déploiement en CI pour rattraper ses erreurs. Voyez-le comme une solution d'attente pendant que vous évaluez un vrai driver, pas comme la destination.

Driver, plateforme, ou résolution sur la pull request ?

Un merge driver est la couche la moins chère et la plus étroite : il supprime les faux conflits au niveau de git, sur les machines des développeurs, et ne fait rien pour la validation ni le déploiement. Les plateformes DevOps intègrent la fusion sémantique dans le pipeline avec un panneau visuel à trois voies, ce qui couvre l'angle mort côté serveur mais lie la résolution à leur outillage.

Serpent prend la troisième voie et résout sur la pull request elle-même. Serpent AI lit le conflit, propose une résolution et attend votre revue avant de l'appliquer, si bien que le correctif atterrit là où la fusion a vraiment lieu plutôt que sur le poste qui se trouve être bien configuré. Voyez Serpent AI, ou parcourez d'autres playbooks Salesforce DevOps evergreen dans les guides Serpent.

FAQ

Dois-je écrire le merge driver moi-même ?

Pas forcément. Des merge drivers XML Salesforce open source existent, et tout outil de fusion conscient du XML peut être enveloppé dans un script shell de deux lignes qui respecte le contrat %O %A %B. Écrire le vôtre reste une après-midi raisonnable si vos métadonnées ont une forme inhabituelle.

Un merge driver modifie-t-il des fichiers déjà commités ?

Non. Il ne tourne que pendant une fusion, sur le résultat fusionné. L'historique reste intact : vous pouvez en ajouter un puis le retirer sans rien réécrire.

Que se passe-t-il si le driver plante ?

Git traite une sortie non nulle comme un conflit non résolu et laisse les marqueurs en place : un driver cassé retombe donc sur le comportement que vous aviez avant. Faites en sorte que le vôtre sorte en erreur sur tout ce qu'il ne comprend pas, plutôt que de deviner.

Cela remplace-t-il la normalisation des métadonnées au retrieve ?

Non, et les deux se complètent. Normaliser l'ordre des éléments réduit les diffs avant même que git les voie, et le driver traite ce qui survit. Faites les deux si vous le pouvez.