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 Ihrem Checkout ändern. Gehen wir ein einfaches Beispiel durch.

Wenn Sie in einem Untermodul nach neuen Inhalten suchen wollen, können Sie in das Verzeichnis gehen und git fetch und git merge auf dem Upstream-Branch ausführen, um den lokalen Code zu aktualisieren.

Wenn Sie nun zurück in das Hauptprojekt gehen und git diff --submodule ausführen, können Sie sehen, dass das Submodul aktualisiert wurde und erhalten eine Liste der Commits, die ihm hinzugefügt wurden. Um nicht jedes Mal, wenn Sie git diff ausführen, --submodule einzugeben, können Sie es als Standardformat festlegen, indem Sie den Konfigurationswert diff.submodule auf „log“ setzen.

Sollten Sie zu diesem Zeitpunkt einen Commit ausführen, dann wird für das Submodul festgelegt, dass es in allen Repositorys den neuen Code enthalten soll. Das bedeutet, wenn andere Personen in Klonen Ihres Repositorys git submodule update ausführen, bekommen sie auch den neuen Code des Submoduls.

Es gibt auch einen leichteren Weg, das zu erreichen. Falls Sie es vorziehen, nicht manuell in das Unterverzeichnis zu fetchen und mergen. Wenn Sie git submodule update --remote ausführen, wird Git in Ihre Submodule hineingehen und die Aktualisierung für Sie abholen und durchführen.

Dieser Befehl geht standardmäßig davon aus, dass Sie den Checkout auf den default branch des entfernten Submodul-Repositorys aktualisieren möchten (derjenige, auf den HEAD auf remote zeigt). Sie können es, sofern Sie möchten, auch auf etwas anderes umstellen. Wenn Sie beispielsweise möchten, dass das DbConnector-Submodul den Branch „stable“ dieses Repositorys tracken soll, dann können Sie es entweder in Ihrer .gitmodules Datei eintragen (so jeder es auch trackt) einfach in Ihrer lokalen .git/config Datei setzen. Lassen Sie es uns in der .gitmodules Datei einrichten:

Wenn Sie die Option -f .gitmodules weglassen, wird die Änderung nur für Sie vorgenommen. Es ist aber wahrscheinlich sinnvoller, diese Informationen mit dem Repository zu protokollieren, 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 Sie die Konfigurationseinstellung status.submodulesummary setzen, zeigt Ihnen Git auch eine kurze Übersicht der Änderungen in den Submodulen an:

Sobald Sie jetzt git diff ausführen, können Sie 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 können Sie diese Informationen auch nachträglich anzeigen lassen, indem Sie git log -p aufrufen.

Standardmäßig wird Git versuchen, alle Submodule zu aktualisieren, wenn Sie git submodule update --remote ausführen. Wenn Sie viele Submodule haben, sollten Sie also den Namen genau des Submoduls angeben, das Sie gerade aktualisieren möchten.

Lassen Sie uns aus Sicht Ihres Mitarbeiters agieren, der einen eigenen lokalen Klon des Hauptprojekt-Repositorys besitzt. Einfach nur git pull auszuführen, um die von Ihnen 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 jedoch nicht die Submodule. Dies wird durch die Ausgabe des git status Befehls gezeigt, aus dem hervorgeht, dass das Submodul „modifiziert“ ist und „neue Commits“ hat. Außerdem zeigen die spitzen Klammern der neuen Commits nach links (<) und bedeuten, dass diese Commits im MainProject aufgezeichnet werden, aber nicht im lokalen Checkout von DbConnector vorhanden sind. Um das Update abzuschließen, müssen Sie git submodule update ausführen:

Sicherheitshalber sollten Sie git submodule update mit dem --init Flag ausführen. Für den Fall, dass das MainProject einen Commit durchführt, bei dem Sie gerade neue Submodule hinzugefügt haben. Wenn ein Submodul verschachtelte Submodule hat, sollten Sie das --recursive Flag setzen.

Wenn Sie diesen Prozess automatisieren möchten, können Sie den 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 Sie in Git immer mit dem Flag --recurse-submodules pullen wollen, können Sie die Konfigurations-Option submodule.recurse auf true setzen (dies funktioniert für git pull seit Git 2.15). Diese Option bewirkt, dass Git den Flag --recurse-submodules für alle Befehle verwendet, die ihn 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 Ihnen 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 Ihrem Repository gefunden wird. Um diese Situation zu beheben, ist der Befehl git submodule sync erforderlich:

Wahrscheinlich verwenden Sie Submodule, weil Sie gleichzeitig am Code im Submodul und im Hauptprojekt (oder modulübergreifend in mehreren Submodulen) arbeiten wollen. Andernfalls würden Sie 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 committet 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 Arbeitszweig, der Änderungen nachverfolgt, d.h. selbst wenn Sie Änderungen an das Untermodul committen, gehen diese Änderungen möglicherweise verloren, wenn Sie das nächste Mal git submodule update ausführen. Sie müssen einige zusätzliche Schritte ausführen, wenn Sie wollen, dass diese Änderungen in einem Submodul getrackt werden.

Um Ihr Submodul so einzurichten, dass Sie leichter einsteigen und sich einbinden können, müssen Sie zwei Dinge tun. Sie müssen in jedes Submodul gehen und einen Branch auschecken, an dem Sie arbeiten wollen. Dann müssen Sie Git mitteilen, was zu tun ist, wenn Sie Änderungen vorgenommen haben. Anschließend pullt der Befehl git submodule update --remote neue Daten vom Upstream. Die Optionen sind, dass Sie entweder diese in Ihre lokale Bearbeitung mergen oder versuchsweise die Änderungen in Ihrer lokalen Bearbeitung zu 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 Sie es manuell starten möchten, 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 verschmolzen. 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 Sie --rebase oder --merge vergessen haben, wird Git einfach das Submodul auf das aktualisieren, was auch immer auf dem Server vorhanden ist und Ihr Projekt in einen abgekoppelten (engl. detached) HEAD-Zustand zurücksetzen.

Wenn das passiert, brauchen Sie sich keine Sorgen zu machen, Sie können einfach ins Verzeichnis zurückgehen und Ihren Branch wieder auschecken (der immer noch Ihre Arbeit enthält) und origin/stable (oder welchen Remote-Branch auch immer) manuell mergen oder rebasieren.

Sollten Sie Ihre Änderungen nicht in Ihrem Submodul committet haben und ein Submodul-Update ausführen, das Probleme verursachen würde, holt Git die gemachten Änderungen, überschreibt aber nicht die ungesicherte Arbeit in Ihrem Submodul-Verzeichnis.

Wenn Sie Änderungen vorgenommen haben, die mit einer Änderung im Upstream-Bereich in Konflikt stehen, wird Git Sie darüber informieren, sobald Sie das Update ausführen.

Sie können 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 oben 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, können Sie Git auffordern, zu überprüfen, ob alle Ihre Submodule ordnungsgemäß gepusht wurden, bevor Sie das Hauptprojekt hochladen. 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 Sie feststellen können, 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 stellen Sie sicher, dass die Submodule extern verfügbar sind. Danach kann man diesen Push erneut versuchen. Wenn Sie möchten, dass dieses Verhalten für alle Pushs durchgeführt wird, können Sie dieses Vorgehen zur Standardeinstellung machen. Dazu müssen Sie den Befehl git config push.recurseSubmodules check ausführen.

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

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

Wenn Sie die Referenz eines Submoduls gleichzeitig mit anderen Personen ändern, könnten Sie auf Probleme stoßen. Sollten die Historien der Submodule divergieren und Sie dorthin zu einem Hauptprojekt mit divergierenden Branches committet haben, kann es ein Stück Arbeit erfordern, 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 gemergt werden müssen, erhalten Sie ähnliche Informationen wie diese:

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

Um das Problem zu lösen, müssen Sie ermitteln, in welchem Status sich das Submodul befinden sollte. Merkwürdigerweise liefert Git hier nicht wirklich viele Informationen, die Ihnen helfen können, nicht einmal die SHA-1s der Commits beider Seiten der Historie. Glücklicherweise ist es aber ganz leicht, das herauszufinden. Wenn Sie git diff ausführen, können Sie die SHA-1s der Commits der beiden Branches, die Sie zusammenführen wollten, 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, können Sie einfach einen neuen Branch erstellen und auschecken, der auf dieses Verzeichnis zeigt.

Wichtig ist der SHA-1 des Commits von der Gegenseite. Das werden Sie mergen und lösen müssen. Sie können entweder direkt versuchen, den Merge mit dem SHA-1 durchzuführen oder Sie können einen Branch dafür erstellen und dann versuchen, diesen zu verschmelzen. 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 Prozess, den Git bearbeiten kann. Wenn ein Merge-Commit im Submodul-Verzeichnis existiert, der beide Commits in seinem Verlauf enthält, wird Git Ihnen diesen als mögliche Abhilfe vorschlagen. Es sieht, dass irgendwann im Submodul-Projekt jemand Branches verschmolzen hat, die diese beiden Commits enthalten. Möglicherweise möchten Sie 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, werden Sie ungefähr folgendes sehen:

Der von Git vorgeschlagene Befehl wird den Index aktualisieren, als ob Sie git add (was den Konflikt aufhebt) und dann commit ausführen würden. Allerdings sollten Sie das nicht tun. Sie können 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 können Sie auf diese Weise überprüfen, ob es wirklich funktioniert und Sie haben den Code in Ihrem Submodul-Verzeichnis, wenn Sie fertig sind.

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

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.

Sie verstehen die Idee dahinter? Eine wirklich sinnvolle Methode, die Ihnen hilft, ein gutes, einheitliches Diff zwischen den Änderungen in Ihrem Hauptprojekt und all Ihren Subprojekten zu erstellen.

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

Vielleicht möchten Sie Aliase für manche dieser Befehle einrichten, da sie ziemlich lang sein können und Sie können 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 aber ein Beispiel dafür, was Sie vielleicht einrichten sollten, wenn Sie viel mit Submodulen in Git arbeiten wollen.

Auf diese Weise können Sie einfach git supdate ausführen, wenn Sie Ihre Submodule aktualisieren wollen, oder git spush, 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) ebenfalls knifflig sein. Wenn Sie einen neuen Branch erstellen, dort ein Submodul hinzufügen und dann wieder zu einem Branch ohne dieses Submodul wechseln, haben Sie darin das Submodul-Verzeichnis immer noch als ungetracktes Verzeichnis:

Das Entfernen des Verzeichnisses ist nicht schwierig, aber es kann etwas verwirrend sein, das darin enthalten zu haben. Wenn Sie es entfernen und dann wieder zu dem Branch wechseln, der dieses Submodul besitzt, müssen Sie submodule update --init ausführen, um es neu zu befüllen.

Auch das ist nicht wirklich schwierig, aber es 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 Sie auf mehreren Branches im Hauptprojekt arbeiten, wobei jedes Ihrer Submodule auf unterschiedliche Commits zeigt. Tatsächlich, wenn Sie zwischen den Branches wechseln, die das Submodul bei verschiedenen Commits erfassen, 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 Ihr Projekt Submodule hat. Für ältere Git-Versionen, die das Flag --recurse-submodules nicht kennen, verwenden Sie nach dem Auschecken git submodule update --init --recursive, um die Submodule in den richtigen Zustand zu versetzen.

Glücklicherweise können Sie Git (≥2.14) anweisen, immer das Flag --recurse-submodules zu verwenden, indem Sie die Konfigurationsoption submodule.recurse setzen 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 Warnung, die viele Anwender zu beachten haben, ist der Wechsel von Unterverzeichnissen zu Submodulen. Wenn Sie Dateien in Ihrem Projekt getrackt haben und sie in ein Submodul verschieben wollen, müssen Sie vorsichtig sein, sonst wird Git Ihnen das nicht verzeihen. Angenommen, Sie haben Dateien in einem Unterverzeichnis Ihres Projekts und wollen es in ein Untermodul verschieben. Wenn Sie das Unterverzeichnis löschen und dann submodule add ausführen, wird Git Sie etwa so anbrüllen:

Sie müssen zuerst das CryptoLibrary Verzeichnis aus der Staging-Area entfernen (engl. unstage). Danach können Sie das Submodul hinzufügen:

Nehmen wir jetzt an, Sie hätten das in einem Branch getan. Wenn Sie versuchen, wieder zu einem Branch zu wechseln, in der sich diese Dateien noch im aktuellen Verzeichnisbaum und nicht in einem Submodul befinden, erhalten Sie diesen Fehler:

Sie können den Wechsel mit checkout -f erzwingen, aber achten Sie darauf, dass dort keine ungesicherten Änderungen enthalten sind, weil diese mit dem Befehl überschrieben werden könnten.

Dann, wenn Sie zurückwechseln, erhalten Sie aus bestimmten Gründen ein leeres CryptoLibrary Verzeichnis, und git submodule update kann es auch nicht beheben. Möglicherweise müssen Sie in Ihr Submodul-Verzeichnis gehen und git checkout . ausführen, um alle Ihre Dateien zurück zu bekommen. Sie könnten das mit einem submodule foreach Skript erledigen, um es für mehrere Submodule anzuwenden.

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

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