Git Submodules – Kurzanleitung #

Einleitung #

Wer mit Git arbeitet, kommt früher oder später an den Punkt, an dem „einfach reinkopieren“ nicht mehr sauber ist.

Libraries werden doppelt gepflegt. Fixes landen nicht überall. Versionen driften auseinander.

Und plötzlich baut man sich schleichend ein System, das nur noch durch Glück zusammenhält.

Submodules sind der Versuch, genau das zu verhindern.

Die Idee ist eigentlich bestechend klar: Fremder oder gemeinsamer Code bleibt ein eigenes Repository – und wird im Hauptprojekt nicht integriert, sondern referenziert. Kein Vermischen, kein Verwässern, keine stillen Änderungen. Stattdessen ein klar definierter Zustand: genau dieser Commit, nicht mehr und nicht weniger.

Das ist sauber. Das ist ehrlich. Aber es ist auch kompromisslos.

Submodules nehmen dir nichts ab. Sie machen sichtbar, wo vorher geschludert wurde. Und sie bestrafen jeden, der glaubt, Git würde schon „irgendwie mitdenken“.

Wenn man sie verstanden hat, sind sie ein starkes Werkzeug. Wenn nicht, sind sie eine Quelle für konstanten Frust.

Diese Anleitung zeigt dir den Unterschied.

Was sind Submodules bei Git? #

Ein Submodule ist ein separates Git-Repository, das in ein anderes Repository eingebunden wird. Es wird als fester Commit referenziert, nicht als Branch.

Typischer Einsatz:

• Externe Libraries
• Gemeinsame Komponenten
• Getrennte Projekte mit klarer Versionierung

Voraussetzungen #

Installiertes Git

Submodule hinzufügen #

git submodule add <repo-url> <zielpfad>

Beispiel:

git submodule add https://github.com/example/lib.git libs/lib

Danach:

git commit -m "Add submodule lib"

Repository mit Submodules klonen #

git clone --recurse-submodules <repo-url>

Falls bereits geklont:

git submodule update --init --recursive

Submodule aktualisieren #

Auf neuesten Stand des Remote-Branches: #

cd libs/lib
git pull origin main
cd ../..
git add libs/lib
git commit -m "Update submodule"

Alternativ automatisch: #

git submodule update --remote

Status prüfen #

git submodule status

Änderungen im Submodule committen #

Wichtig: Submodules sind eigene Repos!

cd libs/lib
git add .
git commit -m "Fix in submodule"
git push

Dann im Hauptrepo:

cd ../..
git add libs/lib
git commit -m "Update submodule pointer"

Submodule entfernen #

git submodule deinit -f libs/lib
git rm -f libs/lib
rm -rf .git/modules/libs/lib

Commit nicht vergessen:

git commit -m "Remove submodule"

Typische Stolperfallen #

• Submodules zeigen auf Commits, nicht automatisch auf Branches
• Änderungen im Submodule müssen separat gepusht werden
• Nach Clone oft vergessen: --recurse-submodules
• CI/CD braucht explizites Submodule-Update

Empfehlung aus der Praxis #

Submodules sind mächtig, aber unbequem. Nutze sie nur wenn:

• klare Trennung notwendig ist (2 oder mehr Projekte)
• Versionierung unabhängig bleiben soll

Für einfachere Fälle oft besser:

• Monorepo
• oder Dependency-Manager

Schlussgedanke #

Submodules sind kein Komfort-Feature. Sie sind eine Entscheidung.

Eine Entscheidung für klare Grenzen. Für explizite Versionierung. Und gegen das „wird schon passen“-Prinzip, das in vielen Projekten erstaunlich lange überlebt.

Wer Submodules einsetzt, übernimmt Verantwortung: für Abhängigkeiten, für Zustände, für Reproduzierbarkeit.

Das ist unbequem. Aber genau darin liegt der Wert.

Wenn du ein kleines Projekt hast, wirst du sie nicht brauchen. Wenn du schnell etwas zusammensteckst, werden sie dich eher ausbremsen.

Aber sobald mehrere Komponenten zusammenspielen, sobald Code geteilt wird, sobald Stabilität zählt – dann sind Submodules kein Overhead mehr, sondern Struktur.

Und Struktur ist das, was am Ende den Unterschied macht zwischen „läuft gerade so“ und „funktioniert verlässlich“.