English ▾ Themen ▾ Neueste Version ▾ gitsubmodules zuletzt aktualisiert in 2.52.0

NAME

gitsubmodules - Ein Repository in ein anderes einbetten

SYNOPSIS

.gitmodules, $GIT_DIR/config
git submodule
git <command> --recurse-submodules

BESCHREIBUNG

Ein Submodul ist ein Repository, das in ein anderes Repository eingebettet ist. Das Submodul hat seine eigene Historie; das Repository, in das es eingebettet ist, wird als Superprojekt bezeichnet.

Auf dem Dateisystem besteht ein Submodul normalerweise (aber nicht immer - siehe FORMEN unten) aus (i) einem Git-Verzeichnis unter dem $GIT_DIR/modules/ Verzeichnis seines Superprojekts, (ii) einem Arbeitsverzeichnis innerhalb des Arbeitsverzeichnisses des Superprojekts und einer .git-Datei am Stammverzeichnis des Arbeitsverzeichnisses des Submoduls, die auf (i) verweist.

Unter der Annahme, dass das Submodul ein Git-Verzeichnis unter $GIT_DIR/modules/foo/ und ein Arbeitsverzeichnis unter path/to/bar/ hat, verfolgt das Superprojekt das Submodul über einen gitlink-Eintrag im Baum unter path/to/bar und einen Eintrag in seiner .gitmodules-Datei (siehe gitmodules[5]) der Form submodule.foo.path = path/to/bar.

Der gitlink-Eintrag enthält den Objektname des Commits, an dem das Superprojekt erwartet, dass sich das Arbeitsverzeichnis des Submoduls befindet.

Der Abschnitt submodule.foo.* in der .gitmodules-Datei gibt zusätzliche Hinweise an die Porcelain-Schicht von Git. Zum Beispiel gibt die Einstellung submodule.foo.url an, wo das Submodul bezogen werden soll.

Submodule können für mindestens zwei verschiedene Anwendungsfälle verwendet werden

  1. Verwendung eines anderen Projekts unter Beibehaltung einer unabhängigen Historie. Submodule ermöglichen es Ihnen, den Arbeitsbaum eines anderen Projekts innerhalb Ihres eigenen Arbeitsbaums zu enthalten, während die Historie beider Projekte getrennt gehalten wird. Da Submodule an eine beliebige Version gebunden sind, kann das andere Projekt unabhängig entwickelt werden, ohne das Superprojekt zu beeinträchtigen, wodurch das Superprojektprojekt nur dann an neue Versionen gebunden wird, wenn dies gewünscht wird.

  2. Aufteilung eines (logisch einzelnen) Projekts in mehrere Repositories und deren Wiederverbindung. Dies kann verwendet werden, um aktuelle Einschränkungen der Git-Implementierung zur Erzielung einer feingranularen Zugriffskontrolle zu überwinden.

    • Größe des Git-Repositorys: In seiner aktuellen Form skaliert Git schlecht für große Repositorys, die Inhalte enthalten, die nicht durch Delta-Berechnungen zwischen Bäumen komprimiert werden. Sie können beispielsweise Submodule verwenden, um große Binärdateien zu speichern, und diese Repositorys können flach geklont werden, sodass Sie lokal keine große Historie haben.

    • Übertragungsgröße: In seiner aktuellen Form benötigt Git den gesamten Arbeitsbaum. Es erlaubt keine teilweisen Bäume, die bei `fetch` oder `clone` übertragen werden. Wenn das Projekt, an dem Sie arbeiten, aus mehreren Repositorys besteht, die als Submodule in einem Superprojekt zusammengebunden sind, können Sie die Arbeitsbäume von Repositorys, an denen Sie nicht interessiert sind, vermeiden.

    • Zugriffskontrolle: Durch die Einschränkung des Benutzerzugriffs auf Submodule kann dies zur Implementierung von Lese-/Schreibrichtlinien für verschiedene Benutzer verwendet werden.

Die Konfiguration von Submodulen

Submoduloperationen können mit den folgenden Mechanismen konfiguriert werden (von höchster zu niedrigster Priorität)

  • Die Kommandozeile für diejenigen Befehle, die Submodule als Teil ihrer Pfadangaben unterstützen. Die meisten Befehle haben ein boolesches Flag --recurse-submodules, das angibt, ob in Submodule rekursiv eingegriffen werden soll. Beispiele hierfür sind grep und checkout. Einige Befehle akzeptieren Aufzählungen, wie z. B. fetch und push, bei denen Sie angeben können, wie Submodule betroffen sind.

  • Die Konfiguration innerhalb des Submoduls. Dies umfasst $GIT_DIR/config im Submodul, aber auch Einstellungen im Baum wie z. B. .gitattributes oder .gitignore-Dateien, die das Verhalten von Befehlen innerhalb des Submoduls festlegen.

    Zum Beispiel wird ein Effekt aus der .gitignore-Datei des Submoduls beobachtet, wenn Sie git status --ignore-submodules=none im Superprojekt ausführen. Dies sammelt Informationen aus dem Arbeitsverzeichnis des Submoduls, indem status im Submodul ausgeführt wird, wobei die .gitignore-Datei des Submoduls beachtet wird.

    Die $GIT_DIR/config-Datei des Submoduls käme ins Spiel, wenn Sie git push --recurse-submodules=check im Superprojekt ausführen, da dies prüft, ob das Submodul Änderungen aufweist, die nicht an ein Remote-Repository übertragen wurden. Die Remote-Repositorys werden im Submodul wie üblich in der $GIT_DIR/config-Datei konfiguriert.

  • Die Konfigurationsdatei $GIT_DIR/config im Superprojekt. Git greift nur auf aktive Submodule zurück (siehe Abschnitt "AKTIVE SUBMODULE" unten).

    Wenn das Submodul noch nicht initialisiert ist, existiert die Konfiguration innerhalb des Submoduls noch nicht. Daher wird hier beispielsweise konfiguriert, woher das Submodul bezogen werden soll.

  • Die .gitmodules-Datei innerhalb des Superprojekts. Ein Projekt verwendet diese Datei normalerweise, um Standardwerte für die Upstream-Sammlung von Repositorys für die erforderliche Zuordnung zwischen dem Namen eines Submoduls und seinem Pfad vorzuschlagen.

    Diese Datei dient hauptsächlich als Zuordnung zwischen dem Namen und dem Pfad von Submodulen im Superprojekt, damit das Git-Verzeichnis des Submoduls gefunden werden kann.

    Wenn das Submodul noch nie initialisiert wurde, ist dies der einzige Ort, an dem die Submodulkonfiguration zu finden ist. Es dient als letzter Ausweg, um anzugeben, woher das Submodul bezogen werden soll.

FORMEN

Submodule können die folgenden Formen annehmen

  • Die grundlegende Form, die in der BESCHREIBUNG beschrieben ist, mit einem Git-Verzeichnis, einem Arbeitsverzeichnis, einem gitlink und einem .gitmodules-Eintrag.

  • "Alte Form" des Submoduls: Ein Arbeitsverzeichnis mit einem eingebetteten .git-Verzeichnis und dem verfolgenden gitlink- und .gitmodules-Eintrag im Superprojekt. Dies findet man typischerweise in Repositorys, die mit älteren Git-Versionen generiert wurden.

    Es ist möglich, diese alten Repositorys manuell zu erstellen.

    Beim Deinitialisieren oder Löschen (siehe unten) wird das Git-Verzeichnis des Submoduls automatisch nach $GIT_DIR/modules/<name>/ des Superprojekts verschoben.

  • Deinitialisiertes Submodul: Ein gitlink und ein .gitmodules-Eintrag, aber kein Arbeitsverzeichnis des Submoduls. Das Git-Verzeichnis des Submoduls kann vorhanden sein, da es nach der Deinitialisierung beibehalten wird. Das Verzeichnis, das das Arbeitsverzeichnis sein soll, ist stattdessen leer.

    Ein Submodul kann durch Ausführen von git submodule deinit deinitialisiert werden. Neben dem Leeren des Arbeitsverzeichnisses modifiziert dieser Befehl nur die $GIT_DIR/config-Datei des Superprojekts, sodass die Historie des Superprojekts nicht beeinträchtigt wird. Dies kann mit git submodule init rückgängig gemacht werden.

  • Gelöschtes Submodul: Ein Submodul kann durch Ausführen von git rm <submodule-path> && git commit gelöscht werden. Dies kann mit git revert rückgängig gemacht werden.

    Die Löschung entfernt die Tracking-Daten des Superprojekts, sowohl den gitlink-Eintrag als auch den Abschnitt in der .gitmodules-Datei. Das Arbeitsverzeichnis des Submoduls wird vom Dateisystem entfernt, aber das Git-Verzeichnis wird beibehalten, um das Auschecken vergangener Commits zu ermöglichen, ohne dass ein Abruf aus einem anderen Repository erforderlich ist.

    Um ein Submodul vollständig zu entfernen, löschen Sie manuell $GIT_DIR/modules/<name>/.

AKTIVE SUBMODULE

Ein Submodul gilt als aktiv,

  1. wenn submodule.<name>.active auf true gesetzt ist

    oder

  2. wenn der Pfad des Submoduls mit dem Pfadspec in submodule.active übereinstimmt

    oder

  3. wenn submodule.<name>.url gesetzt ist.

und diese werden in dieser Reihenfolge ausgewertet.

Zum Beispiel

[submodule "foo"]
  active = false
  url = https://example.org/foo
[submodule "bar"]
  active = true
  url = https://example.org/bar
[submodule "baz"]
  url = https://example.org/baz

In der obigen Konfiguration sind nur die Submodule *bar* und *baz* aktiv, *bar* aufgrund von (1) und *baz* aufgrund von (3). *foo* ist inaktiv, weil (1) Vorrang vor (3) hat.

Beachten Sie, dass (3) ein historisches Artefakt ist und ignoriert wird, wenn (1) und (2) angeben, dass das Submodul nicht aktiv ist. Mit anderen Worten, wenn wir eine submodule.<name>.active auf false gesetzt haben oder wenn der Pfad des Submoduls im Pfadspec in submodule.active ausgeschlossen ist, spielt die URL keine Rolle, ob sie vorhanden ist oder nicht. Dies wird im folgenden Beispiel veranschaulicht.

[submodule "foo"]
  active = true
  url = https://example.org/foo
[submodule "bar"]
  url = https://example.org/bar
[submodule "baz"]
  url = https://example.org/baz
[submodule "bob"]
  ignore = true
[submodule]
  active = b*
  active = :(exclude) baz

Hier sind alle Submodule außer *baz* (foo, bar, bob) aktiv. *foo* aufgrund seines eigenen aktiven Flags und alle anderen aufgrund des aktiven Pfadspecs für Submodule, der angibt, dass jedes Submodul, das mit *b* beginnt und nicht *baz* ist, ebenfalls aktiv ist, unabhängig vom Vorhandensein des .url-Feldes.

Workflow für eine Drittanbieter-Bibliothek

# Add a submodule
git submodule add <URL> <path>
# Occasionally update the submodule to a new version:
git -C <path> checkout <new-version>
git add <path>
git commit -m "update submodule to new version"
# See the list of submodules in a superproject
git submodule status
# See FORMS on removing submodules

Workflow für ein künstlich aufgeteilte Repo

# Enable recursion for relevant commands, such that
# regular commands recurse into submodules by default
git config --global submodule.recurse true
# Unlike most other commands below, clone still needs
# its own recurse flag:
git clone --recurse <URL> <directory>
cd <directory>
# Get to know the code:
git grep foo
git ls-files --recurse-submodules
Hinweis
 git ls-files erfordert ebenfalls sein eigenes --recurse-submodules Flag. 
# Get new code
git fetch
git pull --rebase
# Change worktree
git checkout
git reset

Implementierungsdetails

Beim Klonen oder Pullen eines Repositorys, das Submodule enthält, werden die Submodule standardmäßig nicht ausgecheckt. Sie können clone anweisen, rekursiv in Submodule einzutreten. Die Unterbefehle init und update von git submodule halten die Submodule ausgecheckt und auf einer geeigneten Revision in Ihrem Arbeitsbaum. Alternativ können Sie submodule.recurse setzen, damit checkout rekursiv in Submodule eintritt (beachten Sie, dass submodule.recurse auch andere Git-Befehle beeinflusst, siehe git-config[1] für eine vollständige Liste).

SIEHE AUCH

git-submodule[1], gitmodules[5].

GIT

Teil der git[1] Suite