6.2 KiB
Git-Submodule: Der umfassende Praxisleitfaden
Inhalt
- Git-Submodule: Der umfassende Praxisleitfaden
- Inhalt
- 🔰 Was ist ein Git-Submodul?
- 🧱 Grundlagen
- 🛠️ Submodul hinzufügen
- 🔄 Submodule aktualisieren
- 📥 Klonen mit Submodulen
- 🔃 Submodul-Synchronisation
- 📂 Weitere Remotes im Submodul
- ❗ Stolperfallen und Besonderheiten
- 🔄 Remote-URL wechseln
- 🚀 Push & Pull Verhalten
- 🧼 Submodul löschen
- 🧰 Best Practices
- 📎 Nützliche Kommandos
- 📑 Beispiel
.gitmodulesmit kommentierter Remote-Auswahl - 🧭 Alternative: Subtree statt Submodul?
- 📚 Fazit
- 🔗 Weiterführende Links
🔰 Was ist ein Git-Submodul?
Ein Submodul ist ein Git-Repository innerhalb eines anderen Git-Repositories. Es erlaubt, einen festen Commit eines externen Repositories als Teilprojekt einzubinden, ohne dessen Dateien direkt zu übernehmen.
Beispielhafte Struktur:
hauptprojekt/
├── .gitmodules
├── modul1/ ← eingebundenes Submodul
└── modul2/
🧱 Grundlagen
📌 .gitmodules
Diese Datei beschreibt Pfad und Remote-URL aller eingebundenen Submodule:
[submodule "modul1"]
path = modul1
url = git@github.com:user/modul1.git
🧠 Merksatz
Submodule sind Pointer auf einen bestimmten Commit eines anderen Repositories.
🛠️ Submodul hinzufügen
git submodule add <repo-url> <zielpfad>
git commit -m "📦 Submodul hinzugefügt"
Beispiel:
git submodule add git@github.com:user/libmath.git extern/libmath
Erzeugt:
.gitmodules- Verzeichniseintrag im Git-Index
- Initialer Checkout des Submoduls (HEAD auf Remote-Commit)
🔄 Submodule aktualisieren
cd extern/libmath
git pull origin main
cd ../..
git add extern/libmath
git commit -m "🔄 Submodul libmath aktualisiert"
Nur das Hauptrepo speichert den Commit-Zeiger, nicht den Submodul-Inhalt selbst.
📥 Klonen mit Submodulen
Methode 1: Inklusive Submodule
git clone --recurse-submodules <url>
Methode 2: Nachträglich initialisieren
git clone <url>
git submodule update --init
🔃 Submodul-Synchronisation
Wenn sich .gitmodules ändert (z. B. Remote-URL):
git submodule sync
📂 Weitere Remotes im Submodul
cd modul1
git remote add backup git@backup.server:repo.git
Diese Remotes sind lokal, nicht versioniert.
.gitmoduleskennt nur den Haupt-Remote.
❗ Stolperfallen und Besonderheiten
| Problem | Erklärung |
|---|---|
| Submodul wird nicht mitgeclont | --recurse-submodules vergessen |
| Änderungen im Submodul nicht sichtbar | Submodul-Commit im Hauptrepo nicht geupdated |
.gitmodules zeigt nicht funktionierende URL |
z. B. lokale URL nach GitHub-Push – muss angepasst werden |
| Submodul zeigt „detached HEAD“ | normaler Zustand, wenn Submodul auf festen Commit gesetzt ist |
🔄 Remote-URL wechseln
# In .gitmodules ändern oder per Befehl:
git config -f .gitmodules submodule.modul1.url git@github.com:newuser/libmath.git
git submodule sync
🚀 Push & Pull Verhalten
| Aktion | Wirkung |
|---|---|
git push im Hauptrepo |
Pusht nur Zeiger auf Submodul-Commit |
git push im Submodul |
Muss separat erfolgen |
git pull im Hauptrepo |
Holt nicht automatisch neuen Submodul-Stand |
🧼 Submodul löschen
# Schritt 1: Entfernen
git submodule deinit -f pfad/zum/modul
git rm -f pfad/zum/modul
rm -rf .git/modules/pfad/zum/modul
git commit -m "❌ Submodul entfernt"
🧰 Best Practices
- Nur stabile Submodul-Commits einchecken, keine laufenden Branches.
- Submodule niemals blind aktualisieren – Änderungen genau prüfen.
- Remote-Umschaltung dokumentieren oder automatisieren, z. B. per Script.
- Submodule klein halten – große, tief verschachtelte Strukturen vermeiden.
- Für wiederverwendbare Bibliotheken oder Assets ideal (CAD, Snippets, Markdown, etc.).
📎 Nützliche Kommandos
git submodule status # Überblick über alle Submodule
git submodule update --init # Submodule initial holen
git submodule update --remote # Auf neuesten Remote-Stand updaten
git config -f .gitmodules ... # .gitmodules direkt bearbeiten
📑 Beispiel .gitmodules mit kommentierter Remote-Auswahl
[submodule "modul1"]
path = modul1
url = ssh://git@local.example.com:2222/myorg/modul1.git
# url = git@github.com:myorg/modul1.git
🧭 Alternative: Subtree statt Submodul?
Subtree ist einfacher zu verwalten, aber:
- kein fester Commit-Zeiger,
- kein Remote-Wechsel ohne Umweg,
- gemergte Historie im Hauptrepo.
Submodul = getrennte Repos
Subtree = eingemergter Inhalt
📚 Fazit
Git-Submodule sind mächtig, aber erfordern Disziplin und Überblick. Für wiederverwendbare Komponenten, zentral gepflegte Inhalte oder externe Bibliotheken sind sie oft die bessere Wahl als Duplikate oder Copy-Paste.