English ▾ Themen ▾ Neueste Version ▾ git-bundle zuletzt aktualisiert in 2.48.0

NAME

git-bundle - Objekte und Referenzen per Archiv verschieben

SYNOPSIS

git bundle create [-q | --quiet | --progress]
		    [--version=<version>] <file> <git-rev-list-args>
git bundle verify [-q | --quiet] <file>
git bundle list-heads <file> [<refname>…​]
git bundle unbundle [--progress] <file> [<refname>…​]

BESCHREIBUNG

Erstellt, entpackt und manipuliert "Bundle"-Dateien. Bundles werden für die "Offline"-Übertragung von Git-Objekten verwendet, ohne dass auf der anderen Seite der Netzwerkverbindung ein aktiver "Server" läuft.

Sie können verwendet werden, um sowohl inkrementelle als auch vollständige Backups eines Repositorys zu erstellen (siehe das Beispiel "vollständiges Backup" in "BEISPIELE") und um den Zustand von Referenzen von einem Repository auf ein anderes zu übertragen (siehe das zweite Beispiel).

Git-Befehle, die über Protokolle wie ssh:// und https:// abrufen oder anderweitig "lesen", können auch mit Bundle-Dateien arbeiten. Es ist möglich, ein neues Repository aus einem Bundle mit git-clone[1] zu klonen, es mit git-fetch[1] abzurufen und die darin enthaltenen Referenzen mit git-ls-remote[1] aufzulisten. Es gibt keine entsprechende "Schreib"-Unterstützung, d. h. ein git push in ein Bundle wird nicht unterstützt.

BUNDLE-FORMAT

Bundles sind .pack-Dateien (siehe git-pack-objects[1]) mit einem Header, der angibt, welche Referenzen im Bundle enthalten sind.

Wie das verpackte Archivformat selbst können Bundles entweder in sich geschlossen sein oder unter Verwendung von Ausschlüssen erstellt werden. Siehe den Abschnitt "OBJEKT-VORAUSSETZUNGEN" unten.

Mit Revisionsausschlüssen erstellte Bundles sind "dünne Packs", die mit der Option --thin von git-pack-objects[1] erstellt werden, und werden mit der Option --fix-thin von git-index-pack[1] entpackt.

Es gibt keine Option, ein "dickes Pack" zu erstellen, wenn Revisionsausschlüsse verwendet werden, und Benutzer sollten sich keine Gedanken über den Unterschied machen. Durch die Verwendung von "dünnen Packs" sind mit Ausschlüssen erstellte Bundles kleiner. Dass sie "dünn" sind, wird hier lediglich als Kuriosität und als Verweis auf andere Dokumentation vermerkt.

Weitere Details finden Sie in gitformat-bundle[5] und weitere Details zur Diskussion von "thin pack" in gitformat-pack[5].

OPTIONEN

create [Optionen] <Datei> <git-rev-list-args>

Wird verwendet, um ein Bundle namens Datei zu erstellen. Dies erfordert die <git-rev-list-args>-Argumente zur Definition des Bundle-Inhalts. Optionen enthält die Optionen, die spezifisch für den Unterbefehl git bundle create sind. Wenn Datei - ist, wird das Bundle nach stdout geschrieben.

verify <Datei>

Wird verwendet, um zu überprüfen, ob eine Bundle-Datei gültig ist und sauber auf das aktuelle Repository angewendet werden kann. Dies beinhaltet Überprüfungen des Bundle-Formats selbst sowie Überprüfungen, ob die erforderlichen Commits vorhanden und vollständig im aktuellen Repository verknüpft sind. Dann gibt git bundle eine Liste der fehlenden Commits aus, falls vorhanden. Schließlich werden Informationen über zusätzliche Fähigkeiten, wie z. B. "Objektfilter", ausgegeben. Siehe "Capabilities" in gitformat-bundle[5] für weitere Informationen. Der Exit-Code ist null bei Erfolg, aber nicht null, wenn die Bundle-Datei ungültig ist. Wenn Datei - ist, wird das Bundle von stdin gelesen.

list-heads <Datei>

Listet die im Bundle definierten Referenzen auf. Wenn eine Liste von Referenzen folgt, werden nur übereinstimmende Referenzen ausgegeben. Wenn Datei - ist, wird das Bundle von stdin gelesen.

unbundle <Datei>

Übergibt die Objekte im Bundle an git index-pack zur Speicherung im Repository und gibt dann die Namen aller definierten Referenzen aus. Wenn eine Liste von Referenzen angegeben wird, werden nur übereinstimmende Referenzen ausgegeben. Dieser Befehl ist eigentlich ein "Plumbing"-Befehl, der nur von git fetch aufgerufen werden soll. Wenn Datei - ist, wird das Bundle von stdin gelesen.

<git-rev-list-args>

Eine Liste von Argumenten, die für git rev-parse und git rev-list akzeptabel sind (und einen benannten Ref enthalten, siehe REFERENZEN SPEZIFIZIEREN unten), die die zu transportierenden spezifischen Objekte und Referenzen angibt. Zum Beispiel bewirkt master~10..master, dass die aktuelle Master-Referenz zusammen mit allen Objekten, die seit ihrem 10. Vorläufer-Commit hinzugefügt wurden, verpackt wird. Es gibt keine explizite Begrenzung für die Anzahl der zu verpackenden Referenzen und Objekte.

[<refname>…​]

Eine Liste von Referenzen, die verwendet wird, um die als verfügbar gemeldeten Referenzen einzuschränken. Dies ist hauptsächlich für git fetch von Nutzen, das erwartet, nur die angeforderten Referenzen und nicht unbedingt alles im Pack zu erhalten (in diesem Fall verhält sich git bundle wie git fetch-pack).

--progress

Der Fortschrittsstatus wird standardmäßig auf dem Standardfehlerausgabestrom berichtet, wenn dieser an ein Terminal angeschlossen ist, es sei denn, -q wird angegeben. Diese Flag erzwingt die Anzeige des Fortschrittsstatus, auch wenn der Standardfehlerausgabestrom nicht an ein Terminal weitergeleitet wird.

--version=<version>

Gibt die Bundle-Version an. Version 2 ist das ältere Format und kann nur mit SHA-1-Repositorys verwendet werden; die neuere Version 3 enthält Funktionen, die Erweiterungen ermöglichen. Der Standardwert ist das älteste unterstützte Format, basierend auf dem verwendeten Hash-Algorithmus.

-q
--quiet

Diese Flagge bewirkt, dass der Befehl seinen Fortschritt nicht auf dem Standard-Fehlerstrom meldet.

REFERENZEN SPEZIFIZIEREN

Revisionen müssen von Referenznamen begleitet werden, um in ein Bundle verpackt zu werden. Alternativ kann --all verwendet werden, um alle Refs zu verpacken.

Mehrere Referenzen können verpackt werden, und es kann mehr als eine Menge von erforderlichen Objekten angegeben werden. Die verpackten Objekte sind diejenigen, die nicht in der Vereinigung der Voraussetzungen enthalten sind.

Der Befehl git bundle create löst die Referenznamen für Sie mit denselben Regeln wie git rev-parse --abbrev-ref=loose auf. Jede Voraussetzung kann explizit (z. B. ^master~10) oder implizit (z. B. master~10..master, --since=10.days.ago master) angegeben werden.

Alle diese einfachen Fälle sind in Ordnung (vorausgesetzt, wir haben einen "master"- und einen "next"-Branch)

$ git bundle create master.bundle master
$ echo master | git bundle create master.bundle --stdin
$ git bundle create master-and-next.bundle master next
$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin

Und diese sind es auch (und die gleichen, aber weggelassenen --stdin-Beispiele)

$ git bundle create recent-master.bundle master~10..master
$ git bundle create recent-updates.bundle master~10..master next~5..next

Ein Revisionsname oder ein Bereich, dessen rechte Seite nicht zu einer Referenz aufgelöst werden kann, wird nicht akzeptiert

$ git bundle create HEAD.bundle $(git rev-parse HEAD)
fatal: Refusing to create empty bundle.
$ git bundle create master-yesterday.bundle master~10..master~5
fatal: Refusing to create empty bundle.

OBJEKT-VORAUSSETZUNGEN

Beim Erstellen von Bundles ist es möglich, ein in sich geschlossenes Bundle zu erstellen, das in einem Repository ohne gemeinsame Historie entpackt werden kann, sowie negative Revisionen bereitzustellen, um Objekte auszuschließen, die in den früheren Teilen der Historie benötigt werden.

Wenn Sie eine Revision wie new an git bundle create übergeben, wird eine Bundle-Datei erstellt, die alle von der Revision new erreichbaren Objekte enthält. Dieses Bundle kann in jedem Repository entpackt werden, um eine vollständige Historie zu erhalten, die zur Revision new führt.

$ git bundle create full.bundle new

Ein Revisionsbereich wie old..new erzeugt eine Bundle-Datei, die die Revision old (und alle von ihr erreichbaren Objekte) erfordert, damit das Bundle "entpackbar" ist.

$ git bundle create full.bundle old..new

Ein in sich geschlossenes Bundle ohne Voraussetzungen kann überall extrahiert werden, selbst in ein leeres Repository, oder von ihm geklont werden (d. h. new, aber nicht old..new).

Es ist in Ordnung, auf der sicheren Seite zu sein und die Bundle-Datei so zu erstellen, dass sie Objekte enthält, die bereits im Ziel vorhanden sind, da diese beim Entpacken am Ziel ignoriert werden.

Wenn Sie dieselbe Menge an Refs bereitstellen möchten, die ein direkter Klon vom Quell-Repository erhalten würde, verwenden Sie --branches --tags für die <git-rev-list-args>.

Der Befehl git bundle verify kann verwendet werden, um zu überprüfen, ob Ihr Empfänger-Repository die erforderlichen Vorläufer-Commits für ein Bundle hat.

BEISPIELE

Wir werden zwei Fälle diskutieren

  1. Erstellung eines vollständigen Backups eines Repositorys

  2. Übertragung der Historie eines Repositorys auf eine andere Maschine, wenn die beiden Maschinen keine direkte Verbindung haben

Betrachten wir zunächst ein vollständiges Backup des Repositorys. Der folgende Befehl erstellt ein vollständiges Backup des Repositorys, insofern als alle Refs im Bundle enthalten sind

$ git bundle create backup.bundle --all

Aber beachten Sie nochmals, dass dies nur für die Refs gilt, d. h. Sie werden nur Refs und Commits einschließen, die von diesen Refs erreichbar sind. Sie werden keinen anderen lokalen Zustand einschließen, wie z. B. den Inhalt des Index, des Arbeitsverzeichnisses, des Stash, der Repository-spezifischen Konfiguration, Hooks usw.

Sie können dieses Repository später mit z. B. git-clone[1] wiederherstellen

$ git clone backup.bundle <new directory>

Betrachten wir für das nächste Beispiel, dass Sie die Historie von einem Repository R1 auf Maschine A auf ein anderes Repository R2 auf Maschine B übertragen möchten. Aus irgendeinem Grund ist eine direkte Verbindung zwischen A und B nicht erlaubt, aber wir können Daten von A nach B über einen Mechanismus (CD, E-Mail usw.) bewegen. Wir möchten R2 mit der Entwicklung aktualisieren, die im Branch master in R1 stattgefunden hat.

Um den Prozess zu starten, können Sie zuerst ein Bundle erstellen, das keine Voraussetzungen hat. Sie können einen Tag verwenden, um sich zu merken, bis zu welchem Commit Sie zuletzt verarbeitet haben, um es später einfacher zu machen, das andere Repository mit einem inkrementellen Bundle zu aktualisieren.

machineA$ cd R1
machineA$ git bundle create file.bundle master
machineA$ git tag -f lastR2bundle master

Dann übertragen Sie file.bundle auf die Zielmaschine B. Da dieses Bundle keine vorhandenen Objekte zum Extrahieren benötigt, können Sie auf Maschine B ein neues Repository klonen

machineB$ git clone -b master /home/me/tmp/file.bundle R2

Dies definiert einen Remote namens "origin" im resultierenden Repository, der es Ihnen ermöglicht, von dem Bundle abzurufen und zu ziehen. Die Datei $GIT_DIR/config in R2 enthält einen Eintrag wie diesen

[remote "origin"]
    url = /home/me/tmp/file.bundle
    fetch = refs/heads/*:refs/remotes/origin/*

Um das resultierende mine.git-Repository zu aktualisieren, können Sie abrufen oder ziehen, nachdem Sie das unter /home/me/tmp/file.bundle gespeicherte Bundle durch inkrementelle Updates ersetzt haben.

Nach weiterer Arbeit im ursprünglichen Repository können Sie ein inkrementelles Bundle erstellen, um das andere Repository zu aktualisieren

machineA$ cd R1
machineA$ git bundle create file.bundle lastR2bundle..master
machineA$ git tag -f lastR2bundle master

Anschließend übertragen Sie das Bundle auf die andere Maschine, um /home/me/tmp/file.bundle zu ersetzen, und ziehen davon.

machineB$ cd R2
machineB$ git pull

Wenn Sie wissen, bis zu welchem Commit das beabsichtigte Empfänger-Repository die notwendigen Objekte haben sollte, können Sie dieses Wissen nutzen, um die Voraussetzungen anzugeben und einen Grenzwert festzulegen, um die Revisionen und Objekte einzuschränken, die in das resultierende Bundle gelangen. Im vorherigen Beispiel wurde der Tag lastR2bundle zu diesem Zweck verwendet, aber Sie können auch andere Optionen verwenden, die Sie dem Befehl git-log[1] übergeben würden. Hier sind weitere Beispiele

Sie können einen Tag verwenden, der in beiden vorhanden ist

$ git bundle create mybundle v1.0.0..master

Sie können eine Voraussetzung basierend auf der Zeit verwenden

$ git bundle create mybundle --since=10.days master

Sie können die Anzahl der Commits verwenden

$ git bundle create mybundle -10 master

Sie können git-bundle verify ausführen, um zu sehen, ob Sie aus einem Bundle extrahieren können, das mit einer Voraussetzung erstellt wurde

$ git bundle verify mybundle

Dies listet die Commits auf, die Sie benötigen, um aus dem Bundle zu extrahieren, und gibt einen Fehler aus, wenn Sie sie nicht haben.

Ein Bundle aus der Sicht eines Empfänger-Repositorys ist wie ein reguläres Repository, von dem es abruft oder zieht. Sie können beispielsweise Referenzen beim Abrufen mappen

$ git fetch mybundle master:localRef

Sie können auch sehen, welche Referenzen es anbietet

$ git ls-remote mybundle

DISKUSSION

Eine naive Methode, ein vollständiges Backup eines Repositorys zu erstellen, ist die Verwendung von etwas wie cp -r <repo> <destination>. Dies wird nicht empfohlen, da das Repository während des Kopiervorgangs geschrieben werden könnte. Infolgedessen könnten einige Dateien an <destination> beschädigt werden.

Deshalb wird empfohlen, Git-Tools für Repository-Backups zu verwenden, entweder mit diesem Befehl oder z. B. mit git-clone[1]. Beachten Sie jedoch, dass diese Tools Ihnen nicht helfen, Zustände zu sichern, die über Refs und Commits hinausgehen. Mit anderen Worten, sie helfen Ihnen nicht beim Sichern des Inhalts des Index, des Arbeitsverzeichnisses, des Stash, der Repository-spezifischen Konfiguration, Hooks usw.

Siehe auch gitfaq[7], Abschnitt "TRANSFERS", für eine Diskussion der Probleme im Zusammenhang mit der Dateisynchronisierung zwischen Systemen.

DATEIFORMAT

Siehe gitformat-bundle[5].

GIT

Teil der git[1] Suite