7.11 Git-Tools - Submodule

Das einfachste Modell der Verwendung von Submodulen in einem Projekt wäre, wenn Sie ein Teilprojekt einfach nur konsumieren und von Zeit zu Zeit Updates von ihm erhalten möchten, aber tatsächlich nichts in Ihrem Checkout ändern würden. Gehen wir ein einfaches Beispiel durch.

Wenn Sie nach neuen Arbeiten in einem Submodul suchen möchten, können Sie in das Verzeichnis wechseln und git fetch ausführen und den Upstream-Branch mergen, um den lokalen Code zu aktualisieren.

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

Wenn Sie zu diesem Zeitpunkt committen, sperren Sie das Submodul mit dem neuen Code, wenn andere Personen aktualisieren.

Es gibt auch eine einfachere Methode, wenn Sie es vorziehen, nicht manuell im Unterverzeichnis abzurufen und zu mergen. Wenn Sie git submodule update --remote ausführen, wechselt Git in Ihre Submodule und ruft für Sie ab und aktualisiert.

Dieser Befehl geht standardmäßig davon aus, dass Sie den Checkout auf den Standard-Branch des Remote-Submodul-Repositorys aktualisieren möchten (den, auf den HEAD im Remote zeigt). Sie können dies jedoch auch anders festlegen, wenn Sie möchten. Wenn Sie beispielsweise möchten, dass das DbConnector-Submodul den „stable“-Branch dieses Repositorys verfolgt, können Sie dies entweder in Ihrer .gitmodules-Datei (damit alle anderen ihn ebenfalls verfolgen) oder nur in Ihrer lokalen .git/config-Datei festlegen. Lassen Sie uns es in der .gitmodules-Datei festlegen

Wenn Sie -f .gitmodules weglassen, wird die Änderung nur für Sie vorgenommen, aber es ist wahrscheinlich sinnvoller, diese Informationen mit dem Repository zu verfolgen, damit dies auch für alle anderen gilt.

Wenn wir zu diesem Zeitpunkt git status ausführen, zeigt Git uns, dass wir „neue Commits“ im Submodul haben.

Wenn Sie die Einstellung status.submodulesummary festlegen, zeigt Git auch eine kurze Zusammenfassung der Änderungen an Ihren Submodulen.

Zu diesem Zeitpunkt, wenn wir git diff ausführen, können wir sehen, dass wir unsere .gitmodules-Datei geändert haben und dass es auch eine Reihe von Commits gibt, die wir heruntergeladen haben und die wir für unser Submodulprojekt committen können.

Das ist ziemlich cool, da wir tatsächlich das Commit-Log sehen können, das wir in unserem Submodul committen werden. Sobald es committet ist, können Sie diese Informationen auch nachträglich sehen, wenn Sie git log -p ausführen.

Git versucht standardmäßig, **alle** Ihre Submodule zu aktualisieren, wenn Sie git submodule update --remote ausführen. Wenn Sie viele davon haben, möchten Sie möglicherweise nur den Namen des Submoduls übergeben, das Sie zu aktualisieren versuchen.

Betreten wir nun die Rolle Ihres Mitarbeiters, der seinen eigenen lokalen Klon des MainProject-Repositorys hat. Einfach git pull auszuführen, um Ihre neu committeten Änderungen zu erhalten, reicht nicht aus.

Standardmäßig ruft der Befehl git pull Submodule rekursiv ab, wie wir in der Ausgabe des ersten obigen Befehls sehen können. Er **aktualisiert** die Submodule jedoch nicht. Dies zeigt die Ausgabe des Befehls git status, der besagt, dass das Submodul „modifiziert“ ist und „neue Commits“ hat. Darüber hinaus zeigen die Klammern, die die neuen Commits anzeigen, nach links (<), was bedeutet, dass diese Commits in MainProject aufgezeichnet sind, aber nicht im lokalen DbConnector-Checkout vorhanden sind. Um die Aktualisierung abzuschließen, müssen Sie git submodule update ausführen.

Beachten Sie, dass Sie zur Sicherheit git submodule update mit der Option --init ausführen sollten, falls die gerade gezogenen MainProject-Commits neue Submodule hinzugefügt haben, und mit der Option --recursive, falls einige Submodule verschachtelte Submodule haben.

Wenn Sie diesen Prozess automatisieren möchten, können Sie die Option --recurse-submodules zum Befehl git pull hinzufügen (seit Git 2.14). Dadurch wird Git direkt nach dem Pull git submodule update ausführen und die Submodule in den richtigen Zustand versetzen. Darüber hinaus, wenn Sie möchten, dass Git immer mit --recurse-submodules pullen soll, können Sie die Konfigurationsoption submodule.recurse auf true setzen (dies funktioniert für git pull seit Git 2.15). Diese Option veranlasst Git, das Flag --recurse-submodules für alle Befehle zu verwenden, die es unterstützen (außer clone).

Es gibt eine besondere Situation, die beim Abrufen von Superprojekt-Updates auftreten kann: Es könnte sein, dass das Upstream-Repository die URL des Submoduls in der Datei .gitmodules in einem der Commits, die Sie abrufen, geändert hat. Dies kann beispielsweise passieren, wenn das Submodulprojekt seine Hosting-Plattform wechselt. In diesem Fall ist es möglich, dass git pull --recurse-submodules oder git submodule update fehlschlagen, wenn das Superprojekt auf einen Submodul-Commit verweist, der im lokal konfigurierten Submodul-Remote Ihres Repositorys nicht gefunden wird. Um diese Situation zu beheben, ist der Befehl git submodule sync erforderlich.

Es ist sehr wahrscheinlich, dass Sie Submodule verwenden, weil Sie wirklich gleichzeitig am Code im Submodul und am Code im Hauptprojekt arbeiten möchten. Andernfalls würden Sie wahrscheinlich stattdessen ein einfacheres Abhängigkeitsverwaltungssystem (wie Maven oder Rubygems) verwenden.

Lassen Sie uns nun ein Beispiel durchgehen, bei dem wir Änderungen am Submodul gleichzeitig mit dem Hauptprojekt vornehmen und diese Änderungen gleichzeitig committen und veröffentlichen.

Bisher hat Git beim Ausführen des Befehls git submodule update, um Änderungen von den Submodul-Repositories abzurufen, die Änderungen abgerufen und die Dateien im Unterverzeichnis aktualisiert, aber das Sub-Repository in einem Zustand namens „detached HEAD“ belassen. Das bedeutet, dass kein lokaler Arbeitsbranch (wie z. B. master) die Änderungen verfolgt. Da kein Arbeitsbranch die Änderungen verfolgt, bedeutet dies, dass selbst wenn Sie Änderungen am Submodul committen, diese Änderungen wahrscheinlich beim nächsten Ausführen von git submodule update verloren gehen. Sie müssen zusätzliche Schritte ausführen, wenn Änderungen in einem Submodul verfolgt werden sollen.

Um Ihr Submodul so einzurichten, dass es einfacher zu bearbeiten ist, müssen Sie zwei Dinge tun. Sie müssen in jedes Submodul wechseln und einen Branch zum Arbeiten auschecken. Dann müssen Sie Git mitteilen, was zu tun ist, wenn Sie Änderungen vorgenommen haben und später git submodule update --remote neue Arbeiten aus dem Upstream abruft. Die Optionen sind, dass Sie sie mit Ihrer lokalen Arbeit zusammenführen oder versuchen können, Ihre lokale Arbeit auf die neuen Änderungen zu rebasen.

Zuerst wechseln wir in unser Submodulverzeichnis und checken einen Branch aus.

Lassen Sie uns versuchen, unser Submodul mit der Option „merge“ zu aktualisieren. Um dies manuell anzugeben, können wir einfach die Option --merge zu unserem update-Aufruf hinzufügen. Hier sehen wir, dass es eine Änderung auf dem Server für dieses Submodul gab und sie zusammengeführt wird.

Wenn wir in das Verzeichnis DbConnector wechseln, haben wir die neuen Änderungen bereits in unseren lokalen stable-Branch eingearbeitet. Sehen wir uns nun an, was passiert, wenn wir unsere eigene lokale Änderung an der Bibliothek vornehmen und jemand anderes gleichzeitig eine weitere Änderung am Upstream pusht.

Wenn wir nun unser Submodul aktualisieren, können wir sehen, was passiert, wenn wir eine lokale Änderung vorgenommen haben und der Upstream ebenfalls eine Änderung hat, die wir integrieren müssen.

Wenn Sie --rebase oder --merge vergessen, aktualisiert Git das Submodul nur auf das, was sich auf dem Server befindet, und setzt Ihr Projekt in den Zustand „detached HEAD“ zurück.

Wenn dies passiert, machen Sie sich keine Sorgen, Sie können einfach wieder in das Verzeichnis wechseln und Ihren Branch erneut auschecken (der Ihre Arbeit immer noch enthalten wird) und manuell origin/stable (oder welchen Remote-Branch auch immer Sie möchten) mergen oder rebasen.

Wenn Sie Ihre Änderungen in Ihrem Submodul nicht committet haben und ein submodule update ausführen, das Probleme verursachen würde, ruft Git die Änderungen ab, überschreibt aber keine ungespeicherte Arbeit in Ihrem Submodulverzeichnis.

Wenn Ihre Änderungen mit etwas kollidieren, das am Upstream geändert wurde, wird Git Sie informieren, wenn Sie das Update ausführen.

Sie können in das Submodulverzeichnis wechseln und den Konflikt wie gewohnt beheben.

Nun haben wir einige Änderungen in unserem Submodulverzeichnis. Einige davon wurden durch unsere Updates vom Upstream abgerufen, andere wurden lokal vorgenommen und sind noch für niemanden sonst verfügbar, da wir sie noch nicht gepusht haben.

Wenn wir im Hauptprojekt committen und es hochpushen, ohne auch die Submoduländerungen hochzupushen, werden Personen, die versuchen, unsere Änderungen auszuchecken, in Schwierigkeiten geraten, da sie keine Möglichkeit haben, die benötigten Submoduländerungen abzurufen. Diese Änderungen existieren nur in unserer lokalen Kopie.

Um sicherzustellen, dass dies nicht passiert, können Sie Git bitten zu überprüfen, ob alle Ihre Submodule ordnungsgemäß gepusht wurden, bevor Sie das Hauptprojekt pushen. Der Befehl git push nimmt das Argument --recurse-submodules entgegen, das entweder auf „check“ oder „on-demand“ gesetzt werden kann. Die Option „check“ bewirkt, dass push einfach fehlschlägt, wenn nicht alle committeten Submoduländerungen gepusht wurden.

Wie Sie sehen können, gibt er uns auch einige hilfreiche Ratschläge, was wir als Nächstes tun könnten. Die einfache Option besteht darin, in jedes Submodul zu wechseln und manuell zu den Remotes zu pushen, um sicherzustellen, dass sie extern verfügbar sind, und dann diesen Push erneut zu versuchen. Wenn Sie möchten, dass das „check“-Verhalten für alle Pushes erfolgt, können Sie dieses Verhalten zum Standard machen, indem Sie git config push.recurseSubmodules check ausführen.

Die andere Option ist die Verwendung des Wertes „on-demand“, der versucht, dies für Sie zu tun.

Wie Sie dort sehen können, hat Git das DbConnector-Modul durchlaufen und es gepusht, bevor es das Hauptprojekt gepusht hat. Wenn dieser Submodul-Push aus irgendeinem Grund fehlschlägt, wird auch der Push des Hauptprojekts fehlschlagen. Sie können dieses Verhalten zum Standard machen, indem Sie git config push.recurseSubmodules on-demand ausführen.

Wenn Sie eine Submodulreferenz gleichzeitig mit jemand anderem ändern, können einige Probleme auftreten. Das heißt, wenn sich die Submodulhistorien verzweigt haben und in verzweigten Branches in einem Superprojekt committet sind, kann es etwas Arbeit erfordern, um sie zu beheben.

Wenn einer der Commits ein direkter Vorfahre des anderen ist (ein Fast-Forward-Merge), wählt Git einfach den letzteren für den Merge aus, so dass das gut funktioniert.

Git wird jedoch keinen auch nur trivialen Merge für Sie versuchen. Wenn sich die Submodul-Commits verzweigen und zusammengeführt werden müssen, erhalten Sie etwas, das wie folgt aussieht

Grundsätzlich ist hier passiert, dass Git festgestellt hat, dass die beiden Branches Punkte in der Historie des Submoduls aufzeichnen, die sich verzweigen und zusammengeführt werden müssen. Es erklärt dies als „merge following commits not found“ (nachfolgende Commits zum Mergen nicht gefunden), was verwirrend ist, aber wir werden erklären, warum das so ist.

Um das Problem zu lösen, müssen Sie herausfinden, in welchem Zustand sich das Submodul befinden soll. Seltsamerweise gibt Git Ihnen nicht viele Informationen zur Hilfe, nicht einmal die SHA-1s der Commits beider Seiten der Historie. Glücklicherweise ist es einfach herauszufinden. Wenn Sie git diff ausführen, erhalten Sie die SHA-1s der Commits, die in beiden Branches aufgezeichnet sind, die Sie zusammenführen wollten.

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 Submodulverzeichnis wechseln, sollte es bereits auf eb41d76 stehen, da der Merge es nicht berührt hätte. Wenn es aus irgendeinem Grund nicht der Fall ist, können Sie einfach einen Branch erstellen und ihn auschecken.

Wichtig ist hierbei die SHA-1 des Commits von der anderen Seite. Dies ist das, was Sie zusammenführen und lösen müssen. Sie können entweder versuchen, den Merge direkt mit der SHA-1 durchzuführen, oder Sie können einen Branch dafür erstellen und dann versuchen, diesen zu mergen. Wir würden Letzteres vorschlagen, allein schon, um eine schönere Merge-Commit-Nachricht zu erstellen.

Wir wechseln also in unser Submodulverzeichnis, erstellen einen Branch namens „try-merge“ basierend auf der zweiten SHA-1 aus git diff und führen manuell einen Merge durch.

Wir haben hier einen tatsächlichen Merge-Konflikt, also wenn wir diesen beheben und committen, können wir einfach das Hauptprojekt mit dem Ergebnis aktualisieren.

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

Interessanterweise gibt es einen weiteren Fall, den Git behandelt. Wenn im Submodulverzeichnis ein Merge-Commit vorhanden ist, der **beide** Commits in seiner Historie enthält, schlägt Git ihn Ihnen als mögliche Lösung vor. Er sieht, dass an einem bestimmten Punkt im Submodulprojekt jemand Branches zusammengeführt hat, die diese beiden Commits enthalten, also möchten Sie vielleicht diesen.

Deshalb lautete die Fehlermeldung von zuvor „merge following commits not found“, weil es **dies** nicht tun konnte. Es ist verwirrend, denn wer würde erwarten, dass es **versucht**, dies zu tun?

Wenn es einen einzelnen akzeptablen Merge-Commit findet, sehen Sie etwas wie das hier

Der vorgeschlagene Befehl, den Git bereitstellt, aktualisiert den Index so, als hätten Sie git add ausgeführt (was den Konflikt löst) und committet dann. Dies sollten Sie jedoch wahrscheinlich nicht tun. Sie können genauso gut in das Submodulverzeichnis wechseln, den Unterschied feststellen, zu diesem Commit springen, ihn ordnungsgemäß testen und dann committen.

Dies erreicht dasselbe, aber auf diese Weise können Sie zumindest überprüfen, ob es funktioniert und Sie die Dateien nach Abschluss in Ihrem Submodulverzeichnis haben.

Es gibt einen foreach-Befehl für Submodule, um einen beliebigen Befehl in jedem Submodul auszuführen. Dies kann sehr hilfreich sein, wenn Sie mehrere Submodule im selben Projekt haben.

Nehmen wir zum Beispiel an, wir möchten eine neue Funktion starten oder einen Fehler beheben und wir haben Arbeit in mehreren Submodulen. Wir können ganz einfach die gesamte Arbeit in all unseren Submodulen stashen.

Dann können wir einen neuen Branch erstellen und in all unseren Submodulen zu ihm wechseln.

Sie verstehen das Prinzip. Eine wirklich nützliche Sache, die Sie tun können, ist, eine schöne einheitliche Diff-Ausgabe dessen zu erstellen, was in Ihrem Hauptprojekt und allen Ihren Teilprojekten geändert wurde.

Hier sehen wir, dass wir eine Funktion in einem Submodul definieren und sie im Hauptprojekt aufrufen. Dies ist offensichtlich ein vereinfachtes Beispiel, aber hoffentlich gibt es Ihnen eine Vorstellung davon, wie dies nützlich sein kann.

Sie möchten vielleicht einige Aliase für einige dieser Befehle einrichten, da sie ziemlich lang sein können und Sie für die meisten keine Konfigurationsoptionen festlegen können, um sie zum Standard zu machen. Wir haben die Einrichtung von Git-Aliassen in Git Aliases behandelt, aber hier ist ein Beispiel dafür, was Sie einrichten möchten, wenn Sie vorhaben, viel mit Submodulen in Git zu arbeiten.

Auf diese Weise können Sie einfach git supdate ausführen, wenn Sie Ihre Submodule aktualisieren möchten, oder git spush, um mit der Prüfung von Submodulabhängigkeiten zu pushen.

Zum Beispiel kann das Wechseln von Branches mit Submodulen in Git-Versionen vor Git 2.13 schwierig sein. Wenn Sie einen neuen Branch erstellen, dort ein Submodul hinzufügen und dann zurück zu einem Branch ohne dieses Submodul wechseln, haben Sie das Submodulverzeichnis immer noch als nicht verfolgtes Verzeichnis.

Das Entfernen des Verzeichnisses ist nicht schwierig, aber es kann etwas verwirrend sein, dass es dort ist. Wenn Sie es entfernen und dann zurück zu dem Branch wechseln, der dieses Submodul hat, müssen Sie submodule update --init ausführen, um es wieder aufzufüllen.

Auch das ist nicht wirklich sehr schwierig, aber es kann ein wenig verwirrend sein.

Neuere Git-Versionen (Git >= 2.13) vereinfachen dies, indem sie dem Befehl git checkout die Option --recurse-submodules hinzufügen, die dafür sorgt, dass die Submodule für den Branch, zu dem wir wechseln, in den richtigen Zustand versetzt werden.

Die Verwendung der Option --recurse-submodules von git checkout kann auch dann nützlich sein, wenn Sie an mehreren Branches im Superprojekt arbeiten, die jeweils Ihr Submodul auf verschiedene Commits verweisen. Tatsächlich wird das Submodul bei der Ausführung von git status als „modifiziert“ angezeigt und „neue Commits“ anzeigen, wenn Sie zwischen Branches wechseln, die das Submodul auf verschiedenen Commits aufzeichnen. Dies liegt daran, dass der Submodulstatus standardmäßig beim Wechseln von Branches nicht übernommen wird.

Dies kann sehr verwirrend sein, daher ist es eine gute Idee, immer git checkout --recurse-submodules auszuführen, wenn Ihr Projekt Submodule enthält. Für ältere Git-Versionen, die die Option --recurse-submodules nicht haben, können Sie nach dem Checkout git submodule update --init --recursive verwenden, um die Submodule in den richtigen Zustand zu versetzen.

Glücklicherweise können Sie Git (>=2.14) mitteilen, immer die Option --recurse-submodules zu verwenden, indem Sie die Konfigurationsoption submodule.recurse einstellen: git config submodule.recurse true. Wie oben erwähnt, wird Git dadurch auch rekursiv in Submodule für jeden Befehl durchlaufen, der eine Option --recurse-submodules hat (außer git clone).

Die andere Haupt-Caveat, auf die viele Leute stoßen, betrifft den Wechsel von Unterverzeichnissen zu Submodulen. Wenn Sie Dateien in Ihrem Projekt verfolgt haben und diese in ein Submodul verschieben möchten, müssen Sie vorsichtig sein, sonst wird Git böse. Angenommen, Sie haben Dateien in einem Unterverzeichnis Ihres Projekts und möchten es in ein Submodul umwandeln. Wenn Sie das Unterverzeichnis löschen und dann submodule add ausführen, schreit Git Sie an.

Sie müssen das Verzeichnis CryptoLibrary zuerst ausstagen. Dann können Sie das Submodul hinzufügen.

Nehmen wir nun an, Sie haben dies in einem Branch getan. Wenn Sie versuchen, zu einem Branch zurückzuwechseln, in dem sich diese Dateien immer noch im tatsächlichen Baum und nicht in einem Submodul befinden, erhalten Sie diese Fehlermeldung.

Sie können es mit checkout -f erzwingen, aber seien Sie vorsichtig, dass Sie keine ungespeicherten Änderungen darin haben, da diese mit diesem Befehl überschrieben werden könnten.

Dann, wenn Sie zurückwechseln, erhalten Sie aus irgendeinem Grund ein leeres CryptoLibrary-Verzeichnis und git submodule update behebt es möglicherweise nicht. Sie müssen möglicherweise in Ihr Submodulverzeichnis wechseln und git checkout . ausführen, um alle Ihre Dateien zurückzubekommen. Sie könnten dies in einem submodule foreach-Skript ausführen, um es für mehrere Submodule auszuführen.

Es ist wichtig zu beachten, dass Submodule heutzutage alle ihre Git-Daten im .git-Verzeichnis des Top-Projekts speichern. Im Gegensatz zu viel älteren Git-Versionen gehen beim Zerstören eines Submodulverzeichnisses keine Commits oder Branches verloren, die Sie hatten.

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