9.2 Git och andra system - Migrera till Git

Om du läste föregående avsnitt om att använda git svn kan du enkelt använda dessa instruktioner för att klona ett kodförråd med git svn clone, sedan sluta använda Subversion‑servern, skicka till en ny Git‑server och börja använda den. Om du vill ha historiken kan du göra det så snabbt som du kan dra ut datan ur Subversion‑servern (vilket kan ta tid).

Importen är dock inte perfekt, och eftersom den ändå tar lång tid kan du lika gärna göra det rätt. Det första problemet är författarinformationen. I Subversion har varje person som checkar in en användare i systemet som registreras i incheckningsinformationen. Exemplen i föregående avsnitt visar schacon på vissa ställen, till exempel i blame‑utdata och git svn log. Om du vill mappa detta till bättre Git‑författardata behöver du en mappning från Subversion‑användare till Git‑författare. Skapa en fil som heter users.txt med denna mappning i ett format som ser ut så här:

För att få en lista över de författarnamn som SVN använder kan du köra detta:

Detta genererar loggutdata i XML‑format, behåller bara raderna med författarinformation, tar bort dubbletter och rensar bort XML‑taggarna. Detta fungerar förstås bara på en maskin med grep, sort och perl installerade. Omdirigera sedan utdata till din users.txt‑fil så att du kan lägga till motsvarande Git‑användardata bredvid varje post.

Du kan ge denna fil till git svn för att hjälpa den mappa författardata mer exakt. Du kan också säga åt git svn att inte inkludera metadata som Subversion normalt importerar genom att skicka --no-metadata till kommandot clone eller init. Metadata innehåller en git-svn-id i varje incheckningsmeddelande som Git skapar under importen. Det kan göra din Git‑logg onödigt stor och svårare att läsa.

Det gör att ditt import‑kommando ser ut så här:

Nu bör du ha en snyggare Subversion‑import i din my_project‑katalog. I stället för incheckningar som ser ut så här:

ser de ut så här:

Inte bara ser Author‑fältet mycket bättre ut, utan git-svn-id finns inte längre heller.

Du bör också göra lite efterimport‑städning. För det första bör du städa upp de märkliga referenser som git svn skapade. Först flyttar du taggarna så att de blir riktiga taggar i stället för udda fjärrgrenar, och därefter flyttar du resten av grenarna så att de blir lokala.

För att flytta taggarna till riktiga Git‑taggar, kör:

Detta tar referenserna som var fjärrgrenar och som började med refs/remotes/tags/ och gör dem till riktiga (lättviktiga) taggar.

Flytta sedan resten av referenserna under refs/remotes till lokala grenar:

Det kan hända att du ser några extra grenar som slutar med @xxx (där xxx är ett nummer), trots att du i Subversion bara ser en gren. Det här är en Subversion‑funktion som kallas “peg‑revisioner”, vilket är något som Git helt saknar en syntaktisk motsvarighet till. Därför lägger git svn helt enkelt till SVN‑versionsnumret i grennamnet på samma sätt som du hade skrivit det i SVN för att adressera peg‑revisionen för den grenen. Om du inte längre bryr dig om peg‑revisionerna kan du bara ta bort dem:

Nu är alla de gamla grenarna riktiga Git‑grenar och alla de gamla taggarna riktiga Git‑taggar.

Det finns en sista sak att städa upp. Tyvärr skapar git svn en extra gren som heter trunk, som mappar till Subversions standardgren, men referensen trunk pekar på samma ställe som master. Eftersom master är mer idiomatiskt Git gör du så här för att ta bort den extra grenen:

Sista steget är att lägga till din nya Git‑server som ett fjärrkodförråd och skicka dit. Så här lägger du till din server som fjärrkodförråd:

Eftersom du vill att alla dina grenar och taggar ska skickas upp kan du nu köra detta:

Alla dina grenar och taggar ska nu finnas på din nya Git‑server i en fin, ren import.

Eftersom Mercurial och Git har ganska liknande modeller för att representera versioner, och eftersom Git är lite mer flexibelt, är det ganska okomplicerat att konvertera ett kodförråd från Mercurial till Git med hjälp av verktyget "hg-fast-export", som du behöver ha en kopia av:

Det första steget i konverteringen är att göra en fullständig klon av Mercurial‑kodförrådet du vill konvertera:

Nästa steg är att skapa en fil för författarmappning. Mercurial är lite mer förlåtande än Git när det gäller vad som hamnar i author‑fältet för ändringsuppsättningar, så detta är ett bra tillfälle att städa upp. Detta genereras med ett kort enradskommando i ett bash‑skal:

Detta tar några sekunder, beroende på hur lång historiken i ditt projekt är, och därefter ser filen /tmp/authors ut ungefär så här:

I det här exemplet har samma person (Bob) skapat ändringsuppsättningar under fyra olika namn, varav ett ser korrekt ut och ett skulle vara helt ogiltigt som Git‑incheckning. Hg-fast-export låter oss fixa detta genom att omvandla varje rad till en regel: "<input>"="<output>", som mappar ett <input> till ett <output>. I strängarna <input> och <output> stöds alla escape‑sekvenser som Pythons string_escape‑kodning förstår. Om författarmappningsfilen inte innehåller ett matchande <input> skickas författaren vidare till Git oförändrad. Om alla användarnamn ser bra ut behöver vi inte filen alls. I det här exemplet vill vi att filen ska se ut så här:

Samma typ av mappningsfil kan användas för att byta namn på grenar och taggar när Mercurial‑namnet inte tillåts av Git.

Nästa steg är att skapa vårt nya Git‑kodförråd och köra exportskriptet:

Flaggan -r talar om för hg-fast-export var Mercurial‑kodförrådet vi vill konvertera finns, och flaggan -A talar om var författarmappningsfilen finns (mappningsfiler för grenar och taggar anges med flaggorna -B respektive -T). Skriptet tolkar Mercurial‑ändringsuppsättningar och konverterar dem till ett skript för Gits funktion "fast-import" (som vi går igenom i detalj lite senare). Det här tar en stund (även om det är mycket snabbare än över nätverket), och utskriften är ganska omfattande.

Det är i stort sett allt. Alla Mercurial‑taggar har konverterats till Git‑taggar, och Mercurial‑grenar och bokmärken har konverterats till Git‑grenar. Nu är du redo att skicka kodförrådet till sitt nya hem på servern:

Nästa system att importera från är Perforce. Som vi diskuterade ovan finns det två sätt att låta Git och Perforce prata med varandra: git-p4 och Perforce Git Fusion.

Om ditt system inte är ett av ovanstående bör du leta efter ett importverktyg på nätet – det finns importverktyg av god kvalitet för många andra system, inklusive CVS, ClearCase, Visual SourceSafe och till och med kataloger med arkiv. Om inget av dessa verktyg fungerar för dig, om du har ett mer obskyrt verktyg eller om du behöver en mer anpassad importprocess, bör du använda git fast-import. Detta kommando läser enkla instruktioner från stdin för att skriva specifik Git‑data. Det är mycket enklare att skapa Git‑objekt på det här sättet än att köra de råa Git‑kommandona eller försöka skriva de råa objekten (se Git bakom kulisserna för mer information). På så vis kan du skriva ett importskript som läser den nödvändiga informationen ur systemet du importerar från och skriver tydliga instruktioner till standardutmatningen. Sedan kan du köra programmet och skicka dess utdata genom git fast-import.

För att snabbt demonstrera detta skriver du ett enkelt importskript. Anta att du arbetar i current, att du säkerhetskopierar projektet genom att med jämna mellanrum kopiera katalogen till en tidsstämplad säkerhetskopia back_YYYY_MM_DD, och att du vill importera detta till Git. Din katalogstruktur ser ut så här:

För att importera en Git‑katalog behöver du se över hur Git lagrar sin data. Som du kanske minns är Git i grunden en länkad lista av incheckningsobjekt som pekar på en ögonblicksbild av innehåll. Allt du behöver göra är att tala om för fast-import vilka ögonblicksbilder av innehåll som finns, vilken incheckningsdata som pekar på dem och i vilken ordning de kommer. Din strategi blir att gå igenom ögonblicksbilderna en i taget och skapa incheckningar med innehållet i varje katalog, där varje incheckning länkar tillbaka till den föregående.

Som vi gjorde i Ett exempel på Git‑upprätthållen policy skriver vi detta i Ruby, eftersom det är det vi vanligtvis arbetar med och det brukar vara lätt att läsa. Du kan skriva exemplet ganska enkelt i vilket språk du är bekväm med – det behöver bara skriva rätt information till standardutmatningen. Och om du kör på Windows betyder det att du måste vara extra noga med att inte introducera vagnreturer i slutet av dina rader – git fast-import vill absolut bara ha radmatningar (LF) och inte de vagnretur‑radmatningar (CRLF) som Windows använder.

Till att börja med byter du till målkatalogen och identifierar varje underkatalog, som var och en är en ögonblicksbild du vill importera som en incheckning. Du byter till varje underkatalog och skriver ut kommandona som behövs för att exportera den. Din grundläggande huvudloop ser ut så här:

Du kör print_export inuti varje katalog, som tar manifestet och markeringen för den föregående ögonblicksbilden och returnerar manifestet och markeringen för den här; på så sätt kan du länka dem korrekt. “Mark” är fast-import‑termen för en identifierare du ger en incheckning; när du skapar incheckningar ger du var och en en markering som du kan använda för att länka till den från andra incheckningar. Så det första du gör i din print_export‑metod är att generera en markering från katalognamnet:

Du gör detta genom att skapa en array av kataloger och använda indexvärdet som markering, eftersom en markering måste vara ett heltal. Din metod ser ut så här:

Nu när du har en heltalsrepresentation av din incheckning behöver du ett datum för incheckningsmetadata. Eftersom datumet uttrycks i katalognamnet plockar du ut det därifrån. Nästa rad i din print_export‑fil är:

där convert_dir_to_date är definierad så här:

Detta returnerar ett heltal för datumet för varje katalog. Den sista metainformationen du behöver för varje incheckning är incheckardata, som du hårdkodar i en global variabel:

Nu är du redo att börja skriva ut incheckningsdata för ditt importskript. Den inledande informationen anger att du definierar ett incheckningsobjekt och vilken gren det ligger på, följt av markeringen du har genererat, incheckarinformationen och incheckningsmeddelandet, och sedan den föregående incheckningen om det finns någon. Koden ser ut så här:

Du hårdkodar tidszonen (-0700) eftersom det är enkelt att göra. Om du importerar från ett annat system måste du ange tidszonen som ett offset. Incheckningsmeddelandet måste uttryckas i ett särskilt format:

Formatet består av ordet data, storleken på datan som ska läsas, en radbrytning och till sist datan. Eftersom du behöver använda samma format för att ange filinnehållet senare skapar du en hjälpfunktion, export_data:

Allt som återstår är att ange filinnehållet för varje ögonblicksbild. Det är enkelt eftersom du har varje ögonblicksbild i en katalog – du kan skriva ut kommandot deleteall följt av innehållet i varje fil i katalogen. Git registrerar sedan varje ögonblicksbild på rätt sätt:

Obs: Eftersom många system ser sina revisioner som förändringar från en incheckning till en annan kan fast-import också ta emot kommandon med varje incheckning som anger vilka filer som har lagts till, tagits bort eller ändrats och vad det nya innehållet är. Du skulle kunna beräkna skillnaderna mellan ögonblicksbilderna och bara tillhandahålla denna data, men det är mer komplext – du kan lika gärna ge Git all data och låta den lista ut det. Om detta passar dina data bättre, se manualsidan för fast-import för detaljer om hur du tillhandahåller data på detta sätt.

Formatet för att lista det nya filinnehållet eller ange en modifierad fil med det nya innehållet är följande:

Här är 644 läget (om du har körbara filer behöver du upptäcka och ange 755 i stället), och inline säger att du listar innehållet direkt efter denna rad. Din inline_data‑metod ser ut så här:

Du återanvänder metoden export_data som du definierade tidigare, eftersom den är densamma som när du angav data för incheckningsmeddelandet.

Det sista du behöver göra är att returnera den aktuella markeringen så att den kan skickas vidare till nästa varv:

Det var allt. Här är skriptet i sin helhet:

Om du kör detta skript får du innehåll som ser ut ungefär så här:

För att köra importskriptet skickar du denna utdata genom git fast-import medan du står i Git‑katalogen du vill importera till. Du kan skapa en ny katalog och sedan köra git init i den som startpunkt, och sedan köra ditt skript:

Som du ser, när den slutförs korrekt ger den dig en massa statistik över vad den åstadkom. I det här fallet importerade du totalt 13 objekt för 4 incheckningar till en gren. Nu kan du köra git log för att se din nya historik:

Där har du det – ett snyggt, rent Git‑kodförråd. Det är viktigt att notera att inget är utcheckat – du har inga filer i arbetskatalogen till att börja med. För att få dem måste du återställa din gren till där master är nu:

Du kan göra mycket mer med verktyget fast-import – hantera olika lägen, binärdata, flera grenar och sammanslagningar, taggar, förloppsindikatorer och mer. Flera exempel på mer komplexa scenarier finns i katalogen contrib/fast-import i Gits källkod.