Übersicht

git submodule add <url> <path>
git submodule update --init --recursive
git submodule foreach <cmd>

Beschreibung

Der git submodule-Befehl bettet ein externes Git-Repository in einem anderen bei einem festen Commit ein. Das Eltern-Repo zeichnet die Submodule-URL und den exakten auszucheckenden SHA auf, was Eltern- und Kind-Historien entkoppelt. Das ist nützlich zum Vendoring geteilter Bibliotheken oder zum Komponieren von Multi-Repo-Systemen.

Submodules sind mächtig, haben aber den Ruf, Verwirrung zu stiften. Nach dem Klonen eines Projekts mit Submodules müssen Sie git submodule update --init --recursive ausführen, um sie zu befüllen. Das Aktualisieren auf einen neueren Submodule-Commit ist ein zweistufiger Tanz: im Submodule pullen, dann den neuen SHA im Elternteil committen.

Im täglichen Einsatz integriert sich git submodule eng mit Shell-Aliasen, Editor-Plugins und Continuous Integration. Power-User fügen oft Aliase hinzu, die Flags kombinieren, die sie immer übergeben, oder wickeln den Befehl in Skripte, die Teamkonventionen durchsetzen. Die Ausgabeformatierung kann über Git-Config angepasst werden — Pretty-Formate, Farbschemata und Pager-Verhalten sind alle einstellbar. Wenn etwas schiefgeht, ist der erste Diagnoseschritt üblicherweise, den Befehl erneut mit GIT_TRACE=1 in der Umgebung auszuführen, was die zugrunde liegenden Plumbing-Aufrufe offenlegt. Für ungewöhnliche Situationen öffnet die --help-Ausgabe (git submodule --help) die vollständige Manpage mit Details zu jeder Option, einschließlich solcher, die in alltäglichen Workflows selten verwendet werden, aber für Debugging oder Skripting im großen Maßstab essentiell sind.

Zu verstehen, wie git submodule mit dem Rest von Gits Datenmodell interagiert — der Objektdatenbank, dem Index, Refs und dem Working Tree — zahlt sich aus. Jeder Befehl operiert auf einer Teilmenge dieser Stücke, und zu wissen, welche er berührt, hilft Ergebnisse vorherzusagen und sich von Fehlern zu erholen. Das Lesen der offiziellen Git-Dokumentation neben praktischer Übung in einem Wegwerf-Repository ist der schnellste Weg, die Nuancen zu verinnerlichen. Die meisten Produktionsprobleme mit Git rühren von einer von drei Ursachen: überraschendem Standardverhalten, partiellen Netzwerkoperationen oder dem Umschreiben bereits geteilter Historie. Ein funktionierendes mentales Modell der Nebenwirkungen von git submodule hilft, alle drei zu vermeiden.

Häufige Optionen

Unterbefehl	Beschreibung
add <url> <path>	Fügt ein neues Submodule hinzu.
init	Registriert Submodule-URLs in .git/config.
update --init	Initialisiert und checkt Submodules aus.
update --recursive	Rekurriert in verschachtelte Submodules.
update --remote	Aktualisiert auf die Spitze des Upstream-Branches.
foreach <cmd>	Führt einen Befehl in jedem Submodule aus.
deinit <path>	Entfernt ein Submodule aus dem Working Tree.

Beispiele

git submodule add https://github.com/lib/foo.git vendor/foo
    # Ein neues Submodule unter vendor/foo hinzufügen

    git clone --recurse-submodules https://github.com/me/parent.git
    # Mit Submodules in einem Schritt klonen

    git submodule update --init --recursive
    # Alle Submodules initialisieren und befüllen

    git submodule foreach 'git pull origin main'
    # Jedes Submodule auf seine main-Branch-Spitze aktualisieren

Häufige Fehler

Vergessen, --recurse-submodules beim Klonen zu verwenden, hinterlässt leere Submodule-Verzeichnisse. Den Eltern-Repo zu pushen, ohne zuerst Submodule-Änderungen zu pushen, hinterlässt eine dangling Referenz für Mitwirkende. Viele Teams wechseln zu git subtree oder Monorepos, um der Submodule-Komplexität zu entkommen.

Verwandte Befehle

git subtree, git clone --recurse-submodules, git config submodule