Git Bundle: Repositories offline übertragen ohne Server

1. Wenn kein direkter Zugriff auf den Git Server besteht

In abgeschotteten Netzen ohne Internetverbindung, bei Kunden mit strikten Sicherheitsrichtlinien oder auf Reisen ohne stabile Verbindung ist ein normaler git push oder git pull gegen einen zentralen Server schlicht nicht möglich. Trotzdem muss Code oft zwischen zwei Umgebungen ausgetauscht werden, etwa zwischen einer isolierten Entwicklungsumgebung und einem Produktivsystem, das keinen ausgehenden Netzwerkzugriff besitzt.

Git Bundle wurde genau für solche Szenarien entwickelt: Der Befehl verpackt einen definierten Ausschnitt der Historie, inklusive aller benötigten Commits, Bäume und Blob Objekte, in eine einzelne binäre Datei, die sich über beliebige Kanäle transportieren lässt und auf der Zielseite ohne Netzwerkzugriff wie ein reguläres Remote eingebunden werden kann.

2. Ein vollständiges Bundle erstellen und einbinden

Der einfachste Fall ist ein Bundle mit der kompletten Historie eines oder mehrerer Branches. Der Befehl git bundle create erwartet einen Dateinamen und eine Revisionsangabe, die genauso funktioniert wie bei git log oder git rev-list, also etwa ein einzelner Branchname für die komplette Historie dieses Branches oder --all für sämtliche Referenzen im Repository.

Auf der empfangenden Seite lässt sich das Bundle direkt klonen wie ein reguläres Repository, oder in ein bereits bestehendes Repository als zusätzliches Remote einbinden. Git behandelt die Bundle Datei dabei transparent wie eine Netzwerkquelle, sodass alle gewohnten Befehle wie git fetch und git pull ohne Aenderung funktionieren.

# Vollständiges Bundle mit allen Branches und Tags erstellen
git bundle create repo-vollständig.bundle --all

# Bundle wie ein normales Repository klonen
git clone repo-vollständig.bundle projekt-lokal

# Bundle als zusätzliches Remote in ein bestehendes Repository einbinden
git remote add offline-quelle repo-vollständig.bundle
git fetch offline-quelle

3. Bundle Integrität vor der Weitergabe prüfen

Bevor ein Bundle weitergegeben wird, lohnt sich eine Prüfung mit git bundle verify, das kontrolliert, ob die enthaltenen Objekte konsistent sind und ob alle referenzierten Vorfahren entweder im Bundle selbst enthalten oder im Ziel Repository bereits vorhanden sind. Fehlt ein benötigter Vorfahre, meldet der Befehl genau diesen fehlenden Commit, statt erst beim Import auf der Zielseite mit einer kryptischen Fehlermeldung zu scheitern.

Diese Prüfung ist besonders wichtig bei inkrementellen Bundles, die auf einem gemeinsamen Basiscommit aufbauen, weil ein falsch gewählter Basiscommit sonst erst beim Empfänger auffällt, wenn die Uebertragung selbst bereits abgeschlossen und der physische Datenträger möglicherweise nicht mehr griffbereit ist.

# Bundle Datei auf Konsistenz und benötigte Vorfahren prüfen
git bundle verify repo-vollständig.bundle

# Enthaltene Referenzen und Commits auflisten, ohne das Bundle zu importieren
git bundle list-heads repo-vollständig.bundle

4. Inkrementelle Bundles für wiederholte Uebertragungen

Bei regelmäßigem Datenaustausch mit einer isolierten Umgebung ist ein vollständiges Bundle bei jeder Uebertragung ineffizient, weil bereits übertragene Commits erneut mitgeschickt werden. Git Bundle unterstützt deshalb inkrementelle Uebertragungen: Mit einer Revisionsangabe wie letzter-sync..main enthält das Bundle nur die Commits, die seit dem letzten Sync neu hinzugekommen sind.

Voraussetzung dafür ist, dass der Basiscommit, also der Stand des letzten erfolgreichen Syncs, im Ziel Repository bereits vorhanden ist. Ein bewährtes Muster ist ein dauerhaft gepflegter Tag oder Branch, der den zuletzt übertragenen Stand markiert und nach jeder erfolgreichen Uebertragung aktualisiert wird.

# Nur Commits seit dem markierten letzten Sync Stand ins Bundle packen
git bundle create update-woche-32.bundle letzter-sync..main

# Nach erfolgreicher Uebertragung den Sync Marker aktualisieren
git tag -f letzter-sync main

# Auf der Empfängerseite das inkrementelle Bundle einspielen
git fetch update-woche-32.bundle main:main

5. Mehrere Branches und Tags gezielt in ein Bundle packen

Ein Bundle ist nicht auf einen einzelnen Branch beschränkt. Mehrere Revisionsangaben lassen sich in einem Aufruf kombinieren, um gezielt genau die Branches und Tags zu übertragen, die auf der Zielseite tatsächlich benötigt werden, ohne unnötigen Ballast durch Feature Branches mitzuschleppen, die dort nicht relevant sind.

Beim Einspielen eines solchen Bundles mit mehreren Referenzen zeigt git bundle list-heads vorab an, welche Branches und Tags enthalten sind, sodass sich die tatsächlich gewünschten Referenzen gezielt mit git fetch bundle-datei ref:ref auswählen lassen, statt automatisch alle enthaltenen Referenzen zu übernehmen.

# Bundle mit main, einem Release Branch und allen Tags erstellen
git bundle create release-paket.bundle main release/2.4 --tags

# Nur main aus dem Bundle in den lokalen Branch main übernehmen
git fetch release-paket.bundle main:main

6. Einsatz in air gapped und stark reglementierten Umgebungen

In regulierten Branchen wie Finanzwesen oder kritischer Infrastruktur sind Produktivsysteme oft bewusst vom Internet getrennt, sogenannte air gapped Umgebungen. Code Aenderungen müssen dort über einen kontrollierten, oft manuell freigegebenen Kanal eingeschleust werden, was Git Bundle in Kombination mit einem Freigabeprozess und signierten Commits gut abbildet, weil sich die Integrität des Bundles vor der Uebernahme prüfen lässt.

Ein bewährtes Muster ist ein zweistufiger Prozess: Ein Bundle wird in der offenen Umgebung erstellt, digital signiert oder zumindest mit einer Prüfsumme versehen, über einen genehmigten Transportweg in die air gapped Umgebung geschleust und dort erst nach erfolgreicher Verifikation mit git bundle verify importiert.

# Prüfsumme des Bundles für den Transport erzeugen
sha256sum release-paket.bundle > release-paket.bundle.sha256

# Auf der Zielseite Prüfsumme kontrollieren, bevor das Bundle importiert wird
sha256sum -c release-paket.bundle.sha256

7. Bundles gegenüber Patch Dateien und git format-patch

Für eine einzelne, kleine Aenderung ist ein Bundle oft überdimensioniert. Der Befehl git format-patch erzeugt aus einem oder mehreren Commits klassische Patch Dateien im Mailbox Format, die sich per E Mail verschicken und mit git am beim Empfänger anwenden lassen, ohne dass dafür ein vollständiges Bundle nötig wäre. Für einzelne Commits oder kleine Serien ist dieser Weg leichtgewichtiger und für Reviewer im Textformat leichter lesbar als eine binäre Bundle Datei.

Sobald jedoch mehrere Branches, Tags oder eine längere Commit Serie mit komplexer Merge Historie übertragen werden sollen, stößt format-patch an seine Grenzen, weil Merge Commits und Baumstruktur dabei verloren gehen können. Bundles bilden die vollständige Objektstruktur inklusive Merges verlustfrei ab und sind deshalb die robustere Wahl, sobald mehr als eine lineare Commit Kette übertragen werden muss.

# Einzelne Commits als Patch Dateien für den Versand per E Mail erzeugen
git format-patch -3 --stdout > letzte-drei-commits.patch

# Patch Datei beim Empfänger anwenden
git am letzte-drei-commits.patch

8. Best Practices für den produktiven Einsatz von Bundles

Ein klarer Namenskonvention für Bundle Dateien, etwa mit Datum und enthaltenen Branches im Dateinamen, verhindert Verwechslungen, wenn mehrere Bundles im Umlauf sind. Für wiederkehrende Uebertragungen lohnt sich ein Skript, das Bundle Erstellung, Prüfsummenerzeugung und Sync Marker Aktualisierung in einem Schritt kapselt, statt jeden Schritt manuell auszuführen.

Bundles sollten grundsätzlich vor der Weitergabe mit git bundle verify geprüft werden, weil ein defektes oder unvollständiges Bundle auf der Zielseite oft erst nach einem fehlgeschlagenen Import auffällt, wenn der ursprüngliche Transportweg unter Umständen bereits nicht mehr verfügbar ist.

9. Typische Fallstricke beim Arbeiten mit Bundles

Der häufigste Fehler bei inkrementellen Bundles ist ein falscher oder veralteter Basiscommit, der dazu führt, dass die Zielseite Commits erwartet, die im Bundle gar nicht enthalten sind. Die Fehlermeldung beim Import ist in solchen Fällen oft wenig aussagekräftig, weshalb sich eine vorherige Prüfung mit git bundle verify in jedem Fall lohnt.

Ein weiterer Fallstrick ist die Annahme, ein Bundle enthalte automatisch alle Tags oder alle Branches: Ohne explizite Angabe von --all oder konkreten Referenzen packt git bundle create ausschließlich die angegebenen Revisionen ein, was bei einer unvollständigen Revisionsangabe schnell zu einem Bundle führt, dem wichtige Referenzen fehlen.

10. Zusammenfassung

11. FAQ: Git Bundle