Zur Unterstützung des Debuggings von Frontends ignoriert fast-import jede Zeile, die mit # (ASCII-Pfad/Hash) beginnt, bis einschließlich des Zeilenendes LF. Eine Kommentarzeile kann jede Byte-Sequenz enthalten, die kein LF enthält, und kann daher verwendet werden, um detaillierte Debugging-Informationen einzuschließen, die für das Frontend spezifisch und bei der Inspektion eines fast-import-Datenstroms nützlich sein können.

Die folgenden Datumsformate werden unterstützt. Ein Frontend sollte das zu verwendende Format für diesen Import auswählen, indem es den Formatnamen über die Kommandozeilenoption --date-format=<fmt> übergibt.

fast-import akzeptiert mehrere Befehle, um das aktuelle Repository zu aktualisieren und den aktuellen Importprozess zu steuern. Eine detailliertere Diskussion (mit Beispielen) zu jedem Befehl folgt später.

Erstellt oder aktualisiert einen Branch mit einem neuen Commit, der eine logische Änderung am Projekt aufzeichnet.

wobei <ref> der Name des Branches ist, auf dem der Commit erstellt werden soll. Typischerweise sind Branch-Namen in Git mit refs/heads/ präfixiert, daher würde der Import des CVS-Branch-Symbols RELENG-1_0 refs/heads/RELENG-1_0 für den Wert von <ref> verwenden. Der Wert von <ref> muss ein gültiger Git-Refname sein. Da LF in einem Git-Refnamen nicht gültig ist, wird hier keine Anführungs- oder Escape-Syntax unterstützt.

Ein mark-Befehl kann optional erscheinen und fordert fast-import auf, eine Referenz auf den neu erstellten Commit für die zukünftige Verwendung durch das Frontend zu speichern (siehe unten für das Format). Es ist sehr üblich, dass Frontends jeden erstellten Commit markieren, wodurch zukünftige Branch-Erstellungen von jedem importierten Commit ermöglicht werden.

Der data-Befehl nach committer muss die Commit-Nachricht bereitstellen (siehe unten für die Syntax des data-Befehls). Um eine leere Commit-Nachricht zu importieren, verwenden Sie eine Datenlänge von 0. Commit-Nachrichten sind frei formatiert und werden von Git nicht interpretiert. Derzeit müssen sie in UTF-8 kodiert sein, da fast-import keine anderen Kodierungen zulässt.

Null oder mehr filemodify, filedelete, filecopy, filerename, filedeleteall und notemodify Befehle können enthalten sein, um den Inhalt des Branches vor der Erstellung des Commits zu aktualisieren. Diese Befehle können in beliebiger Reihenfolge angegeben werden. Es wird jedoch empfohlen, einen filedeleteall-Befehl allen filemodify-, filecopy-, filerename- und notemodify-Befehlen im selben Commit voranzustellen, da filedeleteall den Branch löscht (siehe unten).

Das LF nach dem Befehl ist optional (es war früher erforderlich). Beachten Sie, dass aus Gründen der Abwärtskompatibilität, wenn der Commit mit einem data-Befehl endet (d. h. er hat keine from-, merge-, filemodify-, filedelete-, filecopy-, filerename-, filedeleteall- oder notemodify-Befehle), dann zwei LF-Befehle am Ende des Befehls anstelle von nur einem erscheinen können.

Veranlasst fast-import, eine Referenz auf das aktuelle Objekt zu speichern, wodurch das Frontend dieses Objekt zu einem späteren Zeitpunkt abrufen kann, ohne seine SHA-1 zu kennen. Hier ist das aktuelle Objekt der Befehl zur Objekterstellung, in dem der mark-Befehl erscheint. Dies kann commit, tag und blob sein, aber commit ist die häufigste Verwendung.

wobei <idnum> die vom Frontend dieser Markierung zugewiesene Nummer ist. Der Wert von <idnum> wird als ASCII-Dezimalzahl ausgedrückt. Der Wert 0 ist reserviert und kann nicht als Markierung verwendet werden. Nur Werte größer oder gleich 1 dürfen als Markierungen verwendet werden.

Neue Markierungen werden automatisch erstellt. Vorhandene Markierungen können einfach durch Wiederverwendung desselben <idnum> in einem anderen mark-Befehl auf ein anderes Objekt verschoben werden.

Gibt den Namen des Objekts im ursprünglichen Quellkontrollsystem an. fast-import wird diese Anweisung einfach ignorieren, aber Filterprozesse, die den Stream bearbeiten und modifizieren, bevor sie ihn an fast-import weiterleiten, könnten diese Informationen verwenden.

wobei <object-identifier> eine beliebige Zeichenkette ohne LF ist.

Erstellt einen annotierten Tag, der sich auf einen bestimmten Commit bezieht. Zum Erstellen von leichten (nicht-annotierten) Tags siehe den reset-Befehl unten.

wobei <name> der Name des zu erstellenden Tags ist.

Tag-Namen werden in Git automatisch mit refs/tags/ präfixiert, daher würde der Import des CVS-Branch-Symbols RELENG-1_0-FINAL nur RELENG-1_0-FINAL für <name> verwenden, und fast-import schreibt den entsprechenden Ref als refs/tags/RELENG-1_0-FINAL.

Der Wert von <name> muss ein gültiger Git-Refname sein und kann daher Schrägstriche enthalten. Da LF in einem Git-Refnamen nicht gültig ist, wird hier keine Quoting- oder Escape-Syntax unterstützt.

Der from-Befehl ist derselbe wie im commit-Befehl; siehe oben für Details.

Der tagger-Befehl verwendet das gleiche Format wie committer innerhalb von commit; siehe wieder oben für Details.

Der data-Befehl, der auf tagger folgt, muss die annotierte Tag-Nachricht liefern (siehe unten für die Syntax des data-Befehls). Um eine leere Tag-Nachricht zu importieren, verwenden Sie Daten mit 0 Länge. Tag-Nachrichten sind frei formatiert und werden von Git nicht interpretiert. Derzeit müssen sie in UTF-8 kodiert sein, da fast-import keine anderen Kodierungen zulässt.

Das Signieren von annotierten Tags während des Imports aus fast-import heraus wird nicht unterstützt. Der Versuch, Ihre eigene PGP/GPG-Signatur einzufügen, wird nicht empfohlen, da das Frontend keinen (einfachen) Zugriff auf die vollständige Menge von Bytes hat, die normalerweise in eine solche Signatur eingehen. Wenn eine Signierung erforderlich ist, erstellen Sie leichte Tags aus fast-import heraus mit reset, und erstellen Sie dann die annotierten Versionen dieser Tags offline mit dem Standardprozess git tag.

Erstellt (oder erstellt neu) den benannten Branch, optional beginnend mit einer bestimmten Revision. Der Reset-Befehl erlaubt es einem Frontend, einen neuen from-Befehl für einen vorhandenen Branch auszugeben oder einen neuen Branch aus einem vorhandenen Commit zu erstellen, ohne einen neuen Commit zu erstellen.

Eine detaillierte Beschreibung von <ref> und <commit-ish> finden Sie oben unter commit und from.

Das LF nach dem Befehl ist optional (war früher erforderlich).

Der reset-Befehl kann auch zum Erstellen von leichten (nicht-annotierten) Tags verwendet werden. Zum Beispiel

würde den leichten Tag refs/tags/938 erstellen, der auf den Commit-Mark :938 verweist.

Fordert das Schreiben einer Dateirevision in die Packdatei an. Die Revision ist mit keinem Commit verbunden; diese Verbindung muss in einem nachfolgenden commit-Befehl hergestellt werden, indem der Blob über eine zugewiesene Markierung referenziert wird.

Der Markierungsbefehl ist hier optional, da einige Frontends beschlossen haben, die Git SHA-1 für den Blob selbst zu generieren und diese direkt an commit zu übergeben. Dies ist in der Regel mehr Arbeit, als es wert ist, da Markierungen kostengünstig zu speichern und einfach zu verwenden sind.

Liefert Rohdaten (zur Verwendung als Blob/Dateiinhalte, Commit-Nachrichten oder annotierte Tag-Nachrichten) an fast-import. Daten können mit einer exakten Byte-Anzahl oder durch ein abschließendes Zeilenende geliefert werden. Reale Frontends, die für produktionsreife Konvertierungen bestimmt sind, sollten immer das Format mit exakter Byte-Anzahl verwenden, da es robuster und performanter ist. Das begrenzte Format ist hauptsächlich für das Testen von fast-import bestimmt.

Kommentarzeilen, die im <raw>-Teil von data-Befehlen erscheinen, werden immer als Teil des Datenkörpers betrachtet und daher von fast-import nie ignoriert. Dies macht es sicher, beliebige Datei-/Nachrichteninhalte zu importieren, deren Zeilen mit # beginnen könnten.

Zeichnet auf, dass eine Markierung auf ein bestimmtes Objekt verweist, ohne zuvor ein neues Objekt zu erstellen.

Eine detaillierte Beschreibung von <commit-ish> finden Sie oben unter from.

Zwingt fast-import, die aktuelle Packdatei zu schließen, eine neue zu starten und alle aktuellen Branch-Refs, Tags und Markierungen zu speichern.

Beachten Sie, dass fast-import automatisch Packdateien wechselt, wenn die aktuelle Packdatei die Größe --max-pack-size oder 4 GiB erreicht, je nachdem, welche Grenze kleiner ist. Während eines automatischen Packdatei-Wechsels aktualisiert fast-import die Branch-Refs, Tags oder Markierungen nicht.

Da ein checkpoint erhebliche Mengen an CPU-Zeit und Festplatten-I/O erfordern kann (um die SHA-1-Prüfsumme der gesamten Packdatei zu berechnen, die entsprechende Indexdatei zu generieren und die Refs zu aktualisieren), kann es leicht mehrere Minuten dauern, bis ein einzelner checkpoint-Befehl abgeschlossen ist.

Frontends können sich entscheiden, Checkpoints während extrem großer und langwieriger Imports auszugeben, oder wenn sie einem anderen Git-Prozess den Zugriff auf einen Branch ermöglichen müssen. Angesichts der Tatsache, dass ein 30 GiB großes Subversion-Repository in etwa 3 Stunden über fast-import in Git geladen werden kann, ist explizites Checkpointing möglicherweise nicht notwendig.

Das LF nach dem Befehl ist optional (war früher erforderlich).

Veranlasst fast-import, die gesamte progress-Zeile unverändert auf seinen Standardausgabekanal (Dateideskriptor 1) zu drucken, wenn der Befehl aus dem Eingabestrom verarbeitet wird. Der Befehl hat ansonsten keine Auswirkungen auf den aktuellen Import oder auf den internen Zustand von fast-import.

Der <any>-Teil des Befehls kann jede Zeichenkette enthalten, die kein LF enthält. Das LF nach dem Befehl ist optional. Aufrufer möchten die Ausgabe möglicherweise durch ein Werkzeug wie sed verarbeiten, um den führenden Teil der Zeile zu entfernen, zum Beispiel

Das Platzieren eines progress-Befehls unmittelbar nach einem checkpoint informiert den Leser, wann der checkpoint abgeschlossen wurde und er sicher auf die von fast-import aktualisierten Refs zugreifen kann.

Veranlasst fast-import, die SHA-1, die einer Markierung entspricht, auf stdout oder auf den Dateideskriptor zu drucken, der zuvor mit dem Argument --cat-blob-fd arrangiert wurde. Der Befehl hat ansonsten keine Auswirkungen auf den aktuellen Import; sein Zweck ist es, SHA-1s abzurufen, auf die spätere Commits in ihren Commit-Nachrichten verweisen könnten.

Siehe "Responses To Commands" unten für Details, wie diese Ausgabe sicher gelesen werden kann.

Veranlasst fast-import, einen Blob auf einen Dateideskriptor zu drucken, der zuvor mit dem Argument --cat-blob-fd arrangiert wurde. Der Befehl hat ansonsten keine Auswirkungen auf den aktuellen Import; sein Hauptzweck ist es, Blobs abzurufen, die sich möglicherweise im Speicher von fast-import befinden, aber nicht aus dem Ziel-Repository zugänglich sind.

Die <dataref> kann entweder eine Markierungsreferenz (:<idnum>) sein, die zuvor gesetzt wurde, oder eine vollständige 40-stellige SHA-1 eines Git-Blobs, die bereits existiert oder zum Schreiben bereit ist.

Die Ausgabe verwendet das gleiche Format wie git cat-file --batch

Dieser Befehl kann dort verwendet werden, wo eine filemodify-Direktive erscheinen kann, wodurch er mitten in einem Commit verwendet werden kann. Für eine filemodify, die eine Inline-Direktive verwendet, kann er auch direkt vor der data-Direktive erscheinen.

Siehe "Responses To Commands" unten für Details, wie diese Ausgabe sicher gelesen werden kann.

Druckt Informationen über das Objekt an einem Pfad auf einen Dateideskriptor, der zuvor mit dem Argument --cat-blob-fd arrangiert wurde. Dies ermöglicht das Drucken eines Blobs aus dem aktiven Commit (mit cat-blob) oder das Kopieren eines Blobs oder Baums aus einem vorherigen Commit zur Verwendung im aktuellen (mit filemodify).

Der ls-Befehl kann auch dort verwendet werden, wo eine filemodify-Direktive erscheinen kann, wodurch er mitten in einem Commit verwendet werden kann.

Siehe filemodify oben für eine detaillierte Beschreibung von <path>.

Die Ausgabe verwendet das gleiche Format wie git ls-tree <tree> -- <path>

Die <dataref> repräsentiert den Blob, Baum oder Commit-Objekt bei <path> und kann in späteren get-mark, cat-blob, filemodify oder ls Befehlen verwendet werden.

Wenn keine Datei oder kein Unterbaum unter diesem Pfad existiert, wird git fast-import stattdessen berichten

Siehe "Responses To Commands" unten für Details, wie diese Ausgabe sicher gelesen werden kann.

Fordert, dass fast-import die angegebene Funktion unterstützt, oder bricht ab, wenn dies nicht der Fall ist.

Der <feature>-Teil des Befehls kann einer der folgenden sein

Verarbeitet die angegebene Option, damit git fast-import auf eine Weise arbeitet, die den Bedürfnissen des Frontends entspricht. Beachten Sie, dass vom Frontend angegebene Optionen durch Optionen überschrieben werden, die der Benutzer selbst an git fast-import angibt.

Der <option>-Teil des Befehls kann jede der im Abschnitt OPTIONS aufgeführten Optionen enthalten, die die Importsemantik nicht ändern, ohne das führende -- und wird auf die gleiche Weise behandelt.

Option-Befehle müssen die ersten Befehle in der Eingabe sein (nicht mitgezählt Feature-Befehle). Ein Optionsbefehl nach einem Nicht-Optionsbefehl ist ein Fehler.

Die folgenden Befehlszeilenoptionen ändern die Importsemantik und dürfen daher nicht als Option übergeben werden

Wenn das done-Feature nicht verwendet wird, wird es so behandelt, als wäre EOF gelesen worden. Dies kann verwendet werden, um fast-import anzuweisen, frühzeitig zu beenden.

Wenn die Befehlszeilenoption --done oder der Befehl feature done verwendet wird, ist der Befehl done obligatorisch und markiert das Ende des Streams.

Verwenden Sie bei der Konvertierung eines Repositorys eine eindeutige Markierung pro Commit (mark :<n>) und übergeben Sie die Option --export-marks auf der Befehlszeile. fast-import gibt eine Datei aus, die jede Markierung und den entsprechenden Git-Objekt-SHA-1 auflistet. Wenn das Frontend die Markierungen mit dem Quellrepository verknüpfen kann, ist es einfach, die Genauigkeit und Vollständigkeit des Imports zu überprüfen, indem jeder Git-Commit mit der entsprechenden Quellrevision verglichen wird.

Wenn Sie von einem System wie Perforce oder Subversion kommen, sollte dies recht einfach sein, da die fast-import-Markierung auch die Perforce-Änderungssatznummer oder die Subversion-Revisionsnummer sein kann.

Versuchen Sie nicht, das Frontend zu optimieren, damit es während eines Imports bei einem Branch bleibt. Obwohl dies für fast-import etwas schneller sein mag, erhöht es die Komplexität des Frontend-Codes erheblich.

Der integrierte LRU-Branch in fast-import verhält sich tendenziell sehr gut, und die Kosten für die Aktivierung eines inaktiven Branches sind so gering, dass das Springen zwischen Branches praktisch keine Auswirkungen auf die Importleistung hat.

Beim Importieren einer umbenannten Datei oder eines Verzeichnisses löschen Sie einfach den/die alten Namen und ändern Sie den/die neuen Namen während des entsprechenden Commits. Git führt die Erkennung von Umbenennungen nachträglich durch, nicht explizit während eines Commits.

Einige andere SCM-Systeme erlauben es dem Benutzer, ein Tag aus mehreren Dateien zu erstellen, die nicht aus demselben Commit/Änderungssatz stammen. Oder um Tags zu erstellen, die eine Teilmenge der im Repository verfügbaren Dateien sind.

Diese Tags in Git so zu importieren, wie sie sind, ist unmöglich, ohne mindestens einen Commit zu erstellen, der die Dateien "korrigiert", um dem Inhalt des Tags zu entsprechen. Verwenden Sie den Befehl reset von fast-import, um einen Dummy-Branch außerhalb Ihres normalen Branch-Bereichs auf den Basis-Commit für das Tag zurückzusetzen, dann committen Sie einen oder mehrere Datei-Fixup-Commits und taggen Sie schließlich den Dummy-Branch.

Da zum Beispiel alle normalen Branches unter dem Namen refs/heads/ gespeichert sind, nennen Sie den Tag-Fixup-Branch TAG_FIXUP. So ist es für den vom Importeur verwendeten Fixup-Branch unmöglich, Namensraumkonflikte mit echten Branches zu haben, die aus der Quelle importiert wurden (der Name TAG_FIXUP ist nicht refs/heads/TAG_FIXUP).

Berücksichtigen Sie beim Committen von Fixups die Verwendung von merge, um die Commits, die Dateirevisionen liefern, mit dem Fixup-Branch zu verbinden. Dies ermöglicht es Tools wie *git blame*, durch die tatsächliche Commit-Historie zu verfolgen und die Quelldateien ordnungsgemäß zu annotieren.

Nachdem fast-import beendet ist, muss das Frontend rm .git/TAG_FIXUP ausführen, um den Dummy-Branch zu entfernen.

Sobald fast-import abgeschlossen ist, ist das Git-Repository vollständig gültig und einsatzbereit. Dies dauert in der Regel nur sehr kurze Zeit, selbst für beträchtlich große Projekte (100.000+ Commits).

Das erneute Verpacken des Repositorys ist jedoch erforderlich, um die Datenlokalität und die Zugriffsleistung zu verbessern. Dies kann auch Stunden bei extrem großen Projekten dauern (insbesondere bei Verwendung von -f und einem großen --window-Parameter). Da das erneute Verpacken sicher parallel zu Lesern und Schreibern ausgeführt werden kann, führen Sie das erneute Verpacken im Hintergrund aus und lassen Sie es beenden, wenn es fertig ist. Es gibt keinen Grund, auf die Erkundung Ihres neuen Git-Projekts zu warten!

Wenn Sie darauf warten, dass das erneute Verpacken abgeschlossen ist, versuchen Sie nicht, Benchmarks oder Leistungstests auszuführen, bis das erneute Verpacken abgeschlossen ist. fast-import gibt suboptimale Packdateien aus, die in realen Anwendungssituationen einfach nie gesehen werden.

Wenn Sie sehr alte importierte Daten (z. B. älter als das letzte Jahr) neu verpacken, erwägen Sie, etwas zusätzliche CPU-Zeit aufzuwenden und --window=50 (oder höher) anzugeben, wenn Sie *git repack* ausführen. Dies dauert länger, führt aber auch zu einer kleineren Packdatei. Sie müssen den Aufwand nur einmal betreiben, und jeder, der Ihr Projekt nutzt, profitiert von dem kleineren Repository.

Senden Sie ab und zu eine progress-Nachricht von Ihrem Frontend an fast-import. Der Inhalt der Nachrichten ist völlig frei gestaltbar. Ein Vorschlag wäre, den aktuellen Monat und das aktuelle Jahr auszugeben, jedes Mal, wenn das Datum des aktuellen Commits in den nächsten Monat übergeht. Ihre Benutzer werden sich besser fühlen, wenn sie wissen, wie viel vom Datenstrom verarbeitet wurde.

fast-import unterhält eine In-Memory-Struktur für jedes in dieser Ausführung geschriebene Objekt. Auf einem 32-Bit-System ist die Struktur 32 Bytes groß, auf einem 64-Bit-System ist die Struktur 40 Bytes groß (aufgrund der größeren Zeigergrößen). Objekte in der Tabelle werden erst freigegeben, wenn fast-import beendet wird. Der Import von 2 Millionen Objekten auf einem 32-Bit-System erfordert ungefähr 64 MiB Speicher.

Die Objekttabelle ist tatsächlich eine Hashtabelle, die auf dem Objektnamen (dem eindeutigen SHA-1) basiert. Diese Speicheraufteilung ermöglicht es fast-import, ein vorhandenes oder bereits geschriebenes Objekt wiederzuverwenden und Duplikate in der Ausgabe-Packdatei zu vermeiden. Doppelte Blobs sind bei einem Import überraschend häufig, typischerweise aufgrund von Branch-Merges in der Quelle.

Markierungen werden in einem spärlichen Array gespeichert und verwenden 1 Zeiger (4 Bytes oder 8 Bytes, abhängig von der Zeigergröße) pro Markierung. Obwohl das Array spärlich ist, wird Frontends dringend empfohlen, Markierungen zwischen 1 und n zu verwenden, wobei n die Gesamtzahl der für diesen Import erforderlichen Markierungen ist.

Branches werden als aktiv und inaktiv klassifiziert. Der Speicherverbrauch der beiden Klassen ist signifikant unterschiedlich.

Inaktive Branches werden in einer Struktur gespeichert, die 96 oder 120 Bytes (32-Bit bzw. 64-Bit-Systeme) zuzüglich der Länge des Branch-Namens (typischerweise unter 200 Bytes) pro Branch verwendet. fast-import kann problemlos bis zu 10.000 inaktive Branches in weniger als 2 MiB Speicher verwalten.

Aktive Branches haben den gleichen Overhead wie inaktive Branches, enthalten aber auch Kopien jedes Baums, der auf diesem Branch kürzlich geändert wurde. Wenn die Unterverzeichnis include seit der Aktivierung des Branches nicht geändert wurde, werden ihre Inhalte nicht in den Speicher geladen, aber wenn das Unterverzeichnis src seit der Aktivierung des Branches durch einen Commit geändert wurde, werden seine Inhalte in den Speicher geladen.

Da aktive Branches Metadaten über die auf diesem Branch enthaltenen Dateien speichern, kann ihre In-Memory-Speichergröße beträchtlich anwachsen (siehe unten).

fast-import verschiebt aktive Branches automatisch in den inaktiven Status, basierend auf einem einfachen LRU-Algorithmus (Least Recently Used). Die LRU-Kette wird bei jedem commit-Befehl aktualisiert. Die maximale Anzahl aktiver Branches kann auf der Befehlszeile mit --active-branches= erhöht oder verringert werden.

Bäume (auch Verzeichnisse genannt) verbrauchen nur 12 Bytes Speicher zusätzlich zu dem für ihre Einträge benötigten Speicher (siehe "pro aktivem Dateieintrag" unten). Die Kosten eines Baums sind praktisch 0, da sein Overhead über die einzelnen Dateieinträge amortisiert wird.

Dateien (und Verweise auf Unterbäume) innerhalb aktiver Bäume erfordern 52 oder 64 Bytes (32/64-Bit-Plattformen) pro Eintrag. Um Speicher zu sparen, werden Datei- und Baum-Namen in einer gemeinsamen Stringtabelle zusammengefasst, wodurch der Dateiname "Makefile" nur 16 Bytes (einschließlich des String-Header-Overheads) verbraucht, unabhängig davon, wie oft er im Projekt vorkommt.

Die aktive Branch LRU ermöglicht es fast-import, in Verbindung mit dem Dateinamen-Stringpool und der verzögerten Ladung von Unterbäumen, Projekte mit über 2.000 Branches und über 45.114 Dateien mit einem sehr begrenzten Speicherfußabdruck (weniger als 2,7 MiB pro aktivem Branch) effizient zu importieren.