Git-Submodul

Was ist ein Submodul

Sehr oft hängt ein Code-Repository von externem Code aus anderen Repositories ab. Sie können den externen Code direkt in das Haupt-Repository kopieren und einfügen oder das Paketverwaltungssystem einer Sprache verwenden. Beide Methoden haben jedoch den Nachteil, dass Änderungen am externen Repository nicht nachverfolgt werden. Git ermöglicht es, andere Git-Repositories, sogenannte Submodule, in ein einzelnes Repository einzubinden. Submodule ermöglichen es, Änderungen über mehrere Repositories hinweg von einem einzigen übergeordneten Repository aus nachzuverfolgen. Submodule sind Repositories, die im übergeordneten Repository an einem bestimmten Pfad im Arbeitsverzeichnis enthalten sind. Sie können sich überall im Arbeitsverzeichnis befinden und werden über die Datei .gitmodules konfiguriert, die sich im Stammverzeichnis des übergeordneten Repositorys befindet. Die Datei .gitmodules enthält Metadaten über die Zuordnung zwischen der URL des Submodul-Projekts und dem lokalen Verzeichnis. Submodule unterstützen das Hinzufügen, Synchronisieren, Aktualisieren und Klonen. Submodule verfolgen nur bestimmte Commits, keine Git-Referenzen oder Branches.

Wann man Submodule verwenden sollte

Die Arbeit mit Submodulen ist knifflig, daher empfehlen wir einige typische Anwendungsfälle.

• Wenn sich das Unterprojekt zu schnell ändert oder bevorstehende Änderungen die API brechen werden, sperren Sie den Code aus Sicherheitsgründen auf einen bestimmten Commit.
• Wenn eine Komponente nicht sehr oft aktualisiert wird und Sie sie als Vendor-Abhängigkeit verfolgen möchten.
• Wenn Sie einen Teil des Projekts gegenüber Dritten vertreten und deren Arbeit zu einem bestimmten Zeitpunkt integrieren möchten (funktioniert nur, wenn Updates nicht zu häufig sind).
• Wenn der technologische Kontext Paketierung und formale Abhängigkeitsverwaltung zulässt, sollten Sie Paketmanager statt Submodule verwenden.
• Wenn Ihre Codebasis riesig ist und Sie sie nicht jedes Mal abrufen möchten, verwenden Sie Submodule, um zu verhindern, dass Mitwirkende die gesamte Codebasis herunterladen.

Befehle für Git-Submodule

Um ein neues Submodul zu einem bestehenden Repository zu erstellen, verwenden Sie git submodule add.

create a new submodule to the existing repository git

mkdir git-submodule-demo
cd git-submodule-demo/
git init

Initialized empty Git repository in /Users/example/git-submodule-demo/.git/

Um ein Submodul zum neuen Repository hinzuzufügen, führen Sie Folgendes aus:

add submodule to the new repository git

git submodule add https://somehost/example/textexample

Cloning into '/Users/example/git-submodule-demo/textexample'...
remote: Counting objects: 8, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 8 (delta 1), reused 0 (delta 0)
Unpacking objects: 100% (8/8), done.

Der Befehl git submodule add nimmt eine URL entgegen, die auf ein Git-Repository verweist. Git klont das Submodul textexample sofort. Überprüfen Sie den Zustand des Repositorys mit dem Befehl git status:

check the state of the repository git status

git status

On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

 new file: .gitmodules
 new file: textexample

Sie können die Dateien mit den Befehlen git add und git commit in das Repository übernehmen:

commit the files git

git add .gitmodules textexample/
git commit -m "added submodule"

[master (root-commit) d5002d0] added submodule
 2 files changed, 4 insertions(+)
 create mode 100644 .gitmodules
 create mode 160000 textexample

Submodule aktualisieren

Teammitglieder sollten den Code des Submoduls aktualisieren, wenn er andernorts geändert wurde. Sie können git pull nicht verwenden, da dadurch nur die Referenz des übergeordneten Repositorys auf den Submodul-Commit aktualisiert wird, nicht der eigentliche Submodul-Code. Um das Submodul auf den aufgezeichneten Commit zu aktualisieren, führen Sie Folgendes aus:

updating the code of the submodule git

git submodule update

Hinweis: Ohne das Flag --remote prüft dieser Befehl nur den im übergeordneten Repository aufgezeichneten Commit aus und ruft keine neuen Upstream-Änderungen ab.

Wenn die Datei .gitmodules aktualisiert wird (zum Beispiel wenn sich die Submodul-URL ändert), führen Sie git submodule sync aus, um die lokale .git/config mit den neuen URLs zu aktualisieren, bevor Sie git submodule update ausführen.

Git-Submodule klonen

Um ein Projekt mit Submodulen zu klonen, verwenden Sie den Befehl git clone. Standardmäßig klont er das übergeordnete Repository, lässt aber die Submodul-Verzeichnisse leer. Danach müssen Sie git submodule init und git submodule update ausführen. Der erste Befehl aktualisiert die lokale .git/config mit den Zuordnungen aus .gitmodules, während der zweite die Submodul-Daten abruft und den aufgezeichneten Commit auscheckt.

Alternativ können Sie beim git clone-Befehl das Flag --recursive verwenden, um Submodule automatisch zu initialisieren und zu aktualisieren. Wenn Sie ohne --recursive geklont haben, führen Sie Folgendes aus:

git clone command initializes and updates submodules

git clone /url/to/repo/with/submodules
git submodule init
git submodule update

Den Code des Submoduls abrufen

Wenn Sie ein Repository mit neuen Submodulen ziehen, müssen andere Teammitglieder diese initialisieren. Führen Sie zuerst git pull aus, um den neuesten Zustand des übergeordneten Repositorys abzurufen. Wenn neue Submodule aufgeführt sind, initialisieren Sie sie mit:

initiate new submodules git

git submodule init

Beachten Sie, dass init nur die lokale Datei .git/config aktualisiert. Um den Code tatsächlich abzurufen und den aufgezeichneten Commit auszuchecken, müssen Sie git submodule update ausführen.

Updates in Submodulen pushen

Da ein Submodul ein separates Repository ist, können Sie Änderungen daran wie an jedem normalen Git-Repository pushen, indem Sie Befehle innerhalb des Verzeichnisses des Submoduls ausführen. Wenn Sie neue Commits innerhalb des Submoduls erstellen, verweist das übergeordnete Repository weiterhin auf den alten Commit. Um das übergeordnete Repository auf den neuen Commit zu aktualisieren, führen Sie git add für das Verzeichnis des Submoduls aus, committen und pushen Sie dann. Wenn Sie git status im Haupt-Repository ausführen, wird das Submodul als „Changes not staged for commit“ mit der Meldung „modified content (new commits)“ angezeigt. Das bedeutet, dass der Code des Submoduls auf einem anderen Commit ausgecheckt ist, als das übergeordnete Repository erwartet.

Submodule sind eine gute Möglichkeit, Projekte in getrennten Repositories zu halten und sie dennoch als Ordner im Arbeitsverzeichnis eines anderen Repositorys zu referenzieren. Beachten Sie jedoch, dass Submodule für viele Projekte nicht die beste Vorgehensweise sind und die Arbeit mit ihnen knifflig sein kann.

Practice

What are the key aspects of using Git submodules?

Git submodules allow including other repositories within a parent repository and tracking changes in several repositories via one repository.The command 'git submodule add' is used for copying and pasting external code into the main repository.The '.gitmodules' file contains metadata about the mapping between the submodule's URL and local directory.Submodules are updated automatically when the parent repository is updated using 'git pull'.To update the code of a submodule, the command 'git submodule update' should be used.Cloning a repository with submodules requires running 'git clone', followed by 'git submodule init' and 'git submodule update'.Changes made inside a submodule can be pushed directly from the submodule's directory.