Übersicht

git subtree add --prefix=<path> <repo> <ref> [--squash]
git subtree pull --prefix=<path> <repo> <ref>
git subtree push --prefix=<path> <repo> <ref>
git subtree split --prefix=<path> -b <new-branch>

Beschreibung

Der git subtree-Befehl ist eine Alternative zu Submodules, die den Inhalt eines anderen Projekts direkt in ein Unterverzeichnis Ihres Repos mergt. Anders als bei Submodules brauchen Subtree-Konsumenten keine speziellen Schritte — die Dateien sind einfach da. Der Preis ist, dass die fremde Historie in Ihre eigene aufgenommen wird.

Die zwei Hauptoperationen sind add (initialer Import, oft mit --squash, um die Historie zu verflachen) und pull (Upstream-Änderungen einbringen). Um Änderungen zurückzusenden, filtert git subtree push Commits heraus, die das Präfix berühren, und pusht sie zum Upstream-Repo.

Im täglichen Einsatz integriert sich git subtree eng mit Shell-Aliasen, Editor-Plugins und Continuous Integration. Power-User fügen oft Aliase hinzu, die Flags kombinieren, die sie immer übergeben, oder wickeln den Befehl in Skripte, die Teamkonventionen durchsetzen. Die Ausgabeformatierung kann über Git-Config angepasst werden — Pretty-Formate, Farbschemata und Pager-Verhalten sind alle einstellbar. Wenn etwas schiefgeht, ist der erste Diagnoseschritt üblicherweise, den Befehl erneut mit GIT_TRACE=1 in der Umgebung auszuführen, was die zugrunde liegenden Plumbing-Aufrufe offenlegt. Für ungewöhnliche Situationen öffnet die --help-Ausgabe (git subtree --help) die vollständige Manpage mit Details zu jeder Option, einschließlich solcher, die in alltäglichen Workflows selten verwendet werden, aber für Debugging oder Skripting im großen Maßstab essentiell sind.

Zu verstehen, wie git subtree mit dem Rest von Gits Datenmodell interagiert — der Objektdatenbank, dem Index, Refs und dem Working Tree — zahlt sich aus. Jeder Befehl operiert auf einer Teilmenge dieser Stücke, und zu wissen, welche er berührt, hilft Ergebnisse vorherzusagen und sich von Fehlern zu erholen. Das Lesen der offiziellen Git-Dokumentation neben praktischer Übung in einem Wegwerf-Repository ist der schnellste Weg, die Nuancen zu verinnerlichen. Die meisten Produktionsprobleme mit Git rühren von einer von drei Ursachen: überraschendem Standardverhalten, partiellen Netzwerkoperationen oder dem Umschreiben bereits geteilter Historie. Ein funktionierendes mentales Modell der Nebenwirkungen von git subtree hilft, alle drei zu vermeiden.

Häufige Optionen

Unterbefehl	Beschreibung
add	Importiert ein externes Repo in ein Unterverzeichnis.
pull	Mergt Upstream-Änderungen für dieses Präfix.
push	Pusht reine Präfix-Historie zurück zum Upstream.
merge	Mergt einen beliebigen Tree in das Präfix.
split	Extrahiert die Historie eines Unterverzeichnisses als eigenständigen Branch.
--squash	Verflacht fremde Historie zu einem einzelnen Commit.
--prefix=<path>	Unterverzeichnis, in das das Subtree gelegt werden soll.

Beispiele

git subtree add --prefix=vendor/foo https://github.com/lib/foo.git main --squash
    # foo nach vendor/foo importieren, Historie squashen

    git subtree pull --prefix=vendor/foo https://github.com/lib/foo.git main --squash
    # Updates pullen

    git subtree split --prefix=lib -b lib-only
    # lib/ als eigenen Branch zum Teilen extrahieren

    git subtree push --prefix=vendor/foo upstream main
    # Präfix-bezogene Commits zurück zum Upstream senden

Häufige Fehler

--squash bei manchen Operationen zu mischen und bei anderen nicht erzeugt eine chaotische Historie. Wählen Sie einen Modus und bleiben Sie dabei. Subtree-Merges erzeugen nicht-triviale Commit-Graphen, die manche Tooling verwirren. git subtree split kann auf großen Historien langsam sein.

Verwandte Befehle

git submodule, git merge, git filter-repo