Was Ist Ein Git Submodule, Und Wie Wenden Sie Es An?

Was Ist Ein Git Submodule?

Konkret verknüpft ein Git Submodule ein Git Repository als Abhängigkeit innerhalb eines anderen Repositorys. Das übergeordnete Projekt kopiert die Dateien des Submodules nicht in seine eigene Historie. Zudem speichert es nur einen Zeiger auf einen bestimmten Commit des anderen Repositorys, festgehalten in einer .gitmodules Datei und einem besonderen Verzeichniseintrag.

Wer das übergeordnete Projekt klont, sieht den Pfad des Submodules und den erwarteten Commit, aber die Dateien dieses Commits kommen erst in einem separaten Schritt hinzu. Diese Trennung wirkt zunächst ungewohnt, zeigt aber genau, wie zwei unabhängige Historien getrennt bleiben, statt sich zu vermischen. Daher behält das Submodule seine eigenen Branches, Tags und seinen eigenen Beitragsprozess, völlig unabhängig vom übergeordneten Projekt.

Wofür Dient Die Datei .gitmodules?

.gitmodules ist eine reine Textdatei, die den lokalen Pfad jedes Git Submodules mit seiner Remote Adresse verknüpft. Daher committen Teams diese Datei zusammen mit dem übergeordneten Projekt, sodass jeder, der das Repository klont, sofort sieht, welches Submodule von welcher Adresse stammt. Sie können die Datei von Hand bearbeiten, allerdings empfehlen wir, sie von den Git Submodule Befehlen erzeugen zu lassen.

• Path: der Ordnername des Submodules im übergeordneten Projekt.
• Url: die Remote Adresse, von der das Submodule geklont wird.
• Branch (optional): der Branch, der bei Aktualisierungen verfolgt wird.

Für das genaue Verhalten jedes Befehls ist die offizielle Dokumentation Git Tools: Submodules die verlässlichste Quelle, und genau diese haben wir bei der Vorbereitung dieses Leitfadens zur Prüfung genutzt. In einem Projekt mit mehreren Submodules gibt diese Datei auf einen Blick die gesamte Abhängigkeitskarte wieder. Verschachtelte Submodules, also ein Submodule, das selbst wieder ein Submodule enthält, sind ebenfalls möglich. Die Option --recursive verarbeitet dann jede Ebene nacheinander.

Wann Sollten Sie Ein Git Submodule Einsetzen?

Ein Git Submodule ergibt Sinn, wenn eine Komponente eine eigene Historie braucht, Sie aber trotzdem direkt daran arbeiten. Zum Beispiel: Teilt Ihr Team eine UI Bibliothek über mehrere Projekte hinweg und steuert gelegentlich selbst Korrekturen bei, passt ein Submodule gut. Dagegen ist ein Paketmanager für eine Abhängigkeit, die Sie nur konsumieren und nie anfassen, meist der einfachere Weg.

Zum Beispiel teilt ein Team dieselben Validierungsregeln über mehrere Webprojekte hinweg. Die Regeln liegen in einem eigenen Repository. Jedes Projekt zieht dieses Repository als Submodule hinein, und der Aktualisierungsschritt läuft, wann immer er nötig ist. So verwalten Sie die Regeln zentral und lassen jedes Projekt in seinem eigenen Tempo aktualisieren.

Wie Unterscheidet Sich Ein Git Submodule Von Einem Paketmanager?

Ein Paketmanager wie npm, Composer oder pip lädt eine Abhängigkeit anhand einer Versionsnummer herunter. Den Quellcode fassen Sie in der Regel nie an. Dagegen bringt ein Git Submodule ein vollständiges Git Repository mit. Das Submodule behält also seine eigenen Branches, seine Commit Historie und die Möglichkeit, Änderungen vorzunehmen. Wählen Sie einen Paketmanager, wenn Sie Code nur konsumieren, und ein Git Submodule, wenn Sie daran mitentwickeln wollen.

Dieser Unterschied prägt auch den Arbeitsalltag. Konkret erhöht ein Team mit Paketmanager eine Versionsnummer und macht weiter. Ein Team mit Submodules muss dagegen sowohl den Zeiger im übergeordneten Projekt als auch den Commit im Submodule gleichzeitig im Blick behalten, und das ist der Preis für die zusätzliche Flexibilität.

Wie Fügen Sie Ein Git Submodule Hinzu?

Um ein Git Submodule hinzuzufügen, wechseln Sie zuerst ins Wurzelverzeichnis des übergeordneten Projekts und führen git submodule add <repo-adresse> aus. Für einen anderen Ordnernamen hängen Sie einen Pfad an, zum Beispiel git submodule add <repo-adresse> libs/ui. Danach entsteht oder aktualisiert sich die Datei .gitmodules, die Sie zusammen mit den übrigen Änderungen committen.

1. Wechseln Sie ins Wurzelverzeichnis des übergeordneten Projekts.
2. Führen Sie git submodule add mit der Remote Adresse aus.
3. Markieren Sie die neue .gitmodules Datei und den neuen Ordner mit git add.
4. Committen Sie die Änderung mit einer klaren Beschreibung.

Nach dem Hinzufügen sehen Sie einen neuen Ordner. Denn er verhält sich wie ein besonderer Git Eintrag und nicht wie ein gewöhnliches Verzeichnis. Wechseln Sie hinein und prüfen Sie den Status, dann sehen Sie den Status des Submodules selbst, nicht den des übergeordneten Projekts.

Statt jede Abhängigkeit einzeln hinzuzufügen und dieselben Befehle in jedem Ordner zu wiederholen, gibt es eine einfachere Option. git submodule foreach führt einen Befehl nacheinander über alle Submodules aus. Dadurch spart das bei vielen Abhängigkeiten Zeit und erspart Ihnen den Weg durch jeden einzelnen Ordner.

Wie Klonen Sie Ein Repository Mit Submodules?

Ein einfaches git clone lässt Submodule Ordner leer, weil der Hauptklon den Inhalt der Submodules nicht automatisch lädt. Nutzen Sie stattdessen git clone --recurse-submodules <adresse>, dann kommt beim ersten Durchlauf alles mit, auch verschachtelte Submodules. Haben Sie schon auf die übliche Art geklont, erledigt git submodule update --init --recursive denselben Schritt nachträglich.

Bei großen Repositorys kann dieser Schritt etwas dauern, weil jedes Submodule mit seiner vollständigen Historie geladen wird. Teams mit langsamer Verbindung, die nur einen Teil der Historie brauchen, haben dafür Optionen für flache Klone, das führen wir an dieser Stelle aber nicht weiter aus.

Warum Ist Ein Submodule Ordner Leer?

Diese Beschwerde äußern Teams am häufigsten. Konkret klont jemand das Repository, öffnet den Submodule Ordner und findet ihn leer. Der Grund ist einfach. Entweder fehlte beim Klonen die Option --recurse-submodules, oder die Schritte init und update wurden danach nie ausgeführt. Die Lösung ist git submodule update --init --recursive. Dieser Befehl richtet zuerst die Submodule Konfiguration ein und lädt dann den festgelegten Commit.

Teams, die das dauerhaft vermeiden wollen, schreiben den richtigen Klonbefehl in die README. Außerdem bauen sie dieselbe Prüfung in ihr Setup Skript ein. So muss sich kein neuer Entwickler einen zusätzlichen manuellen Schritt merken.

Wie Holen Sie Submodule Aktualisierungen?

Eine Aktualisierung des übergeordneten Projekts kann den Zeiger des Submodules verändern. Allein füllt das aber noch nicht den Ordner des Submodules neu. Führen Sie git submodule update --init --recursive aus, um auf den Commit zu wechseln, den das übergeordnete Projekt jetzt vorgibt. Ab Git 2.14 reicht einmalig git config submodule.recurse true, und danach aktualisiert ein normales git pull die Submodules automatisch mit.

Daher erspart es dem gesamten Team einen wiederkehrenden Fehler, diese Einstellung global zu setzen. Auf einem älteren Rechner ohne diese Einstellung müssen Sie dagegen nach einem Pull den Status prüfen und die Aktualisierung von Hand ausführen, sobald Ihnen auffällt, dass sich das Submodule verändert hat.

Wie Holen Sie Neue Upstream Commits In Ein Submodule?

Wollen Sie nicht den vom übergeordneten Projekt vorgegebenen Stand, sondern den neuesten Stand des eigenen Branches des Submodules, nutzen Sie git submodule update --remote. Konkret lädt dieser Befehl den neuesten Commit des in .gitmodules definierten Branches. Geben Sie zusätzlich den Pfad eines Submodules an, um nur dieses eine zu aktualisieren. Denken Sie anschließend daran, den neuen Zeiger im übergeordneten Projekt zu committen, sonst bleibt der Rest des Teams auf dem alten Stand.

Um den verfolgten Branch dauerhaft festzulegen, tragen Sie ihn mit git config -f .gitmodules submodule.<name>.branch <branch> in die Datei ein. So weiß die Option --remote immer genau, von welchem Branch sie laden soll, und das ganze Team erhält dasselbe Ergebnis.

Was Bedeutet Detached HEAD Im Submodule?

Der Befehl git submodule update checkt das Submodule bei einem bestimmten Commit aus, ohne ihn an einen Branch zu binden. Dieser Zustand heißt also Detached HEAD. Committen Sie direkt in diesem Zustand, kann die nächste Aktualisierung diese Commits unerreichbar machen. Wechseln Sie vor der Arbeit im Submodule mit git checkout <branch> auf einen Branch. Dann bleibt alles, was Sie committen, sicher nachverfolgt.

Ein Entwickler, der unbemerkt im Detached HEAD Zustand committet hat, muss nicht in Panik verfallen. Allerdings löscht Git diese Commits nicht sofort. Sie werden lediglich schwerer erreichbar, weil kein Branch mehr darauf zeigt. Der Befehl git reflog findet in diesem Fall die Kennung des Commits, und ein Verschieben auf einen Branch rettet ihn.

Worauf Achten Sie Vor Dem Push Von Submodule Änderungen?

Stellen Sie sicher, dass die eigenen Commits des Submodules den Remote Server erreicht haben, bevor Sie das übergeordnete Projekt pushen. Andernfalls findet ein anderer Entwickler den vom Submodule gezeigten Commit nicht, selbst wenn er das übergeordnete Projekt zieht. Automatisieren Sie diese Prüfung mit git push --recurse-submodules=check. Konkret stoppt dieser Befehl den Push, wenn ein Submodule Commit noch nicht oben ist. Alternativ schickt git push --recurse-submodules=on-demand zuerst die Submodules und danach automatisch das übergeordnete Projekt.

Legen Sie eine der beiden Optionen mit git config push.recurseSubmodules on-demand als Standard für das Team fest. Dann muss sich niemand die Option merken, und jeder Push läuft in der sicheren Reihenfolge ab.

Warum Bricht Die Submodule Referenz Beim Branch Wechsel?

Unterschiedliche Branches können auf unterschiedliche Submodule Commits zeigen. Allerdings aktualisiert ein Branch Wechsel den Inhalt des Submodules nicht automatisch. Deshalb wirkt der Ordner so, als sei er auf dem alten Commit hängen geblieben. Ab Git 2.13 verschiebt git checkout --recurse-submodules <branch> die Submodules direkt beim Branch Wechsel auf den richtigen Commit. Um das im ganzen Team dauerhaft zu lösen, empfehlen wir jedem Entwickler die Einstellung git config submodule.recurse true.

Ohne diese Einstellung zeigt git status nach einem Branch Wechsel oft, dass sich das Submodule verändert hat. In der Praxis ist das keine Beschädigung. Es bedeutet nur, dass der Ordner noch nicht an den Zeiger des neuen Branches angepasst wurde, und ein einziger Aktualisierungsbefehl löst das Problem.

Wie Lösen Sie Einen Submodule Pointer Konflikt?

Legen zwei Entwickler auf unterschiedlichen Branches verschiedene Commits desselben Submodules fest, kann Git diesen Konflikt nicht allein zusammenführen. Konkret zeigt die Ausgabe von git diff zwei unterschiedliche Commit Kennungen. Gehen Sie in das Submodule, entscheiden Sie, welcher Commit richtig ist, führen Sie beide bei Bedarf zu einem neuen Commit zusammen, und markieren Sie danach im übergeordneten Projekt den Pfad des Submodules mit git add, um den Konflikt zu schließen. Ebenso gilt eine ähnliche Logik bei gewöhnlichen Dateikonflikten. Unseren Leitfaden Git Merge Konflikt lösen können Sie dafür ebenfalls heranziehen.

Ein solcher Konflikt entsteht meist, wenn zwei Entwickler dieselbe Abhängigkeit gleichzeitig aus unterschiedlichen Gründen aktualisieren wollen. Ein kurzes Gespräch darüber, welche Änderung Vorrang hat, erleichtert das Zusammenführen erheblich, bevor Sie den Konflikt lösen.

Wie Verwandeln Sie Einen Vorhandenen Ordner In Ein Submodule?

Git erlaubt das nicht direkt. Ein bereits vom übergeordneten Projekt verfolgter Ordner lässt sich nicht einfach in ein Submodule verwandeln, da sich zwei Nachverfolgungsmechanismen auf demselben Pfad überschneiden würden. Entfernen Sie den Ordner zuerst mit git rm -r <ordner> aus der Nachverfolgung des übergeordneten Projekts, und führen Sie dann git submodule add auf demselben Pfad aus. Vor allem sichern Sie den Ordner vor diesem Schritt, um einen möglichen Datenverlust zu vermeiden.

Wollen Sie die alte Commit Historie des Ordners in das neue Submodule übernehmen, ist das ein eigener, komplexer Vorgang zum Zusammenführen von Historien und braucht sorgfältige Planung. In der Praxis ist es für die meisten Teams einfacher, ein frisches Submodule Repository zu starten. Folglich lohnt sich das Entwirren dieser Art von Historientransplantation selten.

Was Passiert, Wenn Sich Die URL Eines Submodules Ändert?

Zieht die Adresse des Submodules um oder ändert sie sich, aktualisieren Sie zuerst die url Zeile in .gitmodules. Danach bringt git submodule sync --recursive die lokale Konfiguration mit der neuen Adresse in Einklang. Zuletzt führt git submodule update --init --recursive dazu, dass jeder Rechner im Team Inhalte von der richtigen Quelle lädt.

Allerdings genügt es nicht, allein die .gitmodules Datei zu ändern. Die lokale Konfiguration behält die alte Adresse, und die Aktualisierung kann dann still fehlschlagen. Denn genau diesen alten Eintrag erneuert der Sync Schritt.

Wie Unterscheidet Sich Ein Git Submodule Von Einem Monorepo?

Ein Git Submodule verbindet Repositorys mit unabhängiger Historie über eine lose Referenz, und jedes Projekt bleibt in seinem eigenen Repository. Ein Monorepo macht das Gegenteil und hält viele Projekte in einem einzigen Repository mit einer gemeinsamen Commit Historie. Konkret passen Submodules zu unabhängig versionierten, aber gemeinsam genutzten Komponenten. Ein Monorepo passt dagegen zu Teams, die den gesamten Code gemeinsam sehen und ändern wollen. Unseren Artikel Was ist ein Monorepo, mit Vor und Nachteilen können Sie für diese Entscheidung vertiefend heranziehen.

Manche Teams kombinieren beides. Das Kernprodukt bleibt in einem Monorepo, während eine selten geänderte, mit anderen Projekten geteilte Komponente als Submodule hinzukommt. So lässt diese Mischung jeden Ansatz dort wirken, wo er am besten passt.

Worauf Sollte Ein Team Bei Submodules Achten?

Ein Team, das mit einem Git Submodule arbeitet, profitiert von einem gemeinsamen Regelwerk. Dokumentieren Sie die Option --recurse-submodules in den Klonanweisungen und halten Sie sie in der README fest. Außerdem machen Sie den Wechsel auf einen Branch vor dem Committen im Submodule zur festen Gewohnheit. Prüfen Sie zudem, ob Ihre Continuous Integration Pipeline ebenfalls die Schritte init und update für Submodules ausführt. Sonst läuft die Erstellung weiter gegen veralteten Code.

• Dokumentieren Sie Klonbefehle mit --recurse-submodules.
• Machen Sie die Einstellung submodule.recurse im ganzen Team zur Pflicht.
• Bauen Sie die Gewohnheit auf, vor der Arbeit im Submodule auf einen Branch zu wechseln.
• Fügen Sie den Schritt submodule update --init --recursive in CI Skripte ein.

Diese Regeln schriftlich in die Projektdokumentation aufzunehmen, statt sie als mündliche Abmachung zu belassen, hindert ein neues Teammitglied daran, dieselben Fehler zu wiederholen. So beugt eine kurze Einrichtungscheckliste mit der Zeit viel angesammelter Verwirrung vor.

Welche Typischen Fallen Hat Ein Git Submodule?

Erstens ist die häufigste Falle eine veraltete Referenz, die unbemerkt bleibt. Sie ziehen das übergeordnete Projekt, aber der Submodule Ordner bleibt auf einem alten Commit, weil der Aktualisierungsschritt übersprungen wurde. Der zweite häufige Fehler ist das Vergessen der Option --recurse-submodules beim Klonen, dann bleibt der Ordner vollständig leer. Die dritte Falle ist das direkte Committen im Submodule während des Detached HEAD Zustands, wobei diese Commits später verloren gehen können. Die vierte Falle besteht darin, das übergeordnete Projekt zu pushen, bevor die eigenen Änderungen im Submodule gepusht wurden. Folglich findet ein anderer Entwickler den benötigten Commit trotz Pull nicht.

Alle vier Fallen haben eine gemeinsame Ursache: die zweischichtige Natur eines Submodules wird übersehen. Das übergeordnete Projekt und das Submodule sind zwei Zustände, die getrennt verwaltet werden müssen, und genau darauf zu achten, dass beide zusammenpassen, bildet die Grunddisziplin bei der Arbeit mit Submodules.

Welche Alternativen Gibt Es Zu Einem Git Submodule?

Zunächst: Ein Git Submodule ist nicht die einzige Option. Git Subtree führt die Dateien des untergeordneten Projekts direkt in die Historie des übergeordneten Projekts zusammen und erspart einen separaten Klonschritt. Allerdings kostet das eine komplizierteren Historie. Paketmanager wie npm, Composer oder pip bieten für Abhängigkeiten, die Sie nur konsumieren und nie ändern, einen einfacheren Weg. Dagegen schafft ein Monorepo Ansatz separate Repositorys ganz ab und sammelt alles in einem einzigen. Welche Wahl richtig ist, hängt davon ab, wie oft Sie die Abhängigkeit anfassen und wie Ihr Team arbeitet.

Der einfachste Weg für ein neues Projekt besteht oft darin, auf Submodules zu verzichten, solange sie nicht wirklich nötig sind. Die Flexibilität eines Submodules bringt die Last mit sich, zusätzliche Befehle in der richtigen Reihenfolge zu merken, und diese Last sollte gegen die tatsächliche Nutzungshäufigkeit der Abhängigkeit abgewogen werden.

Daher erspart es später den Aufwand eines Methodenwechsels, diese Abwägung früh im Projekt zu treffen. Es einfach zu halten, solange das Team klein ist, und das passende Werkzeug zu wählen, sobald der Bedarf mit dem Wachstum deutlich wird, ist meist der gesündeste Weg.

Worauf Achten Sie Bei Einer Open Source Abhängigkeit Als Submodule?

Fügen Sie eine Open Source Bibliothek als Git Submodule hinzu, prüfen Sie zuerst deren Lizenz und Beitragsregeln. Wollen Sie Korrekturen zurück an das Projekt schicken, ist es praktisch, von einem eigenen Fork aus zu arbeiten. Konkret richten Sie dafür das Feld url des Submodules auf diesen Fork. Unseren Leitfaden Zu Open Source beitragen, GitHub Leitfaden für Einsteiger können Sie für diesen Prozess ausführlicher nutzen.

Arbeiten Sie von einem Fork aus, müssen Sie von Zeit zu Zeit Upstream Aktualisierungen hineinziehen. Sonst entfernt sich Ihr Submodule immer weiter vom eigentlichen Projekt. Diese Synchronisation zur festen Gewohnheit zu machen, verhindert, dass später ein großer Abstand entsteht.

Was Passiert, Wenn Eine .env Datei Im Submodule Versehentlich Committed Wird?

Da ein Submodule ein eigenes Repository ist, gelten dort auch eigene .gitignore Regeln. Die Regeln des übergeordneten Projekts erfassen es nicht. Wird eine .env Datei versehentlich im Submodule committed, sitzt das Leck in der Historie dieses Submodules, und das übergeordnete Projekt allein zu bereinigen reicht nicht aus. Unseren Leitfaden Env Datei versehentlich in Git committed, Lösung wenden Sie in diesem Fall direkt auf das eigene Repository des Submodules an.

Deshalb braucht jedes Submodule eine eigene, ebenso sorgfältig vorbereitete .gitignore Datei wie das übergeordnete Projekt. Eines der ersten Dinge, die Sie beim Hinzufügen eines neuen Submodules prüfen sollten, ist, ob sensible Dateien dort ebenfalls korrekt ausgeschlossen sind.

Welche Entwicklungswerkzeuge Passen Gut Zu Einem Git Submodule?

Soll Ihr gesamtes Team ein Submodule Projekt auf dieselbe Weise betreiben, hilft eine einheitliche Entwicklungsumgebung. Eine containerbasierte Umgebung kann die Schritte Klonen und Aktualisieren für Submodules automatisieren. Diesen Ansatz behandeln wir in unserem Artikel Was ist ein VS Code Dev Container. Auch Werkzeuge zur Codeformatierung brauchen über alle Submodules hinweg dieselben Regeln, um konsistent zu bleiben. Dafür ist unser Beitrag zum Lösen von Git Konflikten eine nützliche Ergänzung.

Vergessen Sie auch Installationsskripte nicht. Manche Teams führen nach dem Klonen eines Submodules direkt pnpm install im entsprechenden Unterordner aus. Diesen Schritt in das Setup Skript aufzunehmen, verringert die Anzahl der Handgriffe, die sich ein neuer Entwickler merken muss.

Wer Richtet Eine Git Submodule Struktur Richtig Ein?

Bei Talha Aslan und Team begegnen wir in individuellen Softwareprojekten häufig Situationen, in denen mehrere Komponenten in getrennten Repositorys liegen, aber unter einem gemeinsamen Dach entwickelt werden. In solchen Fällen richten wir die Git Submodule Struktur ein und bereiten die interne Dokumentation für das Team vor. Brauchen Sie eine solche Projektumgebung, lohnt sich ein Blick auf unsere individuelle Softwareentwicklung. Eine korrekt eingerichtete Submodule Struktur bewahrt das Team später vor Verwirrung.

Worauf wir bei der Einrichtung achten, ist, ob die technische Entscheidung zum Arbeitsalltag des Teams passt. Manchmal ist eine einfachere Lösung besser als ein Submodule. Diese Entscheidung setzt voraus, zu verstehen, wie oft das Team eine bestimmte Komponente wirklich anfasst.

Diese Abwägung früh und gemeinsam zu treffen und die Entscheidung schriftlich festzuhalten, gibt dem Team später eine fertige Antwort auf die Frage, warum etwas so eingerichtet wurde. Eine kurze Notiz kann Monate später viel Zeit sparen.

Wie Behalten Sie Die Git Submodule Befehle Im Kopf?

Die meisten Submodule Befehle erweitern den Unterbefehl git submodule: add, init, update, sync, foreach. Sie müssen diese nicht auswendig lernen. Entscheidend ist, zu erkennen, welche Situation welchen Befehl braucht. Unseren Git und GitHub Leitfaden mit den wichtigsten Befehlen können Sie als Auffrischung der grundlegenden Schritte vor Submodules heranziehen.

Ein Tipp: Binden Sie häufig genutzte Befehle an kurze Aliase, das beschleunigt die tägliche Arbeit. Einen langen Aktualisierungsbefehl an einen kurzen Alias zu binden bedeutet, dass Sie sich die richtigen Optionen nie mehr aus dem Gedächtnis zusammenreimen müssen, und das verringert zugleich die Fehlerquote.

Zum Schluss hilft eine kleine Übung, wenn Sie eine Git Submodule Struktur im Team einführen: Ein neuer Entwickler klont das Repository, führt eine Aktualisierung aus und nimmt im Submodule absichtlich eine kleine Änderung vor, die er anschließend wieder zurücknimmt. Diese kurze Übung zeigt, wie sich die Befehle in der Praxis verhalten und nicht nur auf dem Papier, und nimmt die Panik vor dem ersten echten Problem.