Einen Salesforce-bewussten Git Merge Driver einrichten

Kurz gefasst: Ein Merge Driver ist ein Programm, das git anstelle seiner eigenen zeilenbasierten Zusammenführung aufruft, für die Dateimuster, die Sie benennen. Richten Sie einen auf Ihre Salesforce-Metadaten in .gitattributes aus, registrieren Sie ihn in der git-Konfiguration jedes Clones, und unabhängige XML-Knotenänderungen mergen von selbst, statt als Konfliktmarkierungen einzutreffen. Die Einstellung gilt pro Clone, braucht also einen Bootstrap-Schritt, und sie läuft nie beim Merge-Button Ihres Hosters.

Das hier ist die Einrichtungsanleitung, nicht die Auflösungsanleitung. Wenn Sie schon Konfliktmarkierungen vor sich haben, lesen Sie zuerst Salesforce-Metadatenkonflikte lösen, ohne die Arbeit anderer zu verlieren, und kommen Sie danach hierher zurück, um die nächste Runde zu verhindern.

Was macht ein Merge Driver wirklich?

Bei einem Drei-Wege-Merge braucht git drei Versionen einer Datei: den gemeinsamen Vorfahren, Ihre Seite und die eingehende Seite. Standardmäßig gleicht git sie Zeile für Zeile ab. Ein Merge Driver ersetzt diesen Schritt durch ein Kommando Ihrer Wahl, und git übergibt ihm die drei Versionen als temporäre Dateien.

Der Vertrag ist klein. Git setzt die Platzhalter in Ihre Kommandozeile ein:

• %O die gemeinsame Vorfahrenversion
• %A Ihre Version, und die Datei, in die der Driver das Ergebnis schreibt
• %B die eingehende Version
• %P der echte Pfad der gemergten Datei
• %L die Größe der Konfliktmarkierung

Exit 0, und git übernimmt den Inhalt von %A als sauberen Merge. Exit ungleich null, und git wertet es als Konflikt und überlässt %A einem Menschen. Das ist die gesamte Schnittstelle, und deshalb kann ein Salesforce-bewusster Driver so schlicht sein wie ein Skript, das beide Seiten als XML parst, die Kindknoten unter jedem Elternknoten vereinigt und nur dann aussteigt, wenn dasselbe Schlüsselelement auf beiden Seiten unterschiedliche Werte trägt.

Wie richtet man einen in git ein?

Zwei Dateien, und nur eine davon liegt in der Versionsverwaltung.

Registrieren Sie den Driver zuerst in der git-Konfiguration. Sie liegt in .git/config und ist lokal zum Clone:

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

Sagen Sie git dann, welche Dateien ihm gehören, in .gitattributes im Repo-Root. Diese Datei wird committet, jede Kollegin und jeder Kollege bekommt sie also:

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

Fangen Sie eng an. Nehmen Sie die zwei oder drei Metadatentypen auf, die die meisten Konflikte erzeugen, leben Sie einen Sprint damit, und weiten Sie die Muster danach aus. Ein Driver, der einen nie getesteten Typ still falsch behandelt, ist schlechter als der Konflikt, den er ersetzt hat.

Warum braucht jeder Clone eine Einrichtung, und wie automatisiert man das?

.gitattributes liegt in der Versionsverwaltung, merge.sfxml.driver nicht, und git weigert sich, ein Kommando auszuführen, das es nur aus einer geklonten Datei kennt. Diese Trennung ist bewusstes Sicherheitsdesign: ein Repository, das Sie klonen, kann Ihre Maschine nicht zu beliebigen Kommandos bringen.

Praktische Folge: wer die Einrichtung überspringt, bekommt keinen Fehler. Git fällt still auf den eingebauten Textmerge zurück, diese Person sieht Konfliktmarkierungen, alle anderen sehen saubere Merges. Lösen Sie das mit einem Bootstrap-Schritt, den sich niemand merken muss: committen Sie ein scripts/setup-merge-driver.sh, das die beiden git config-Kommandos ausführt, rufen Sie es aus dem Post-Install-Hook Ihres Paketmanagers auf, und lassen Sie es laut scheitern, wenn das Driver-Binary fehlt.

Welche Merges sieht der Driver nie?

Drei Lücken sollten Sie kennen, bevor Sie sich darauf verlassen:

• Serverseitige Merges. Der Merge-Button bei GitHub, GitLab oder Bitbucket läuft auf deren Infrastruktur, ohne Zugriff auf Ihre .git/config. Ein Pull Request, der auf Ihrem Rechner sauber mergen würde, kann dort trotzdem Konflikte melden. Der Ausweg ist der übliche: mergen Sie den Zielbranch lokal in Ihren Feature-Branch, wo der Driver läuft, und pushen Sie die Auflösung.
• Einseitige Änderungen. Git ruft einen Driver nur auf, wenn beide Seiten die Datei angefasst haben. Hat nur eine Seite sie geändert, übernimmt git diese Seite und Ihr Driver startet nie.
• Generiertes XML. Ein Driver kann Knoten vereinigen, aber er kann nicht wissen, dass zwei Flow-Versionen unvereinbare Logik beschreiben. Halten Sie *.flow-meta.xml aus Ihren Mustern heraus und lösen Sie diese im Flow Builder.

Gibt es eine Variante ohne Installation?

Ja, für die rein additiven Fälle. Git bringt einen eingebauten union-Driver mit, der alle Zeilen beider Seiten behält, und er braucht überhaupt keinen Config-Eintrag:

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

Er ist grob. Union-Merge hängt aneinander, statt zu entdoppeln: ein Knoten, den beide Branches ergänzt haben, landet zweimal, und die Datei kann ungültig zurückkommen. Setzen Sie ihn nur auf flache, rein additive Listen wie Custom Labels ein, und behalten Sie eine Deployment-Validierung in der CI, die auffängt, was schiefgeht. Behandeln Sie ihn als Übergangslösung, während Sie einen echten Driver prüfen, nicht als Ziel.

Driver, Plattform oder Auflösung am Pull Request?

Ein Merge Driver ist die günstigste und schmalste Schicht: er entfernt falsche Konflikte auf git-Ebene, auf Entwicklerrechnern, und tut nichts für Validierung oder Deployment. DevOps-Plattformen bauen semantisches Mergen mit einem visuellen Drei-Wege-Panel in die Pipeline ein, was die serverseitige Lücke schließt, die Auflösung aber an ihr Tooling bindet.

Serpent geht den dritten Weg und löst am Pull Request selbst auf. Serpent AI liest den Konflikt, schlägt eine Auflösung vor und wartet auf Ihre Review, bevor sie angewendet wird. So landet die Korrektur dort, wo der Merge wirklich passiert, statt auf dem Rechner, der zufällig richtig konfiguriert ist. Sehen Sie sich Serpent AI an, oder stöbern Sie in weiteren Evergreen-Playbooks zu Salesforce DevOps in den Serpent-Guides.

FAQ

Muss ich den Merge Driver selbst schreiben?

Nicht zwingend. Es gibt quelloffene Salesforce-XML-Merge-Driver, und jedes XML-bewusste Merge-Werkzeug lässt sich in ein zweizeiliges Shell-Skript packen, das den Vertrag %O %A %B erfüllt. Selbst bauen ist ein vertretbarer Nachmittag, wenn Ihre Metadaten eine ungewöhnliche Form haben.

Ändert ein Merge Driver bereits committete Dateien?

Nein. Er läuft nur während eines Merges, auf dem Merge-Ergebnis. Die Historie bleibt unangetastet, Sie können also einen hinzufügen und wieder entfernen, ohne etwas umzuschreiben.

Was passiert, wenn der Driver abstürzt?

Git wertet einen Exit ungleich null als ungelösten Konflikt und lässt die Markierungen stehen, ein kaputter Driver fällt also auf das Verhalten zurück, das Sie vorher hatten. Lassen Sie Ihren bei allem, was er nicht versteht, ungleich null beenden, statt zu raten.

Ersetzt das die Normalisierung von Metadaten beim Retrieve?

Nein, beides ergänzt sich gut. Eine normalisierte Elementreihenfolge verkleinert die Diffs schon, bevor git sie sieht, und der Driver übernimmt, was übrig bleibt. Nutzen Sie beides, wenn es geht.