Git Submodule Tutorial: Hinzufügen, Klonen & Aktualisieren

Git-Submodule ermöglichen es, ein Git-Repository in ein anderes einzubinden. Sie sind nützlich, um gemeinsam genutzte Bibliotheken, Fremdcode oder wiederverwendbare Komponenten in mehreren Projekten einzusetzen, ohne Dateien zu duplizieren. Jedes Submodul verweist auf einen bestimmten Commit eines externen Repositories und behält dadurch seine eigene Historie und Konfiguration, getrennt vom Hauptprojekt.

In dieser Anleitung erfahren Sie, wie Sie Git-Submodule hinzufügen, klonen, aktualisieren und verwalten. Zudem erhalten Sie praktische Befehle und Hinweise, um typische Fehler zu vermeiden.

Die Kurzversion

Ein Submodul zu Ihrem Repository hinzufügen

$ git submodule add https://github.com/user/repo.git path/to/submodule

Submodule in einem geklonten Repository initialisieren

$ git submodule init

Submodule aktualisieren, um Inhalte zu laden

$ git submodule update

Repository und Submodule in einem Schritt klonen

$ git clone --recurse-submodules https://github.com/user/project.git

Neueste Commits aus dem Remote-Submodul ziehen

$ git submodule update --remote

Ein Submodul vollständig entfernen

$ git submodule deinit -f path/to/submodule
$ rm -rf path/to/submodule
$ git rm path/to/submodule
$ rm .gitmodules

Ein Git-Submodul hinzufügen

Submodule erlauben es, ein weiteres Git-Repository in Ihr Projekt einzubinden, wobei dessen Versionshistorie und Konfiguration eigenständig bleiben. In diesem Abschnitt wird gezeigt, wie Sie ein Submodul zu einem bereits initialisierten Git-Projekt hinzufügen.

Befehlssyntax

Um ein Submodul einzubinden, verwenden Sie:

git submodule add <submodule-url> <path>

• <submodule-url>: Die Remote-URL des Git-Repositories, das hinzugefügt werden soll.
• <path>: Das Zielverzeichnis innerhalb Ihres Projekts, in dem das Submodul abgelegt wird.

Git speichert diesen Verweis in einer .gitmodules-Datei und behandelt das Submodul als Verweis auf einen bestimmten Commit.

Befehls-Demonstration

Erstellen Sie ein Projektverzeichnis:

$ mkdir my-project && cd my-project

Initialisieren Sie das Verzeichnis als Git-Repository:

$ git init

Fügen Sie ein Submodul hinzu:

$ git submodule add https://github.com/example/repo.git vendor/example-lib

Dieser Befehl klont das externe Repository in den Ordner vendor/example-lib und erzeugt eine .gitmodules-Datei.

Prüfen Sie die .gitmodules-Datei:

$ cat .gitmodules

Ausgabe:

[submodule "vendor/example-lib"]
    path = vendor/example-lib
    url = https://github.com/example/repo.git

Stagen Sie die .gitmodules-Datei und den Submodul-Ordner:

$ git add .gitmodules vendor/example-lib

Committen Sie die Hinzufügung des Submoduls:

$ git commit -m "Add example-lib as submodule"

Pushen Sie die Änderungen in das Remote-Repository:

$ git push origin main

Ein Repository mit Git-Submodulen klonen

Beim Klonen eines Repositories mit Submodulen lädt Git die Inhalte der Submodule nicht automatisch, sofern es nicht ausdrücklich angewiesen wird. In diesem Abschnitt erfahren Sie, wie Submodule korrekt initialisiert und aktualisiert werden.

Befehlssyntax

Um Submodule nach dem Klonen manuell zu initialisieren und zu aktualisieren:

git clone <repo-url>
cd <repo-name>
git submodule init
git submodule update

Um Repository und Submodule in einem Schritt zu klonen:

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

• --recurse-submodules: Klont und initialisiert alle Submodule während des ersten Klonens automatisch.
• git submodule init: Registriert die in .gitmodules definierten Submodule.
• git submodule update: Lädt die Inhalte der Submodule herunter.

Um Submodule auf die neuesten Commits der Remote-Quelle zu aktualisieren:

git submodule update --remote

• --remote: Holt den aktuellsten Commit vom verfolgten Remote-Branch des Submoduls.

Befehls-Demonstration

Klonen Sie das Haupt-Repository:

$ git clone https://github.com/example/project.git

Wechseln Sie in das Projektverzeichnis:

$ cd project

Initialisieren Sie die in .gitmodules definierten Submodule:

$ git submodule init

Holen Sie die Inhalte der Submodule:

$ git submodule update

Alternative: Repository und Submodule in einem Schritt klonen:

$ git clone --recurse-submodules https://github.com/example/project.git

Optional: Submodule auf den neuesten Commit des Remote-Branches aktualisieren:

$ git submodule update --remote

Standardmäßig zeigen Submodule auf einen festen Commit. Verwenden Sie --remote nur, wenn Sie auf den neuesten Upstream-Commit des verfolgten Branches synchronisieren möchten.

Wichtige Hinweise beim Einsatz von Git-Submodulen

• Submodule verweisen auf Commits, nicht auf Branches.

  Standardmäßig sind Submodule an einen bestimmten Commit gebunden. Sie folgen nicht automatisch den neuesten Änderungen im Remote-Repository. Aktualisierungen müssen manuell mit git submodule update --remote erfolgen.

• Aktualisierungen von Submodulen müssen committed werden.

  Wenn ein Submodul auf einen neuen Commit gesetzt wird, betrachtet das Haupt-Repository dies als Änderung. Sie müssen diesen Zeiger explizit stagen und committen.

• Klonen erfordert zusätzliche Schritte.

  Nutzer müssen entweder git submodule init und git submodule update ausführen oder direkt mit --recurse-submodules klonen.

• Workflows werden komplexer.

  Wenn unterschiedliche Branches auf verschiedene Submodule-Commits verweisen, können Merges oder Rebases kompliziert werden. Abstimmung im Team ist daher wichtig.

• CI/CD-Pipelines benötigen Submodul-Handling.

  Automatisierte Build- oder Deployment-Prozesse müssen Logik enthalten, um Submodule zu holen und zu aktualisieren. Ein häufiger Fehler ist das Vergessen des Parameters --recurse-submodules.

Verwenden Sie Submodule nur, wenn eine unabhängige Versionsverwaltung externer Codebasen zwingend erforderlich ist. Andernfalls sind Lösungen wie Paketmanager oder Monorepo-Strukturen oft einfacher zu pflegen.

Ein Git-Submodul entfernen

Wenn Sie ein Git-Submodul nicht mehr benötigen, führen Sie folgende Schritte aus, um es vollständig zu entfernen:

Submodul deinitialisieren:

$ git submodule deinit -f vendor/example-lib

Submodul-Verzeichnis löschen:

$ rm -rf vendor/example-lib

Submodul-Eintrag aus .gitmodules entfernen:

$ git config -f .gitmodules --remove-section submodule.vendor/example-lib

Geänderte .gitmodules-Datei zum Commit vormerken:

$ git add .gitmodules

Submodul-Konfiguration aus Git entfernen:

$ git config --remove-section submodule.vendor/example-lib

Submodul aus dem Git-Index löschen:

$ git rm --cached vendor/example-lib

Aufräum-Commit erstellen:

$ git commit -m "Remove vendor/example-lib submodule"

Änderungen ins Remote-Repository pushen:

$ git push origin main

Diese Schritte sorgen dafür, dass alle Referenzen zum Submodul vollständig aus Ihrem Git-Projekt entfernt werden.

Fazit

In dieser Anleitung haben Sie gelernt, wie Git-Submodule verwendet werden, um wiederverwendbaren Code in mehreren Projekten zu organisieren. Sie haben Submodule hinzugefügt, Repositories mit Submodulen geklont, Aktualisierungen aus der Remote-Quelle eingespielt und Submodule bei Bedarf entfernt. Durch den richtigen Einsatz von Submodulen bleiben Projektstrukturen modular, Code-Duplikate werden vermieden und Versionskonsistenz über Abhängigkeiten hinweg sichergestellt.