7.11 Git Tools - Submodule

Das Einfachste bei der Verwendung von Submodulen in einem Projekt, ist ein Subprojekt nur zu benutzen und gelegentlich Aktualisierungen zu erhalten, die aber nichts an deinem Checkout ändern. Gehen wir ein einfaches Beispiel durch.

Wenn du in einem Untermodul nach neuen Inhalten suchen willst, kannst du ins entsprechende Verzeichnis gehen und git fetch und git merge auf dem Upstream-Branch ausführen, um den lokalen Code zu aktualisieren.

Wenn du nun zurück in das Hauptprojekt gehst und git diff --submodule ausführst, kannst du sehen, dass das Submodul aktualisiert wurde und erhältst eine Liste der Commits, die ihm hinzugefügt wurden. Um nicht jedes Mal, wenn du git diff ausführst, --submodule einzugeben, kannst du es als Standardformat festlegen, indem du den Konfigurationswert diff.submodule auf „log“ setzen.

Wenn du nun committest, zwingst du das submodule neuen code zu zu beinhalten, wenn andere Personen ihn updaten.

Es gibt auch einen einfacheren Weg, das zu erreichen. Falls du es vorziehst, nicht manuell in das Unterverzeichnis zu fetchen und zu mergen. Wenn du git submodule update --remote ausführst, wird Git in dein Submodul wechseln und die Aktualisierung abholen und durchführen.

Dieser Befehl geht standardmäßig davon aus, dass du den Checkout auf den default branch des entfernten Submodul-Repositorys aktualisieren möchtest (derjenige, auf den HEAD auf remote zeigt). Du kannst es, sofern du möchtest, auch anders konfigurieren. Wenn du beispielsweise möchtest, dass das DbConnector-Submodul den Branch „stable“ dieses Repositorys tracken soll, dann kannst du es entweder in deiner .gitmodules Datei eintragen (damit jeder andere es auch trackt) oder es einfach in deiner lokalen .git/config Datei setzen. Lass es uns in der .gitmodules Datei einrichten:

Wenn du die Option -f .gitmodules weglässt, wird die Änderung nur für dich vorgenommen. Es ist aber wahrscheinlich sinnvoller, diese Informationen im Repository zu speichern, damit alle anderen es genauso machen.

Wenn wir hier git status ausführen, wird Git uns anzeigen, dass wir „neue Commits“ im Submodul haben.

Wenn du die Konfigurationseinstellung status.submodulesummary setzt, zeigt dir Git auch eine kurze Übersicht der Änderungen in den Submodulen an:

Sobald du jetzt git diff ausführst, kannst du erkennen, dass sowohl unsere .gitmodules Datei modifiziert wurde und dass es eine Reihe von Commits gibt, die wir gepullt haben und die bereit sind, an unser Submodul-Projekt committet zu werden.

Das ist ziemlich beeindruckend, denn wir können das Log-Protokoll der Commits sehen, die wir in unserem Submodul vornehmen wollen. Nach dem erfolgten Commit kannst du diese Informationen auch nachträglich anzeigen lassen, indem du git log -p aufrufst.

Standardmäßig wird Git versuchen, alle Submodule zu aktualisieren, wenn du git submodule update --remote ausführst. Wenn du viele Submodule hast, solltest du also den genauen Namen des Submoduls angeben, das du gerade aktualisieren möchtest.

Lass uns nun aus Sicht deiner Mitstreiters agieren, der einen eigenen lokalen Klon des Hauptprojekt-Repositorys besitzt. Einfach nur git pull auszuführen, um die von dir eingereichten Änderungen abzurufen, wird nicht ausreichen:

Der Befehl git pull holt standardmäßig rekursiv die Änderungen der Submodule, wie wir in der Ausgabe des ersten Befehls oben sehen können. Er aktualisiert die Submodule jedoch nicht. Dies wird durch die Ausgabe des git status Befehls gezeigt, aus dem hervorgeht, dass das Submodul „modifiziert“ ist und „neue Commits“ enthält. Außerdem zeigen die spitzen Klammern der neuen Commits nach links (<) und bedeuten, dass diese Commits im Hauptprojekt, aber nicht im lokalen Checkout von DbConnector vorhanden sind. Um das Update abzuschließen, musst du git submodule update ausführen:

Sicherheitshalber solltest du git submodule update mit dem --init Flag ausführen. Für den Fall, dass das Hauptprojekt einen Commit durchführt, bei dem du gerade neue Submodule hinzugefügt hast. Wenn ein Submodul verschachtelte Submodule enthält, solltest du das --recursive Flag setzen.

Wenn du diesen Prozess automatisieren möchtest, kannst du das Flag --recurse-submodules zum Befehl git pull hinzufügen (seit Git 2.14). Dadurch wird Git dazu veranlasst git submodule update direkt nach dem Pull-Kommando zu starten, wodurch die Submodule in die korrekte Version versetzt werden. Wenn du in Git immer mit dem Flag --recurse-submodules pullen willst, kannst du die Konfigurations-Option submodule.recurse auf true setzen (dies funktioniert für git pull seit Git 2.15). Diese Option bewirkt, dass Git das Flag --recurse-submodules für alle Befehle verwendet, die es unterstützen (außer clone).

Es gibt eine besondere Situation, die beim Abrufen von Aktualisierungen des Hauptprojekts auftreten kann: Es könnte sein, dass das Upstream-Repository die URL des Submoduls in der Datei .gitmodules in einem der von dir abgerufenen Commits geändert hat. Das kann zum Beispiel passieren, wenn das Submodul-Projekt seine Hosting-Plattform ändert. In diesem Fall ist es möglich, dass git pull --recurse-submodules oder git submodule update fehlschlägt, wenn das Hauptprojekt auf einen Submodul-Commit verweist, der nicht in dem lokal konfigurierten Submodul in deinem Repository gefunden wird. Um diese Situation zu beheben, ist der Befehl git submodule sync erforderlich:

Wahrscheinlich verwendest du Submodule, weil du gleichzeitig am Code im Submodul und im Hauptprojekt (oder modulübergreifend in mehreren Submodulen) arbeiten willst. Andernfalls würdest du wahrscheinlich stattdessen ein einfacheres System zur Verwaltung von Abhängigkeiten (wie Maven oder Rubygems) verwenden.

Betrachten wir nun ein Beispiel, bei dem Änderungen am Submodul gleichzeitig mit dem Hauptprojekt vorgenommen werden und diese Änderungen zur gleichen Zeit committed und veröffentlicht werden.

Wenn wir bisher den Befehl git submodule update ausgeführt haben, um Änderungen aus den Submodul-Repositorys zu holen, würde Git die Änderungen erhalten und die Dateien im Unterverzeichnis aktualisieren, aber das Sub-Repository in einem sogenannten "detached HEAD" Status belassen. Das bedeutet, dass es keinen lokalen Arbeits-Branch (wie z.B. den master) gibt, der die Änderungen trackt. Ohne einen Arbeits-Branch verändert sich die Nachverfolgung, d.h. selbst wenn du Änderungen an das Untermodul committest, gehen diese Änderungen möglicherweise verloren, wenn du das nächste Mal git submodule update ausführst. Du musst einige zusätzliche Schritte ausführen, wenn du willst, dass diese Änderungen in einem Submodul getrackt werden.

Um dein Submodul so einzurichten, dass du es leichter kannst, musst du zwei Dinge tun. Du musst in jedes Submodul gehen und einen Branch auschecken, an dem du arbeiten willst. Dann musst du Git mitteilen, was zu tun ist, wenn du Änderungen vorgenommen hast. Anschließend pullt der Befehl git submodule update --remote neue Daten vom Upstream. Die Optionen sind, dass du diese entweder in deine lokale Bearbeitung mergst oder du kannst deine lokale Arbeit auf die neuen Änderungen rebasen.

Gehen wir zunächst in unser Submodul-Verzeichnis und wechseln in einen Branch.

Versuchen wir, unser Submodul mit der Option „merge“ zu aktualisieren. Wenn du es manuell starten möchtest, können wir einfach die Option --merge zu unserem update Aufruf hinzufügen. Wir erkennen hier, dass es eine Änderung auf dem Server für dieses Submodul gegeben hat und es wird zusammengeführt.

Das Verzeichnis DbConnector hat die neuen Änderungen bereits in unserem lokalen stable Branch gemerged. Jetzt wollen wir beobachten, was passiert, wenn wir unsere eigene lokale Änderung an der Bibliothek vornehmen und jemand anderes gleichzeitig eine andere Änderung im Upstream-Bereich vornimmt.

Bei der Aktualisierung unseres Submoduls erfahren wir jetzt, was passiert, wenn wir eine lokale Änderung vorgenommen haben und auch im Upstream-Bereich eine Änderung vorliegt, die wir einbauen müssen.

Wenn du --rebase oder --merge vergessen hast, wird Git einfach das Submodul auf das aktualisieren, was auch immer auf dem Server vorhanden ist und dein Projekt in einen abgekoppelten (engl. detached) HEAD-Zustand zurücksetzen.

Wenn das passiert, brauchst du dir keine Sorgen zu machen. Du kannst einfach ins Verzeichnis zurückgehen und deinen Branch wieder auschecken (der immer noch deine Arbeit enthält) und origin/stable (oder welchen Remote-Branch auch immer) manuell mergen oder rebasen.

Solltest du deine Änderungen nicht in deinem Submodul committed haben und ein Submodul-Update ausführen, das Probleme verursachen würde, holt Git die gemachten Änderungen, überschreibt aber nicht die ungesicherte Arbeit in deinem Submodul-Verzeichnis.

Wenn du Änderungen vorgenommen hast, die mit einer Änderung im Upstream-Bereich in Konflikt stehen, wird Git dich darüber informieren, sobald du das Update ausführst.

Du kannst in das Submodul-Verzeichnis wechseln und den Konflikt wie gewohnt beheben.

Wir haben jetzt einige Änderungen in unserem Submodul-Verzeichnis gemacht. Einige davon wurden von unseren Updates aus dem Upstream-Bereich eingebracht, andere wurden lokal vorgenommen und stehen noch niemandem zur Verfügung, da wir sie noch nicht gepusht haben.

Wenn wir im Hauptprojekt einen Commit machen und ihn nach pushen, ohne gleichzeitig die Änderungen an den Submodulen zu pushen, werden andere Entwickler, die versuchen, unsere Änderungen zu überprüfen, in Schwierigkeiten geraten, da sie keine Möglichkeit haben, die davon abhängigen Änderungen an den Submodulen zu erhalten. Diese Änderungen werden nur auf unserer lokalen Kopie existieren.

Um sicherzustellen, dass dies nicht passiert, kannst du Git auffordern, zu überprüfen, ob alle deine Submodule ordnungsgemäß gepusht wurden, bevor du das Hauptprojekt pushst. Der Befehl git push übernimmt das Argument --recurse-submodules, das entweder auf „check“ oder „on-demand“ (dt. bei Bedarf) gesetzt werden kann. Die Option „check“ lässt push einfach fehlschlagen, wenn eine der eingereichten Submodul-Änderungen noch nicht gepusht wurde.

Wie du feststellen kannst, erhalten wir dadurch auch einige hilfreiche Tipps, was wir als nächstes tun könnten. Die einfache Lösung besteht darin, in jedes Submodul zu wechseln und manuell auf den Remote zu pushen. So stellst du sicher, dass die Submodule extern verfügbar sind. Danach kann man diesen Push erneut versuchen. Wenn du möchtest, dass dieses Verhalten für alle Pushs durchgeführt wird, kannst du dieses Vorgehen zur Standardeinstellung machen. Dazu musst du den Befehl git config push.recurseSubmodules check ausführen.

Die andere Möglichkeit ist die Verwendung der Option „on-demand“, die das für dich erledigt.

Wie du oben sehen konntest, ist Git in das DbConnector-Modul gewechselt und hat es gepusht, bevor das Hauptprojekt gepusht wurde. Wenn dieser Push des Submoduls aus irgendeinem Grund fehlschlägt, wird auch der Push des Hauptprojekts fehlschlagen. Du kannst dieses Verhalten zur Standardeinstellung machen, indem du git config push.recurseSubmodules on-demand ausführst.

Wenn du die Referenz eines Submoduls gleichzeitig mit anderen Personen änderst, könntest du auf Probleme stoßen. Sollten die Historien der Submodule divergieren und du dorthin zu einem Hauptprojekt mit divergierenden Branches committed haben, kann es schwierig sein, das zu beheben.

Ist einer der Commits ein direkter Vorgänger des anderen (ein fast-forward Merge), dann wählt Git einfach den letzteren für den Merge aus, so dass das gut funktioniert.

Git wird nicht einmal einen trivialen Merge versuchen. Wenn die Submodule Commits divergieren und gemerged werden müssen, erhältst du folgende Ausgabe:

Im Wesentlichen ist hier Folgendes passiert: Git hat herausgefunden, dass die beiden Branches, im Verlauf der Submodule, Einträge aufzeichnen, die voneinander abweichen und gemerged werden müssen. Es erklärt es als „merge following commits not found“ (Merge nach Commits nicht gefunden), was erstmal verwirrend erscheint. Wir werden gleich erklären, warum das so passiert.

Um das Problem zu lösen, musst du ermitteln, in welchem Status sich das Submodul befinden sollte. Merkwürdigerweise liefert Git hier nicht wirklich viele Informationen, die dir helfen können, nicht einmal die SHA-1s der Commits beider Seiten der Historie. Glücklicherweise ist es aber ganz leicht, das herauszufinden. Wenn du git diff ausführst, kannst du die SHA-1s der Commits der beiden Branches, die du zusammenführen willst, anzeigen lassen.

In diesem Fall ist eb41d76 der Commit in unserem Submodul, den wir hatten, und c771610 ist der Commit, den der Upstream hatte. Wenn wir in unser Submodul-Verzeichnis gehen, sollte es bereits eb41d76 enthalten, da es durch den Merge nicht angetastet wurde. Sollte das aus irgendeinem Grund nicht der Fall sein, kannst du einfach einen neuen Branch erstellen und auschecken, der auf dieses Verzeichnis zeigt.

Wichtig ist der SHA-1 des Commits von der Gegenseite. Diesen wirst du mergen und auflösen müssen. Du kannst entweder direkt versuchen, den Merge mit dem SHA-1 durchzuführen oder du kannst einen Branch dafür erstellen und dann versuchen, diesen zu mergen. Wir empfehlen letzteres – und sei es nur, um eine bessere Merge-Commit-Meldung zu erhalten.

Wir werden also in unser Submodul-Verzeichnis wechseln, einen Branch namens „try-merge“, basierend auf diesem zweiten SHA-1 aus git diff erstellen und manuell mergen.

Wir haben hier einen echten Merge-Konflikt. Wenn wir diesen lösen und beheben, dann können wir das Hauptprojekt einfach mit dem Resultat updaten.

Es kann etwas verwirrend sein, aber es ist eigentlich nicht sehr schwer.

Interessanterweise gibt es einen weiteren Fall, den Git handhaben kann. Wenn ein Merge-Commit im Submodul-Verzeichnis existiert, der beide Commits in seinem Verlauf enthält, wird Git dir dies als mögliche Lösung vorschlagen. Git sieht, dass irgendwann im Submodul-Projekt jemand Branches gemerged hat, die diese beiden Commits enthalten. Möglicherweise möchtest du also diesen einen haben wollen.

Deshalb lautete die Fehlermeldung von vorhin „merge following commits not found“, weil dies nicht möglich war. Es ist verwirrend, denn wer würde erwarten, dass es das versucht?

Wenn Git einen einzelnen, akzeptablen Merge-Commit findet, siehst du wahrscheinlich Folgendes:

Der von Git vorgeschlagene Befehl wird den Index aktualisieren, als ob du git add (was den Konflikt aufhebt) und dann commit ausführen würdest. Allerdings solltest du das nicht tun. Du kannst genauso einfach in das Submodul-Verzeichnis wechseln, den Unterschied prüfen, zu diesem Commit springen, ihn ordnungsgemäß testen und ihn dann committen.

Damit wird dasselbe erreicht, aber zumindest kannst du auf diese Weise überprüfen, ob es wirklich funktioniert und du hast den Code in deinem Submodul-Verzeichnis, wenn du fertig bist.

Es gibt das Submodul-Kommando foreach, um in jedem Submodul ein beliebiges Kommando auszuführen. Das kann wirklich hilfreich sein, wenn du mehrere Submodule im gleichen Projekt hast.

Nehmen wir zum Beispiel an, wir wollen ein neues Feature starten oder einen Bugfix durchführen und arbeiten an mehreren Submodulen. Wir können leicht die gesamte Arbeit in all unseren Submodulen stashen.

Dann können wir einen neuen Branch erstellen und von allen unseren Submodulen zu diesem wechseln.

Du verstehst die Idee dahinter? Eine wirklich sinnvolle Methode, die dir hilft, ein gutes, einheitliches Diff zwischen den Änderungen in deinem Hauptprojekt und all deinen Subprojekten zu erstellen.

Hier kannst du sehen, dass wir eine Funktion in einem Submodul definieren und sie im Hauptprojekt aufrufen. Das ist natürlich ein vereinfachtes Beispiel, aber es gibt dir hoffentlich eine Vorstellung davon, wie hilfreich das sein könnte.

Vielleicht möchtest du Aliase für manche dieser Befehle einrichten, da sie ziemlich lang sein können. Du kannst für die meisten dieser Befehle keine Konfigurationsoptionen festlegen, um sie zu Standardeinstellungen zu machen. Wir haben die Einrichtung von Git-Aliasen in Git Aliases behandelt. Hier ist ein Beispiel dafür, was du vielleicht einrichten solltest, wenn du viel mit Submodulen in Git arbeiten willst.

Auf diese Weise kannst du einfach git supdate ausführen, wenn du deine Submodule aktualisieren willst. Oder du kannst git spush nutzen, um einen Push mit der Überprüfung der Submodul-Abhängigkeiten durchzuführen.

So kann beispielsweise das Wechseln von Branches mit darin enthaltenen Submodulen bei älteren Git-Versionen (vor Git 2.13) etwas knifflig sein. Wenn du einen neuen Branch erstellst, dort ein Submodul hinzufügst und dann wieder zu einem Branch ohne dieses Submodul wechselst, hast du darin das Submodul-Verzeichnis immer noch als ungetracktes Verzeichnis:

Das Entfernen des Verzeichnisses ist nicht schwierig, aber es kann etwas verwirrend sein, was darin enthalten ist. Wenn du es entfernst und dann wieder zum Branch wechselst, der dieses Submodul besitzt, musst du submodule update --init ausführen, um es neu zu befüllen.

Auch das ist nicht wirklich schwierig. Aber auch das kann ein wenig verwirrend sein.

Neuere Git-Versionen (ab Git 2.13) vereinfachen das alles, indem sie das Flag --recurse-submodules zum Befehl git checkout hinzufügen, der sich darum kümmert, die Submodule in den richtigen Zustand für den Branch zu bringen, auf den wir wechseln.

Die Verwendung des Flags --recurse-submodules mit git checkout kann auch praktisch sein, wenn du auf mehreren Branches im Hauptprojekt arbeitest, wobei jedes deiner Submodule auf unterschiedliche Commits zeigt. Wenn du zwischen den Branches wechselst, die das Submodul bei verschiedenen Commits enthalten, wird das Submodul bei der Ausführung von git status als „modifiziert“ erscheinen und „neue Commits“ anzeigen. Das liegt daran, dass der Submodul-Status beim Wechseln der Branches standardmäßig nicht mit übertragen wird.

Das kann äußerst verwirrend sein, deshalb ist es besser, immer den Befehl git checkout --recurse-submodules zu verwenden, wenn dein Projekt Submodule hat. Für ältere Git-Versionen, die das Flag --recurse-submodules nicht kennen, verwende nach dem Auschecken git submodule update --init --recursive, um die Submodule in den richtigen Zustand zu versetzen.

Glücklicherweise kannst du Git (≥2.14) anweisen, immer das Flag --recurse-submodules zu verwenden, indem du die Konfigurationsoption submodule.recurse setzt mit: git config submodule.recurse true. Wie oben schon erwähnt, wird das auch dazu führen, dass Git in Submodulen jeden Befehl entsprechend umwandelt, der eine --recurse-submodules Option hat (außer bei git clone).

Die andere Falle, in die viele Anwender tappen, ist der Wechsel von Unterverzeichnissen zu Submodulen. Wenn du Dateien in deinem Projekt getrackt hast und sie in ein Submodul verschieben willst, musst du vorsichtig sein. Anderenfalls wird Git dir das nicht verzeihen. Angenommen, du hast Dateien in einem Unterverzeichnis deines Projekts und willst sie in ein Untermodul verschieben. Wenn du das Unterverzeichnis löschen und dann submodule add ausführst, wird Git dich in etwa so ausschimpfen:

Du musst zuerst das CryptoLibrary Verzeichnis aus der Staging-Area unstagen. Danach kkannst du das Submodul hinzufügen:

Nehmen wir jetzt an, du hast das in einem Branch getan. Wenn du versuchst, wieder zu einem Branch zu wechseln, in der sich diese Dateien noch im aktuellen Verzeichnisbaum und nicht in einem Submodul befinden, erhältst du diesen Fehler:

Du kannst den Wechsel mit checkout -f erzwingen, aber achte darauf, dass dort keine ungesicherten Änderungen enthalten sind, da diese mit dem Befehl überschrieben werden könnten.

Wenn du zurückwechselst, erhältst du aus bestimmten Gründen ein leeres CryptoLibrary Verzeichnis. Auch ein git submodule update kann es dann nicht beheben. Möglicherweise musst du in dein Submodul-Verzeichnis gehen und git checkout . ausführen, um alle deine Dateien zurück zu bekommen. Du kannst das mit einem submodule foreach Skript erledigen, um es für mehrere Submodule anzuwenden.

Es ist wichtig zu wissen, dass Submodule heutzutage alle ihre Git-Daten im .git Verzeichnis des Hauptprojekts speichern. So gehen im Gegensatz zu vielen älteren Git-Versionen, mit dem Löschen eines Submodul-Verzeichnisses keine Commits oder Branches verloren, die du zuvor schon hattest.

Mit diesen Werkzeugen können Submodule eine ziemlich einfache und effektive Methode sein, um an mehreren verwandten, aber dennoch unterschiedlichen Projekten gleichzeitig zu arbeiten.