9.2 Git en andere systemen - Migreren naar Git

Als je de vorige paragraaf leest over het gebruik van`git svn`, kan je eenvoudigweg deze instructies gebruiken om met git svn clone een repository te maken en daarna te stoppen met de Subversion server, naar een nieuwe Git server te pushen en die beginnen te gebruiken. Als je de historie wilt, kan je dat zo snel voor elkaar krijgen als je de gegevens uit de Subversion server kunt krijgen (en dat kan even duren).

Deze import is echter niet perfect, en omdat het zo lang duurt, kan je eigenlijk ook meteen maar goed doen. Het eerste probleem is de auteur-informatie. In Subversion, heeft elke persoon die commit heeft gedaan een gebruikersnaam op het systeem die wordt opgenomen in de commit-informatie. De voorbeelden in de vorige paragraaf tonen schacon in bepaalde plaatsen, zoals de blame uitvoer en de git svn log. Als je dit beter op Git auteur-gegevens wilt mappen, moet je een relatie leggen van de Subversion gebruikers naar de Git auteurs. Maak een bestand genaamd users.txt die deze mapping-informatie heeft in een formaat als deze:

Om een lijst van auteur-namen te krijgen die SVN gebruikt, kan je dit aanroepen:

Dat maakt de loguitvoer in XML formaat aan, en behoudt vervolgens alleen de regels met auteur-informatie, verwijdert duplicaten en haalt de XML tags weg. (Dit werkt duidelijk alleen op een machine met grep, sort, en perl erop geïnstalleerd). Stuur daarna de uitvoer naar je users.txt bestand zodat je de overeenkomstige Git gebruiker gegevens naast elke regel kunt zetten.

Je kunt dit bestand aan git svn geven om het te helpen de auteur gegevens beter te mappen. Je kunt git svn ook vertellen de meta-data die Subversion normaalgesproken importeert niet mee te nemen, door --no-metadata mee te geven aan de clone of init commando’s. Hierdoor ziet je import commando er ongeveer zo uit:

Nu zou je een mooiere Subversion import moeten hebben in je my_project directory. In plaats van commits die er uit zien als dit

zien ze er zo uit:

Niet alleen ziet het Author veld er veel beter uit, maar de git-svn-id is er ook niet meer.

Je moet ook nog wat opschonen na de import. Onder andere moet je de vreemde referenties opschonen die git svn heeft gemaakt. Allereerst ga je de tags verplaatsen zodat ze echte tags zijn, in plaats van vreemde remote branches, en daarna verplaats je de overige branches zodat ze lokaal zijn.

Om de tags te verplaatsen zodat ze echte Git tags worden, roep je dit aan

Dit neemt de referenties die remote branches waren en begonnen met refs/remotes/tags/ en maakt er echte (lichtgewicht) tags van.

Daarna verplaatsen we de overige referenties onder refs/remotes om er lokale branches van te maken:

Het kan gebeuren dat je een aantal extra branches ziet die vooraf worden gegaan door @xxx (waar xxx een getal is), terwijl je in Subversion aleen maar een branch ziet. Dit is eigenlijk een Subversion kenmerk genaamd “peg-revisions”, wat iets is waar Git gewoonweg geen syntactische tegenhanger voor heeft. Vandaar dat git svn eenvoudigweg het svn versienummer aan de branchnaam toevoegt op dezelfde manier als jij dit zou hebben gedaan in svn om het peg-revisie van die branch te adresseren. Als je niet meer om de peg-revisies geeft, kan je ze simpelweg verwijderen:

Nu zijn alle oude branches echte Git branches en alle oude tags echte Git tags.

Er is nog een laatste ding om op te schonen: Helaas maakt git svn een extra branch aan met de naam trunk, wat overeenkomt met de standaard branch in Subversion, maar de trunk-referentie wijst naar dezelfde plek als master. Omdat master idiomatisch meer Git is, is hier de manier om die extra branch te verwijderen:

Het laatste om te doen is om je nieuwe Git server als een remote toe te voegen en er naar te pushen. Hier is een voorbeeld van een server als een remote toe te voegen:

Omdat al je branches en tags ernaar wilt sturen, kan je nu dit aanroepen:

Al je branches en tags zouden nu op je nieuwe Git server moeten staan in een mooie, schone import.

Omdat Mercurial and Git een redelijk overeenkomend model hebben om versies te representeren en omdat Git iets flexibeler is, is het converteren van een repository uit Mercurial naar Git minder omslachtig, gebruik makend van een instrument dat "hg-fast-export" heet, waar je een kopie van nodig gaat hebben:

De eerste stap in de conversie is om een volledige kloon van de Mercurial repository die je wilt converteren te maken:

De volgende stap is om een auteur-mapping bestand te maken. Mercurial is wat minder streng dan Git voor wat het in het auteur veld zet voor changesets, dus dit is een goed moment om schoon schip te maken. Het aanmaken hiervan is een enkele commando regel in een bash shell:

Dit duurt een paar tellen, afhankelijk van de lengte van de geschiedenis van je project, en nadien ziet het /tmp/authors bestand er ongeveer zo uit:

In dit voorbeeld, heeft dezelfde persoon (Bob) changesets aangemaakt onder vier verschillende namen, waarvan er één er wel correct uitziet, en één ervan zou voor een Git commit helemaal niet geldig zijn. Hg-fast-export laat ons dit corrigeren door elke regel in een instructie te veranderen: "<invoer>"="<uitvoer>", waarbij <invoer> in een <uitvoer> wordt gewijzigd. Binnen de <invoer> en <uitvoer> tekenreeksen, worden alle escaped reeksen die door de python string_escape encoding worden begrepen ondersteund. Als het auteur mapping-bestand geen passende <invoer> regel heeft, wordt deze ongewijzigd doorgestuurd naar Git. Als alle gebruikersnamen er goed uitzien, hebben we dit bestand helemaal niet nodig. In ons voorbeeld, willen we dat ons bestand er zo uit ziet:

Hetzelfde soort mapping bestand kan worden gebruikt om branches en tags te hernoemen als de Mercurial naam niet wordt toegestaan door Git.

De volgende stap is om onze nieuwe Git repository aan te maken en het volgende export script aan te roepen:

De -r vlag vertelt hg-fast-export waar het de Mercurial repository kan vinden die we willen converteren, en de -A vlag vertelt het waar het auteur-mapping bestand te vinden is. Het script verwerkt Mercurial changesets en converteert ze in een script voor de "fast-import" functie (die we iets later zullen bespreken). Dit duurt even (al is het veel sneller dan het via het netwerk zou zijn), en de uitvoer is nogal breedsprakig:

Meer valt er eigenlijk niet over te vertellen. Alle Mercurial tags zijn geconverteerd naar Git tags, en Mercurial branches en boekleggers (bookmarks) zijn geconverteerd naar Git branches. Nu ben je klaar om de repository naar zijn nieuwe server-thuis te sturen:

Bazaar is een DVCS tool die veel op Git lijkt, en als gevolg is het redelijk probleemloos om een Bazaar repository in een van Git te converteren. Om dit voor elkaar te krijgen, moet je de bzr-fastimport-plugin importeren.

Het volgende systeem waar we naar gaan kijken is het importeren uit Perforce. Zoals hierboven besproken, zijn er twee manieren om Git en Perforce met elkaar te laten praten: git-p4 en Perforce Git Fusion.

Als je team haar versiebeheer uit TFVC naar Git gaat converteren, wil je de hoogst-betrouwbare conversie gebruiken die je maar kunt krijgen. Dit houdt in dat, hoewel we zowel git-tfs als git-tf in de samenwerkings-paragraaf hebben behandeld, zullen we hier alleen git-tfs behandelen, omdat git-tfs branches ondersteunt, en deze beperking het vrijwel onmogelijk maakt om git-tf hiervoor te gebruiken.

Het eerste om te doen is gebruikersnamen mappen. TFVC is nogal ruimdenkend met wat er in het auteur veld gaat voor changesets, maar Git wil een voor de mens leesbare naam en email adres hebben. Je kunt deze informatie als volgt van het tf commando-regel client krijgen:

Dit pakt alle changesets in de geschiedenis van het project en zet dit in het AUTHORS_TMP bestand die we verder gaan verwerken om de gegevens uit het User kolom (de tweede) te halen. Open het bestand en bekijk op welke karakter de kolom begint en eindigt en vervang, in de volgende commando-regel, de parameters 11-20 van het cut commando met de waarden die jij gevonden hebt:

Het cut commando behoudt alleen de karakters tussen 11 en 20 van elke regel. Het tail commando slaat de eerste twee regels over, die kolom-koppen en ASCII-art onderstrepingen zijn. Het resultaat van dit alles wordt aan sort en uniq doorgegeven om duplicaten te verwijderen en bewaard in een bestand genaamd AUTHORS. De volgende stap is handmatig; om git-tfs van dit bestand gebruik te laten maken, moet elke regel in dit formaat staan:

Het gedeelte links is het “User” veld van TFVC, en het gedeelte rechts van het gelijk-teken is de gebruikersnaam die voor Git commits gaat worden gebruikt.

Als je dit bestand eenmaal hebt, is de volgende stap om te nemen een volledige kloon van het TFVC project waar je in bent geïnteresseerd te maken:

Vervolgens wil je de git-tfs-id gedeeltes aan het eind van de commit-berichten opschonen. Het volgende commando gaat dit doen:

Dit gebruikt het sed commando van de Git-bash omgeving om elke regel die begint met “git-tfs-id:” met leegte te vervangen, dit Git vervolgens dan zal negeren.

Als dit eenmaal gedaan is, ben je klaar om een nieuwe remote toe te voegen, al je branches te pushen, en je team is klaar om met Git te gaan werken.

Als jouw systeem niet een van de bovenstaande is, moet je op het internet gaan zoeken naar een importeerder - goede importeerders zijn beschikbaar voor vele andere systemen, inclusief CVS, Clear Case, Visual Source Safe en zelfs een directory met archieven. Als geen van die tools voor jou geschikt zijn, je hebt een heel obscure tool, of je hebt om een andere reden een meer aangepaste importeer proces nodig, dan moet je git fast-import gebruiken. Dit commando leest eenvoudige instructies van stdin om specifieke Git gegevens te schrijven. Het is veel eenvoudiger om op deze manier Git objecten aan te maken dan de rauwe Git commando’s te gebruiken of om zelf de rauwe objecten te schrijven (zie Git Binnenwerk voor meer informatie). Op deze manier kan je een import script schrijven die de benodigde informatie uit het te importeren systeem leest en op stdout eenvoudige instructies afdrukt. Je kunt dit programma dan aanroepen en de uitvoer doorgeven aan git fast-import met een pipe-instructie.

Om een snelle demonstratie te geven, ga je een eenvoudige importeerder schrijven. Stel dat je in current aan het werk bent, je maakt op gezette tijden een backup van je project door de directory naar een andere te kopieren met een datum-tijd indicatie genaamd back_YYYY_MM_DD, en je wilt dit importeren in Git. Je directory-structuur ziet er zo uit:

Om een Git directory te importeren, moet je weten hoe Git haar gegevens opslaat. Zoals je je zult herinneren, is Git in de basis een geschakelde lijst van commit objecten die verwijzen naar een snapshot van de inhoud. Alles wat je hoeft te doen is fast-import te vertellen wat de snapshots van de inhoud zijn, welke commit-gegevens hiernaar verwijzen en de volgorde waarin ze staan. Je strategie zal zijn om een voor een door de snapshots te gaan en commits te maken met de inhoud van elke directory, en elke commit terug te laten verwijzen naar de vorige.

Zoals we in Een voorbeeld van Git-afgedwongen beleid gedaan hebben, schrijven we dit in Ruby, omdat dit is waar we gewoonlijk mee werken en het redelijk eenvoudig te lezen is. Je kunt dit voorbeeld redelijk eenvoudig in iets schrijven waar je bekend mee bent - het moet gewoon de juiste informatie naar stdout uitvoeren. En als je op Windows draait, betekent dit dat je ervoor moet zorgen dat je geen carriage returns aan het eind van je regels gebruikt - git fast-import is erg secuur in het alleen accepteren van line feeds (LF) niet de carriage return line feeds (CFLF) die door Windows wordt gebruikt.

Om te beginnen, spring je in de doel directory en identificeert elke subdirectory, die elk een snapshot is van wat je wilt importeren als een commit. Je springt in elke subdirectory en drukt de commando’s af die nodig zijn om het te exporteren. Je hoofdlus ziet er zo uit:

Je roept print_export in elke directory aan, die de inhoud en kenmerk (mark) van de vorige snapshot neemt en je de inhoud en kenmerk van deze teruggeeft; op die manier kan je ze goed koppelen.

“Mark” is de term die fast-import gebruikt voor een identificatie die je aan een commit geeft; tijdens het aanmaken van commit geef je elk een kenmerk die je kunt gebruiken om als koppeling vanaf andere commits. Dus, het eerste wat je moet doen in je print_export methode is een kenmerk genereren van de naam van de directory:

Je doet dit door een reeks (array) directories te maken en de indexwaarde als het kenmerk te gebruiken, omdat een kenmerk een integer dient te zijn. Je methode ziet er zo uit:

Nu je een integer representatie hebt van je commit, heb je een datum nodig voor de commit metadata. Omdat de datum in de naam van de directory zit, ga je het eruit halen. De volgende regel in je print_export bestand is:

where convert_dir_to_date is defined as:

Dat retourneert een integerwaarde voor de datum van elke directory. Het laatste stukje meta-informatie dat je nodig hebt voor elke commit zijn de gegevens van de committer, die je hardgecodeerd hebt in een globale variabele:

Nu ben je klaar om de commit data af te drukken voor je importeerder. De initiële informatie geeft aan dat je een commit object definieert en op welke branch deze staat, gevolgd door het kenmerk die je hebt gegenereert, de informatie van de committer en het commit bericht, en dan de vorige commit als die er is. De code ziet er zo uit:

Je geeft de tijdzone (-0700) hardgecodeerd, omdat dit nu eenmaal makkelijk is. Als je vanuit een ander systeem importeert, moet je de tijdzone als een relatieve verschuiving (offset) weergeven. Het commit bericht moet worden uitgedrukt in een speciaal formaat:

Het formaat bestaat uit het woord data, de grootte van de te lezen gegevens, een nieuwe regel en tot slot de gegevens. Omdat je hetzelfde formaat later nodig hebt om de bestandsinhoud te specificeren, maak je een hulpmethode, export_data:

Wat er nu nog overblijft is het specifieren van de bestandsinhoud voor elk snapshot. Dit is makkelijk, omdat je elk van deze in een directory hebt - je kunt het deleteall commando afdrukken gevolgd door de inhoud van elk bestand in de directory. Git zal dan elke snapshot op de juiste manier opslaan:

Let op: Omdat veel systemen hun revisies zien als wijzigingen van de ene commit naar de ander, kan fast-import ook commando’s accepteren waar bij elke commit kan worden aangegeven welke bestanden er zijn toegevoegd, verwijderd of gewijzigd en welke nieuwe elementen erbij zijn gekomen. Je kunt de verschillen tussen de snapshots berekenen en alleen deze gegevens meegeven, maar het is veel ingewikkelder om dit te doen - je kunt net zo makkelijk Git alle gegevens meegeven en het hem laten uitzoeken. Als dit beter past bij jouw gegevens, neem dan de fast-import man page door voor de details hoe je deze gegevens moet doorgeven in dat geval.

Het formaat om de nieuwe bestandsinhoud weer te geven of om een gewijzigd bestand te specificeren met de nieuwe inhoud is als volgt:

Hier is 644 de mode (als je aanroepbare bestanden hebt, moet je dit detecteren en in plaats daarvan 755 opgeven), en in de code (inline) geef je de inhoud direct achter deze regel weer. Je inline_data methode ziet er zo uit:

Je hergebruikt de export_data methode die je eerder hebt gedefinieerd, omdat dit formaat hetzelfde is als waarmee je de commit bericht gegevens specificeert.

Het laatste wat je nog moet doen is om het huidige kenmerk te retourneren, zodat het kan worden doorgegeven in de volgende iteratie:

Dat is 't. Hier is het script in zijn totaliteit:

Als je dit script aanroept, krijg je inhoud dat er ongeveer zo uit ziet:

Om de importeerder te laten draaien, geeft je de uitvoer met een pipe door aan git fast-import terwjil je in de Git directory staat waar je naartoe wilt importeren. Je kunt een nieuwe directory aanmaken en daarna git init daarin aanroepen als een begin, en daarna je script aanroepen:

Zoals je kunt zien, als het succesvol eindigt, geeft het je een bergje statistieken wat het allemaal heeft bereikt. In dit geval, heb je in totaal 13 objecten geïmporteerd voor 4 commits in 1 branch. Je kunt nu git log aanroepen om je nieuwe historie te bekijken:

Kijk eens aan - een mooie, schone Git repository. Het is belangrijk om op te merken dat er niets is uitgecheckt - je hebt initieel nog geen enkel bestand in je werk directory. Om deze te krijgen, moet je je branch resetten tot waar master nu is:

Je kunt nog veel meer doen met het fast-import gereedschap - verschillende modes behandelen, binaire gegevens, meerdere branches en mergen, tags, voortgangs-indicators en meer. Een aantal voorbeelden van meer ingewikkelde scenarios zijn beschikbaar in de contrib/fast-import directory van de Git broncode.