Submodules, Subtrees oder Vendoring: drei Wege, ein anderes Repository einzubinden

Worum es geht

Drei Mechanismen bringen Code aus einem anderen Repository in das eigene:

• Submodule. Der Baum des Superprojekts enthält einen Gitlink-Eintrag mit der Commit-ID, auf die das Submodule stehen soll, und .gitmodules vermerkt Pfad und URL. Das Submodule behält seine eigene Historie und sein eigenes Git-Verzeichnis. Die Dokumentation hält fest, dass nach git submodule update der vermerkte Commit auf einem losgelösten HEAD ausgecheckt wird.
• Subtree. git subtree add --prefix=<dir> <repository> <ref> importiert die Dateien des anderen Projekts als gewöhnliche verfolgte Dateien in ein Unterverzeichnis; mit --squash wird statt der gesamten Historie nur ein einzelner Commit importiert. git subtree pull und git subtree push bewegen Änderungen in beide Richtungen. Das Handbuch betont, dass Subtrees keine besonderen Konstruktionen wie .gitmodules oder Gitlinks brauchen und Endnutzende zu nichts zwingen.
• Vendoring. Die Dateien kopieren, committen und die Upstream-Version, die Quell-URL und allfällige lokale Patches in eine Datei daneben schreiben (VENDOR.md oder eine Lock-Datei).

Warum es wichtig ist

Die Wahl entscheidet, wie ein frischer Klon aussieht, wie ein Upgrade durchgeführt wird und ob lokale Änderungen möglich sind. Submodules sind exakt, verlangen aber von allen, einschliesslich der CI, git clone --recurse-submodules oder git submodule update --init --recursive; wird das vergessen, entstehen leere Verzeichnisse. Subtrees und Vendoring erzeugen einen in sich geschlossenen Klon, auf Kosten einer fetteren Historie und einer weniger offensichtlichen Herkunft.

So wird es angewendet

• Einen Paketmanager bevorzugen, wenn es für die Sprache einen gibt; diese drei sind für Fälle gedacht, in denen keiner passt (gemeinsame Konfiguration, Assets, ein privater Fork).
• Submodules verwenden, wenn die Abhängigkeit gross ist, sich unabhängig ändert und auf einen genauen Commit festgenagelt sein muss, in dem auch selbst entwickelt wird.
• Subtrees verwenden, wenn Konsumierende es nicht wissen müssen und Upgrades gelegentlich sind (git subtree pull --squash hält die Historie kurz).
• Vendoring anwenden, wenn die Abhängigkeit klein und stabil ist; Version und Lizenz vermerken, damit die Kopie geprüft und aufgefrischt werden kann.
• Unabhängig von der Wahl den Upgrade-Befehl ins README schreiben und den Build in der CI aus einem frischen Klon ausführen.

Stolpersteine

Submodule-Commits, die ins Superprojekt, aber nicht ins Remote des Submodules gepusht werden, brechen jeden anderen Klon. Commits, die innerhalb eines Submodules auf dessen losgelöstem HEAD erstellt werden, liegen auf keinem Branch und gehen leicht verloren, sofern nicht zuerst ein Branch erstellt wird. Das Subtree-Handbuch verlangt Konsistenz bei --squash: Werden alle Merges gesquasht, muss auch split --rejoin gesquasht werden, sonst zeigt das Log eine Kopie jedes Commits. Vendorte Kopien driften still, wenn jemand sie patcht, ohne die Aufzeichnung zu aktualisieren.