9.2 Git und andere VCS-Systeme - Migration zu Git

Wenn Du den vorherigen Abschnitt über die Verwendung von git svn gelesen hast, kannst du die Anweisungen zu git svn clone dazu benutzen, um ein Repository zu klonen. Anschliessend benötigst du den Subversion-Servers nicht mehr. Pushe alles zu einem neuen Git-Server und nutze dann nur noch diesen. Der Verlauf kann dabei aus dem Subversion-Server gezogen werden, was einige Zeit in Anspruch nehmen kann – abhängig von der Geschwindigkeit, mit der dein SVN-Server die Historie ausliefern kann.

Allerdings ist der Import nicht perfekt. Da er aber so lange dauert, kannst du es auch direkt richtig machen. Das erste Problem sind die Autoreninformationen. In Subversion hat jede Person, die einen Commit durchführt, auch einen Benutzer-Account auf dem System, der in den Commit-Informationen erfasst wird. Die Beispiele im vorherigen Abschnitt zeigen an einigen Stellen schacon, wie z.B. der blame Output und das git svn log. Wenn du diese auf bessere Git-Autorendaten abbilden möchtest, benötigst du eine Zuordnung der Subversion-Benutzer zu den Git-Autoren. Erstelle eine Datei mit Namen users.txt, die diese Zuordnung in folgendem Format vornimmt:

Um eine Liste der Autorennamen zu erhalten, die SVN verwendet, kannst du diesen Befehl ausführen:

Das erzeugt die Protokollausgabe im XML-Format, behält nur die Zeilen mit Autoreninformationen, verwirft Duplikate und entfernt die XML-Tags. Natürlich funktioniert das nur auf einem Computer, auf dem grep, sort und perl installiert sind. Leite diese Ausgabe dann in deine users.txt Datei um, damit du die entsprechenden Git-Benutzerdaten neben jedem Eintrag hinzufügen kannst.

Du kannst diese Datei an git svn übergeben, um die Autorendaten genauer abzubilden. Außerdem kannst du git svn anweisen, die Metadaten, die Subversion normalerweise importiert, nicht zu berücksichtigen. Übergebe dazu --no-metadata an den clone oder init Befehl. Die Metadaten enthalten eine git-svn-id in jeder Commit-Nachricht, die Git während des Imports generiert. Dies kann dein Git-Log aufblähen und es möglicherweise etwas unübersichtlich machen.

Dadurch sieht dein import Befehl so aus:

Nun solltest du einen passenderen Subversion-Import in deinem my_project Verzeichnis haben. Anstelle von Commits, die so aussehen:

sehen diese jetzt so aus:

Nicht nur das Autorenfeld sieht viel besser aus, auch die git-svn-id ist nicht mehr vorhanden.

Du solltest auch eine Bereinigung nach dem Import durchführen. Zum einen solltest du die seltsamen Referenzen bereinigen, die git svn eingerichtet hat. Verschiebe zuerst die Tags so, dass sie echte Tags und nicht merkwürdige Remote-Branches darstellen. Dann verschiebe den Rest der Branches auf lokale Branches.

Damit die Tags zu richtigen Git-Tags werden, führe folgenden Befehl aus:

Dabei werden die Referenzen, die Remote-Branches waren und mit refs/remotes/tags/ begonnen haben zu richtigen (leichten) Tags gemacht.

Als nächstes verschiebe den Rest der Referenzen unter refs/remotes in lokale Branches:

Es kann vorkommen, dass du einige zusätzliche Branches siehst, die durch @xxx ergänzt sind (wobei xxx eine Zahl ist), während du in Subversion nur einen Branch siehst. Es handelt sich hierbei um eine Subversion-Funktion mit der Bezeichnung „peg-revisions“, für die Git kein syntaktisches Gegenstück hat. Daher fügt git svn einfach die SVN-Versionsnummer zum Branch-Namen hinzu, genau so, wie du es in SVN geschrieben hättest, um die peg-Revision dieses Branchs anzusprechen. Wenn du dich nicht mehr um die peg-Revisionen sorgen willst, entferne diese einfach:

Jetzt sind alle alten Branches echte Git-Branches und alle alten Tags sind echte Git-Tags.

Da wäre noch eine letzte Sache zu klären. Leider erstellt git svn einen zusätzlichen Branch mit dem Namen trunk, der auf den Standard-Branch von Subversion gemappt wird, aber die trunk Referenz zeigt auf die gleiche Position wie master. Da master in Git eher idiomatisch ist, hier die Anleitung zum Entfernen des extra Branchs:

Das Letzte, was du tun musst, ist deinem neuen Git-Server als Remote hinzuzufügen und zu ihm zu pushen. Hier ist ein Beispiel für das hinzufügen deines Servers als Remote:

Um alle deine Branches und Tags zu aktualisieren, kannst du jetzt diese Anweisungen ausführen:

Alle deine Branches und Tags sollten sich nun auf deinem neuen Git-Server in einem schönen, sauberen Import befinden.

Merkurial und Git haben ziemlich ähnliche Modelle für die Darstellung von Versionen. Außerdem ist Git etwas flexibler, so dass die Konvertierung eines Repositorys von Merkurial nach Git ziemlich einfach ist. Dazu wird ein Tool mit der Bezeichnung „hg-fast-export“ verwendet, dass du aus github beziehen kannst:

Der erste Schritt bei der Umstellung besteht darin, einen vollständigen Klon des zu konvertierenden Mercurial-Repository zu erhalten:

Der nächste Schritt ist die Erstellung einer Autor-Mapping-Datei. Mercurial ist etwas toleranter als Git für das, was es in das Autorenfeld für Changesets stellt. Das ist daher ein guter Zeitpunkt, um das ganze Projekt zu bereinigen. Das lässt sich mit einem einzeiligen Befehl in einer bash Shell erreichen:

Das dauert nur ein paar Sekunden, abhängig davon, wie umfangreich der Verlauf deines Projekts ist. Danach wird die Datei /tmp/authors in etwa so aussehen:

In diesem Beispiel hat die gleiche Person (Bob) Changesets unter vier verschiedenen Namen erstellt, von denen einer tatsächlich korrekt aussieht und einer für einen Git-Commit völlig ungültig wäre. Mit hg-fast-export können wir das beheben. Jede Zeile wird in eine Regel umgewandelt: "<input>"="<output>", wobei ein <input> auf einen <output> abgebildet wird. Innerhalb der Zeichenketten <input> und <output> werden alle Escape-Sequenzen unterstützt, die von Python string_escape Encoding verstanden werden. Wenn die Autor-Mapping-Datei keinen passenden <input> enthält, wird dieser Autor unverändert an Git übergeben. Wenn alle Benutzernamen korrekt aussehen, werden wir diese Datei überhaupt nicht brauchen. In diesem Beispiel soll unsere Datei so aussehen:

Die gleiche Art von Mapping-Datei kann zum Umbenennen von Branches und Tags verwendet werden, wenn der Mercurial-Name in Git nicht zulässig ist.

Der nächste Schritt ist die Erstellung unseres neuen Git-Repository und das Ausführen des Exportskripts:

Das -r Flag informiert hg-fast-export darüber, wo das Mercurial-Repository zu finden ist, das wir konvertieren möchten. Das -A Flag sagt ihm, wo es die Autor-Mapping-Datei findet (Branch- und Tag-Mapping-Dateien werden jeweils durch die -B und -T Flags definiert). Das Skript analysiert Mercurial Change-Sets und konvertiert sie in ein Skript für Gits „fast-import“ Funktion (auf die wir später noch näher eingehen werden). Das dauert ein wenig (obwohl es viel schneller ist, als wenn es über das Netzwerk laufen würde). Der Output ist ziemlich umfangreich:

Das ist so ziemlich alles, was es dazu zu sagen gibt. Alle Mercurial-Tags wurden in Git-Tags umgewandelt, und Mercurial-Branches und -Lesezeichen wurden in Git-Branches umgewandelt. Jetzt kannst du das Repository in das neue serverseitige System pushen:

Bei dem nächsten System, aus dem du importieren könntest, handelt es sich um Perforce. Wie bereits erwähnt, gibt es zwei Möglichkeiten, wie Git und Perforce miteinander kommunizieren können: git-p4 und Perforce Git Fusion.

Wenn dein System nicht zu den vorgenannten gehört, solltest du online nach einer Import-Schnittstelle suchen – hochwertige Importer sind für viele andere Systeme verfügbar, darunter CVS, Clear Case, Visual Source Safe, sogar für ein Verzeichnis von Archiven. Wenn keines dieser Tools für dich geeignet ist, du ein obskures Tool nutzt oder anderweitig einen benutzerdefinierten Importprozess benötigst, solltest du git fast-import verwenden. Dieser Befehl liest die einfachen Anweisungen von „stdin“ aus, um bestimmte Git-Daten zu schreiben. Es ist viel einfacher, Git-Objekte auf diese Weise zu erstellen, als die Git-Befehle manuell auszuführen oder zu versuchen, Raw-Objekte zu erstellen (siehe Kapitel 10, Git Interna für weitere Informationen). Auf diese Weise kannst du ein Import-Skript schreiben, das die notwendigen Informationen aus dem System liest, aus dem du importierst, und Anweisungen direkt auf „stdout“ ausgibt. Du kannst dann dieses Programm ausführen und seine Ausgaben über git fast-import pipen.

Um das kurz zu demonstrieren, schreibe eine einfache Import-Anweisung. Angenommen, du arbeitest im current Branch, du sicherst dein Projekt, indem du das Verzeichnis gelegentlich in ein mit Zeitstempel versehenes back_YYYY_MM_DD Backup-Verzeichnis kopieren und dieses in Git importieren möchtest. Deine Verzeichnisstruktur sieht wie folgt aus:

Damit du ein Git-Verzeichnis importieren kannst, musst du dir ansehen, wie Git seine Daten speichert. Wie du dich vielleicht erinnerst, ist Git im Grunde genommen eine verknüpfte Liste von Commit-Objekten, die auf einen Schnappschuss des Inhalts verweisen. Alles, was du tun musst, ist fast-import mitzuteilen, worum es sich bei den Content-Snapshots handelt, welche Commit-Datenpunkte zu ihnen gehören und in welcher Reihenfolge sie in den jeweiligen Ordner gehören. Deine Strategie besteht darin, die Snapshots einzeln durchzugehen und Commits mit dem Inhalt jedes Verzeichnisses zu erstellen. Dabei wird jeder Commit mit dem vorherigen verknüpft.

Wie wir es in Kapitel 8, Beispiel für Git-forcierte Regeln getan haben, werden wir das in Ruby schreiben, denn damit arbeiten wir normalerweise und es ist eher leicht zu lesen. Du kannst dieses Beispiel sehr leicht in jedem Editor schreiben, den du kennst – er muss nur die entsprechenden Informationen nach stdout ausgeben können. Unter Windows musst du besonders darauf achten, dass du am Ende deiner Zeilen keine Zeilenumbrüche einfügst – git fast-import ist da sehr empfindlich, wenn es darum geht, nur Zeilenvorschübe (LF) und nicht die von Windows verwendeten Zeilenvorschübe (CRLF) zu verwenden.

Zunächst wechselst du in das Zielverzeichnis und identifizierst jene Unterverzeichnisse, von denen jedes ein Snapshot ist, den du als Commit importieren möchtest. Du wechselst in jedes Unterverzeichnis und gibst die für den Export notwendigen Befehle aus. Deine Hauptschleife sieht so aus:

Führe print_export in jedem Verzeichnis aus, das das Manifest und die Markierung des vorherigen Snapshots enthält und das Manifest und die Markierung dieses Verzeichnisses zurückgibt. So kannst du sie richtig verlinken. „Mark“ ist der fast-import Begriff für eine Kennung, die du einem Commit mitgibst. Wenn du Commits erstellst, gibst du jedem eine Markierung, mit dem du ihn von anderen Commits aus verlinken kannst. Daher ist das Erste, was deine print_export Methode tut, die Generierung einer Markierung aus dem Verzeichnisnamen:

Du wirst dazu ein Array von Verzeichnissen erstellen und den Indexwert als Markierung verwenden. Eine Markierung muss nämlich eine Ganzzahl (Integer) sein. Deine Methode sieht so aus:

Nachdem du nun eine ganzzahlige Darstellung deines Commits hast, benötigst du ein Datum für die Commit-Metadaten. Das Datum wird im Namen des Verzeichnisses ausgewiesen, daher wirst du es auswerten. Die nächste Zeile in deiner print_export Datei lautet:

wobei convert_dir_to_date definiert ist als:

Das gibt einen ganzzahligen Wert für das Datum jedes Verzeichnisses zurück. Die letzte Meta-Information, die du für jeden Commit benötigst, sind die Committer-Daten, die du in einer globalen Variable hartkodierst:

Damit bist du startklar für die Ausgabe der Commit-Daten für deinen Importer. Die ersten Informationen beschreiben, dass du ein Commit-Objekt definierst und in welchem Branch es sich befindet, gefolgt von der Markierung, die du generiert hast, den Committer-Informationen und der Commit-Beschreibung und dann, falls vorhanden, der vorherige Commit. Der Code sieht jetzt so aus:

Du kannst die Zeitzone (-0700) hartkodieren, da das einfach ist. Wenn du sie aus einem anderen System importierst, musst du die Zeitzone als Offset angeben. Die Commit-Beschreibung muss in einem speziellen Format ausgegeben werden:

Das Format besteht aus den Wortdaten, der Größe der zu lesenden Daten, einer neuen Zeile und schließlich den Daten. Da du später das gleiche Format verwenden musst, um den Datei-Inhalt festzulegen, erstellst du mit export_data eine Hilfs-Methode:

Nun musst du nur noch den Dateiinhalt für jeden Schnappschuss angeben. Das ist einfach, denn du hast jeden in einem eigenen Verzeichnis. Du kannst den Befehl deleteall ausgeben, gefolgt vom Inhalt jeder Datei im Verzeichnis. Git zeichnet dann jeden Schnappschuss entsprechend auf:

Hinweis: Da viele Systeme ihre Revisionen als Änderungen von einem Commit zum anderen betrachten, kann fast-import auch Befehle mit jedem Commit übernehmen, um anzugeben, welche Dateien hinzugefügt, entfernt oder geändert wurden und was die neuen Inhalte sind. Du kannst die Unterschiede zwischen den Snapshots berechnen und nur diese Daten bereitstellen, aber das ist komplizierter – in diesem Fall solltest du Git alle Daten übergeben und sie auswerten lassen. Sollte diese Option für deine Daten besser geeignet sein, informiere dich in der fast-import Man-Page, wie du deine Daten auf diese Weise bereitstellen kannst.

Das Format für die Auflistung des neuen Datei-Inhalts oder die Angabe einer modifizierten Datei mit dem neuen Inhalt lautet wie folgt:

Im Beispiel ist es der Modus 644 (wenn du ausführbare Dateien hast musst du stattdessen 755 ermitteln und spezifizieren), und inline besagt, dass der Inhalt unmittelbar nach dieser Zeile aufgelistet wird. Das Verfahren inline_data sieht so aus:

Bei der Wiederverwendung der Methode export_data, die du zuvor definiert hast, handelt es sich um das gleiche Verfahren wie bei der Angabe deiner Commit-Message-Daten.

Als Letztes musst du die aktuelle Markierung an das System zurückgeben, damit sie an die nächste Iteration weitergegeben werden kann:

Das war' s. Das Skript ist jetzt komplett:

Wenn du dieses Skript ausführst, solltest du eine Ausgabe wie die folgende erhalten:

Um den Importer aufzurufen, übergibst du diese Output-Pipe an git fast-import, während du dich in dem Git-Verzeichnis befindest, in das du importieren willst. Du kannst ein neues Verzeichnis erstellen und dort git init für einen Anfangspunkt ausführen und danach dein Skript ausführen:

Wie du siehst, gibt es nach erfolgreichem Abschluss eine Reihe von Statistiken über den erreichten Status. In diesem Fall hast du 13 Objekte mit insgesamt 4 Commits in einen Branch importiert. Jetzt kannst du git log ausführen, um deine neue Historie zu sehen:

So ist es richtig – ein ordentliches, sauberes Git-Repository. Es ist wichtig zu beachten, dass nichts ausgecheckt ist – du hast zunächst keine Dateien in deinem Arbeitsverzeichnis. Um sie zu erhalten, musst du deinen Branch auf den aktuellen master zurücksetzen:

Mit dem fast-import Tool kannst du noch viel mehr tun – bearbeiten von unterschiedlichen Modi, binären Daten, multiplen Branches und Merges, Tags, Verlaufsindikatoren und mehr. Eine Reihe von Beispielen für komplexere Szenarien findest du im contrib/fast-import Verzeichnis des Git-Quellcodes.