9.2 Git and Other Systems - Migrating to Git

As jy die vorige afdeling gelees het oor die gebruik van git svn, kan jy daardie instruksies maklik gebruik om git svn clone van 'n bewaarplek te doen; stop dan om die Subversion-bediener te gebruik, push na 'n nuwe Git-bediener, en begin dit gebruik. As jy die geskiedenis wil hê, kan jy dit bereik so vinnig as wat jy die data uit die Subversion-bediener kan uittrek (wat 'n rukkie kan neem).

Die invoer is egter nie perfek nie; en omdat dit so lank sal neem, kan jy dit net as goed reg doen. Die eerste probleem is die outeurinligting. In Subversion het elke persoon wat 'n vaslegging doen, 'n gebruiker op die stelsel wat in die vasleggingsinligting opgeteken word. Die voorbeelde in die vorige afdeling wys schacon op sommige plekke, soos die blame-afvoer en die git svn log. As jy dit na betere Git-outeurdata wil kaart, benodig jy 'n kartering van die Subversion-gebruikers na die Git-outeurs. Skep 'n lêer genaamd users.txt wat hierdie kartering in 'n formaat soos dit het:

Om 'n lys te kry van die outeursname wat SVN gebruik, kan jy dit uitvoer:

Dit genereer die log-afvoer in XML-formaat, behou dan slegs die reëls met outeurinligting, gooi duplikate weg en stroop die XML-merkers uit. Dit werk uiteraard net op 'n masjien waarop grep, sort en perl geïnstalleer is. Leid dan daardie afvoer na jou users.txt lêer om sodat jy die ekwivalente Git-gebruikersdata langs elke inskrywing kan byvoeg.

Jy kan hierdie lêer aan git svn verskaf om dit te help om die outeurdata akkuraat te kaart. Jy kan ook vir git svn sê om nie die metadata in te sluit wat Subversion normaalweg invoer nie, deur --no-metadata na die clone of init opdrag deur te gee. Die metadata sluit 'n git-svn-id binne elke vasleggingsboodskap in wat Git tydens invoer sal genereer. Dit kan jou Git-log laat uitswel en dit dalk 'n bietjie onduidelik maak.

Dit laat jou import-opdrag so lyk:

Nou behoort jy 'n mooier Subversion-invoer in jou my_project gids te hê. In plaas van vasleggings wat so lyk:

lyk hulle soos dit:

Nie net lyk die Outeurveld baie beter nie, maar die git-svn-id is ook nie meer daar nie.

Jy moet ook 'n bietjie skoonmaak na die invoer doen. Een ding is dat jy die vreemde verwysings wat git svn opgestel het, moet skoonmaak. Eers sal jy die merkers skuif sodat dit werklike merkers is eerder as vreemde afgeleë takke, en dan sal jy die res van die takke skuif sodat hulle plaaslik is.

Om die merkers na egte Git-merkers te skuif, voer uit:

Dit neem die verwysings wat afgeleë takke was wat met refs/remotes/tags/ begin het, en maak werklike (liggewig) merkers daarvan.

Volgende, skuif die res van die verwysings onder refs/remotes om plaaslike takke te wees:

Dit kan gebeur dat jy 'n paar ekstra takke sal sien wat agtervoegsels het van @xxx (waar xxx 'n nommer is), terwyl jy in Subversion net een tak sien. Dit is eintlik 'n Subversion-funksie genaamd “peg-revisions”, wat iets is waarvoor Git eenvoudig geen sintaktiese eweknie het nie. Vandaar dat git svn eenvoudig die SVN-weergawenommer by die taknaam voeg op presies dieselfde manier as wat jy dit in SVN sou geskryf het om die peg-hersiening van daardie tak te adresseer. As jy nie meer omgee vir die peg-hersienings nie, verwyder hulle eenvoudig:

Nou is al die ou takke egte Git-takke en al die ou merkers egte Git-merkers.

Daar is een laaste ding om op te skoon. Ongelukkig skep git svn 'n ekstra tak genaamd trunk, wat na Subversion se verstektak karteer, maar die trunk verwysing wys na dieselfde plek as master. Aangesien master meer idiomaties Git is, is hier hoe om die ekstra tak te verwyder:

Die laaste ding om te doen is om jou nuwe Git-bediener as 'n remote by te voeg en daarna te push. Hier is 'n voorbeeld van die byvoeging van jou bediener as 'n remote:

Omdat jy wil hê al jou takke en merkers moet opstoot, kan jy nou dit uitvoer:

Al jou takke en merkers behoort op jou nuwe Git-bediener te wees in 'n lekker, skoon invoer.

Aangesien Mercurial en Git taamlik soortgelyke modelle het om weergawes te verteenwoordig, en aangesien Git 'n bietjie more buigsaam is, is dit vrij eenvoudig om 'n bewaarplek van Mercurial na Git te konverteer deur gebruik te maak van 'n hulpmiddel genaamd "hg-fast-export", waarvan jy 'n kopie nodig sal hê:

Die eerste stap in die omskakeling is om 'n volledige kloon te kry van die Mercurial-bewaarplek wat jy wil konverteer:

Die volgende stap is om 'n outeurskarteringslêer te skep. Mercurial is 'n bietjie meer vergewensgesind as Git oor wat dit in die outeursveld vir wysigingstelle (changesets) plaas, so dit is 'n goeie tyd om huis skoon te maak. Om dit te genereer is 'n eenreël-opdrag in 'n bash dop:

Dit sal 'n paar sekondes neem, afhangende van hoe lank jou projek se geskiedenis is, en daarna sal die /tmp/authors lêer so iets lyk:

In hierdie voorbeeld het dieselfde persoon (Bob) wysigingstelle geskep onder vier verskillende name, waarvan een eintlich korrek lyk, en een daarvoor heeltemal ongeldig sou wees vir 'n Git-vaslegging. hg-fast-export laat ons dit regmaak deur elke reël in 'n reël te verander: "<input>"="<output>", wat 'n <input> na 'n <output> karteer. Binne die <input> en <output> stringe word alle ontsnappingsreekse (escape sequences) wat deur die Python string_escape kodering verstaan word, ondersteun. As die outeurskarteringslêer nie 'n ooreenstemmende <input> bevat nie, sal daardie outeur ongewijzigd na Git aangestuur word. As al die gebruikersname goed lyk, benodig ons hierdie lêer glad nie. In hierdie voorbeeld wil ons hê ons lêer moet so lyk:

Dieselfde soort karteringslêer kan gebruik word om takke en merkers te hernoem wanneer die Mercurial-naam nie deur Git toegelaat word nie.

Die volgende stap is om ons nuwe Git-bewaarplek te skep en die uitvoerskrip te laat loop:

Die -r vlag vertel hg-fast-export waar om die Mercurial-bewaarplek te vind wat ons wil konverteer, en die -A vlag vertel dit waar om die outeurskarteringslêer te vind (tak- en merkerkarteringslêers word onderskeidelik deur die -B en -T vlae gespesifiseer). Die skrip ontleed Mercurial-wysigingstelle en skakel dit om in 'n skrip vir Git se "fast-import" kenmerk (wat ons 'n bietjie later in detail sal bespreek). Dit neem 'n bietjie (alhoewel dit baie vinniger is as wat dit oor die netwerk sou wees), en die afvoer is taamlik lankdradig (verbose):

Dis omtrent al wat daar is. Al die Mercurial-merkers is na Git-merkers omgeskakel, en Mercurial-takke en -boekmerke is na Git-takke omgeskakel. Nou is jy gereed om die bewaarplek na sy nuwe bedienerkant-tuis te push:

Die volgende stelsel waarna jy sal kyk om van in te voer, is Perforce. Soos ons hierbo bespreek het, is daar twee maniere om Git en Perforce met mekaar te laat praat: git-p4 en Perforce Git Fusion.

As jou stelsel nie een van bogenoemde is nie, moet jy aanlyn na 'n invoerder soek – gehalte-invoerders is beskikbaar vir baie ander stelsels, insluitend CVS, Clear Case, Visual Source Safe, selfs 'n gids van argiewe. As geen van hierdie hulpmiddels vir jou werk nie, jy 'n meer obskure hulpmiddel het, of jy andersins 'n meer pasgemaakte invoerproses benodig, moet jy git fast-import gebruik. Hierdie opdrag lees eenvoudige instruksies vanaf stdin om spesifieke Git-data te skryk. Dit is baie makliker om Git-objekte op hierdie manier te skep as om die rou Git-opdragte uit te voer of te probeer om die rou objekte te skryf (sien Git Internals vir meer inligting). Op hierdie manier kan jy 'n invoerskrip skryf wat die nodige inligting uit die stelsel lees waaruit jy invoer en reguit instruksies na stdout druk. Jy kan dan hierdie program uitvoer en sy afvoer deur git fast-import pyp (pipe).

Om vinnig te demonstreer, gaan jy 'n eenvoudige invoerder skryf. Sê nou jy werk in current, jy rugsteun jou projek deur die gids af en toe te kopieer na 'n tydgestempelde back_YYYY_MM_DD rugsteungids, en jy wil dit in Git invoer. Jou gidsstruktuur lyk soos dit:

Ten einde 'n Git-gids in te voer, moet jy hersien hoe Git sy data stoor. Soos jy dalk onthou, is Git fundamenteel 'n gekoppelde lys van vasleggingsobjekte (commit objects) wat wys na 'n momentopname (snapshot) van inhoud. Al wat jy hoef te doen is om vir fast-import te sê wat die inhoudmomentopnames is, watter vasleggingsdata daarna wys, en die volgorde waarin hulle gaan. Jou strategie sal wees om een vir een deur die momentopnames te gaan en vasleggings te skep met die inhoud van elke gids, en elke vaslegging terug te skakel na die vorige een.

Soos ons in 'n Voorbeeld van 'n Git-Afgedwonge Beleid (An Example Git-Enforced Policy) gedoen het, sal ons dit in Ruby skryf, omdat dit is waarmee ons gewoonlik werk en dit geneig is om maklik te lees te wees. Jy kan hierdie voorbeeld pretty maklik skryf in enigiets waarmee jy vertroud is – dit hoef net die gepaste inligting na stdout te druk. En, as jy op Windows loop, beteken dit dat jy spesiale sorg moet dra om nie wa-terugvoere (carriage returns) aan die einde van jou reëls in te voer nie – git fast-import is baie kieskeurig oor net die wil van reëltoevoere (line feeds - LF) en nie die wa-terugvoer-reëltoevoere (CRLF) wat Windows gebruik nie.

Om te begin, sal jy na die teikengids verander en elke subgids identifiseer, wat elk 'n momentopname is wat jy as 'n vaslegging wil invoer. Jy sal in elke subgids verander en die opdragte druk wat nodig is om dit te eksporteer. Jou basiese hooflus lyk soos dit:

Jy voer print_export binne elke gids uit, wat die manifes en merker van die vorige momentopname neem en die manifes en merker van hierdie een teruggee; op daardie manier kan jy hulle behoorlik koppel. “Merker” (Mark) is die fast-import term vir 'n identifiseerder wat jy aan 'n vaslegging gee; terwyl jy vasleggings skep, gee jy elkeen 'n merker wat jy kan gebruik om van ander vasleggings daaraan te skakel. Dus, die eerste ding om te doen in jou print_export metode is om 'n merker uit die gidself te genereer:

Jy sal dit doen deur 'n skikking (array) van gidse te skep en die indeksiewaarde as die merker te gebruik, omdat 'n merker 'n heelgetal (integer) moet wees. Jou metode lyk soos dit:

Noudat jy 'n heelgetalvoorstelling van jou vaslegging het, benodig jy 'n datum vir die vasleggingsmetadata. Omdat die datum in die naam van die gids uitgedruk word, gaan jy dit ontleed. Die volgende reël in jou print_export lêer is:

waar convert_dir_to_date gedefinieer word as:

Dit gee 'n heelgetalwaarde terug vir die datum van elke gids. Die laaste stukmetainligting wat jy vir elke vaslegging benodig, is die vaslêerdata (committer data), wat jy hardkodeer in 'n globale veranderlike:

Nou is jy gereed om te begin met die druk van die vasleggingsdata vir jou invoerder. Die aanvanklike inligting vermeld dat jy 'n vasleggingsobjek definieer en op watter tak dit is, gevolg deur die merker wat jy gegenereer het, die vaslêerinligting en vasleggingsboodskap, en dan die vorige vaslegging, indien enige. Die code lyk soos dit:

Jy hardkodeer die tydsone (-0700) omdat dit maklik is om dit te doen. As jy van 'n ander stelsel invoer, moet jy die tydsone as 'n verrekening (offset) spesifiseer. Die vasleggingsboodskap moet in 'n spesiale formaat uitgedruk word:

Die formaat bestaan uit die woord data, die grootte van die data wat gelees moet word, 'n nuwe reël, en uiteindelik die data. Omdat jy dieselfde formaat moet gebruik om die lêerinhoud later te spesifiseer, skep jy 'n hulpmetode, export_data:

Al wat oorbly, is om die lêerinhoud vir elke momentopname te spesifiseer. Dit is maklik, omdat jy elk in 'n gids het – jy kan die deleteall opdrag druk, gevolg deur die inhoud van elke lêer in die gids. Git sal dan elke momentopname gepas opteken:

Let wel: Omdat baie stelsels dink aan hul hersienings as veranderings van een vaslegging na 'n ander, kan fast-import ook opdragte neem met elke vaslegging om te spesifiseer watter lêers bygevoeg, verwyder of gewysig is en wat die nuwe inhoud is. Jy kan die verskille tussen momentopnames bereken en slegs hierdie data verskaf, maar om dit te doen is more kompleks – jy kan net as well vir Git al die data gee en dit laat uitvind. As dit beter by jou data pas, kyk na die fast-import man-bladsy vir besonderhede oor hoe om jou data op hierdie manier te verskaf.

Die formaat vir die lys van die nuwe lêerinhoud of die spesifikasie van 'n gewysigde lêer met die nuwe inhoud is as volg:

Hier is 644 die modus (as jy uitvoerbare lêers het, moet jy 755 in plaas daarvan detekteer en spesifiseer), en inline sê dat jy die inhoud onmiddellik na hierdie reël sal lys. Jou inline_data metode lyk soos dit:

Jy hergebruik die export_data metode wat jy vroeër gedefinieer het, omdat dit dieselfde is as die manier waarop jy jou vasleggingsboodskapdata gespesifiseer het.

Die laaste ding wat jy moet doen is om die huidige merker terug te gee sodat dit aan die volgende herhaling (iteration) deurgegee kan word:

Dis dit. Hier is die skrip in sy geheel:

As jy hierdie skrip uitvoer, kry jy inhoud wat so iets lyk:

Om die invoerder te laat loop, pyp hierdie afvoer deur git fast-import terwyl jy in die Git-gids is waarin jy wil invoer. Jy kan 'n nuwe gids skep en dan git init daarin uitvoer vir 'n beginpunt, en dan jou skrip uitvoer:

Soos jy kan sien, wanneer dit suksesvol voltooi word, gee dit vir jou 'n trop statistieke oor wat dit bereik het. In hierdie geval het jy in totaal 13 objekte vir 4 vasleggings in 1 tak ingevoer. Nou kan jy git log uitvoer om jou nuwe geskiedenis te sien:

Daar het jy dit – 'n lekker, skoon Git-bewaarplek. Dit is belangrik om op te let dat niks uitgetrek is nie – jy het aanvanklik geen lêers in jou werkgids nie. Om hulle te kry, moet jy jou tak herstel (reset) na waar master nou is:

Jy kan baie meer met die fast-import hulpmiddel doen – verskillende modusse hanteer, binêre data, veelvuldige takke en saamsmelting, merkers, vorderingaanwysers, en meer. 'n Aantal voorbeelde van meer kompleks scenario’s is beskikbaar in die contrib/fast-import gids van die Git-bronkode.