För att underlätta felsökning av frontänder ignorerar fast-import alla rader som börjar med # (ASCII-pund/hash) upp till och inklusive raden som slutar LF. En kommentarsrad kan innehålla vilken bytesekvens som helst som inte innehåller en LF och kan därför användas för att inkludera detaljerad felsökningsinformation som kan vara specifik för frontänden och användbar vid inspektion av en fast-importdataström.

Följande datumformat stöds. Ett gränssnitt bör välja det format som ska användas för denna import genom att skicka formatnamnet i kommandoradsalternativet --date-format=<fmt>.

fast-import accepterar flera kommandon för att uppdatera det aktuella kodförrådet och kontrollera den aktuella importprocessen. Mer detaljerad diskussion (med exempel) av varje kommando följer senare.

Skapa eller uppdatera en gren med en ny incheckning, och registrera en logisk ändring i projektet.

där <ref> är namnet på grenen att göra incheckning på. Vanligtvis har grennamn prefixet refs/heads/ i Git, så import av CVS-grensymbolen RELENG-1_0 skulle använda refs/heads/RELENG-1_0 för värdet för <ref>. Värdet för <ref> måste vara ett giltigt refnamn i Git. Eftersom LF inte är giltigt i ett Git-refnamn, stöds ingen citerings- eller escapesyntax här.

Ett mark-kommando kan valfritt visas och begär fast-import för att spara en referens till den nyskapade incheckningen för framtida bruk av frontänden (se nedan för format). Det är mycket vanligt att frontänder markerar varje incheckning de skapar, vilket möjliggör framtida skapande av grenar från alla importerade incheckningar.

Kommandot data som följer efter committer måste tillhandahålla incheckningsmeddelandet (se nedan för data-kommandosyntax). För att importera ett tomt incheckningsmeddelande, använd en data med längden 0. Incheckningsmeddelanden är fritt formaterade och tolkas inte av Git. För närvarande måste de kodas i UTF-8, eftersom fast-import inte tillåter att andra kodningar anges.

Noll eller fler filemodify, filedelete, filecopy, filerename, filedeleteall och notemodify-kommandon kan inkluderas för att uppdatera innehållet i grenen innan incheckning skapas. Dessa kommandon kan anges i valfri ordning. Det rekommenderas dock att ett filedeleteall-kommando föregår alla filemodify, filecopy, filerename och notemodify-kommandon i samma incheckning, eftersom filedeleteall rensar grenen (se nedan).

LF efter kommandot är valfritt (det var tidigare obligatoriskt). Observera att av bakåtkompatibilitetsskäl, om commit-kommandot avslutas med ett data-kommando (d.v.s. det har inga from-, merge-, filemodify-, filedelete-, filecopy-, filerename-, filedeleteall- eller notemodify-kommandon) så kan två LF-kommandon visas i slutet av kommandot i stället för bara ett.

Gör så att fast-import sparar en referens till det aktuella objektet, så att frontänden kan återanvända objektet vid ett senare tillfälle utan att känna till dess SHA-1. Här är det aktuella objektet det objektskapande kommando som mark-kommandot förekommer i. Detta kan vara commit, tag eller blob, men commit är vanligast.

där <idnum> är numret som frontänden har tilldelat markeringen. Värdet för <idnum> uttrycks som ett decimalt ASCII-heltal. Värdet 0 är reserverat och kan inte användas som markering. Endast värden större än eller lika med 1 får användas som markeringar.

Nya markeringar skapas automatiskt. Befintliga markeringar kan flyttas till ett annat objekt genom att återanvända samma <idnum> i ett annat mark-kommando.

Tillhandahåller objektets namn i det ursprungliga versionshanteringssystemet. fast-import ignorerar direktivet, men filterprocesser som arbetar på och ändrar strömmen innan den matas till fast-import kan ha nytta av informationen

där <object-identifier> är en valfri sträng som inte innehåller LF.

Skapar en annoterad tagg som pekar på en specifik incheckning. För att skapa lättviktiga (icke-annoterade) taggar, se kommandot reset nedan.

där <name> är namnet på taggen som ska skapas.

Taggnamn får automatiskt prefixet refs/tags/ när de lagras i Git, så import av CVS-grensymbolen RELENG-1_0-FINAL skulle använda enbart RELENG-1_0-FINAL som <name>, och fast-import skriver motsvarande referens som refs/tags/RELENG-1_0-FINAL.

Värdet för <name> måste vara ett giltigt referensnamn i Git och kan därför innehålla snedstreck. Eftersom LF inte är giltigt i ett Git-referensnamn stöds ingen citerings- eller escapesyntax här.

Kommandot from är samma som i kommandot commit; se ovan för detaljer.

Kommandot tagger använder samma format som committer i commit; se återigen ovan för detaljer.

Kommandot data efter tagger måste leverera det annoterade taggmeddelandet (se nedan för syntaxen för data). För att importera ett tomt taggmeddelande används data med längd 0. Taggmeddelanden är fria i formen och tolkas inte av Git. För närvarande måste de kodas i UTF-8, eftersom fast-import inte tillåter att andra kodningar anges.

Signering av annoterade taggar under import inifrån fast-import stöds inte. Att försöka inkludera en egen PGP/GPG-signatur rekommenderas inte, eftersom frontänden inte (enkelt) har tillgång till hela mängden byte som normalt ingår i en sådan signatur. Om signering krävs, skapa lättviktiga taggar i fast-import med reset och skapa sedan annoterade versioner av taggarna offline med standardprocessen git tag.

Skapar (eller återskapar) den namngivna grenen, valfritt med start från en specifik revision. Kommandot reset låter ett frontändsprogram utfärda ett nytt from-kommando för en befintlig gren, eller skapa en ny gren från en befintlig incheckning utan att skapa en ny incheckning.

En detaljerad beskrivning av <ref> och <commit-ish> finns ovan under commit och from.

LF efter kommandot är valfri (den var tidigare obligatorisk).

Kommandot reset kan också användas för att skapa lättviktiga (icke-annoterade) taggar. Till exempel:

skulle skapa den lättviktiga taggen refs/tags/938 som pekar på den incheckning markeringen :938 refererar till.

Begär att en filrevision skrivs till packfilen. Revisionen är inte kopplad till någon incheckning; kopplingen måste skapas i ett efterföljande commit-kommando genom att referera till blobben via en tilldelad markering.

Kommandot mark är valfritt här eftersom vissa frontänder väljer att själva generera Git-SHA-1 för blobben och mata det direkt till commit. Det är dock vanligtvis mer arbete än det är värt, eftersom markeringar är billiga att lagra och enkla att använda.

Levererar rådata (för användning som blob-/filinnehåll, incheckningsmeddelanden eller annoterade taggmeddelanden) till fast-import. Data kan levereras med ett exakt byteantal eller avgränsas med en avslutande rad. Riktiga frontänder för konverteringar i produktionskvalitet bör alltid använda formatet med exakt byteantal, eftersom det är robustare och ger bättre prestanda. Det avgränsade formatet är främst avsett för test av fast-import.

Kommentarrader som förekommer inom <raw>-delen av data-kommandon betraktas alltid som en del av datakroppen och ignoreras därför aldrig av fast-import. Det gör det säkert att importera fil-/meddelandeinnehåll vars rader kan börja med #.

Registrera att en markering refererar till ett givet objekt utan att först skapa något nytt objekt.

En detaljerad beskrivning av <commit-ish> finns ovan under from.

Tvingar fast-import att stänga den aktuella packfilen, starta en ny och spara ut alla aktuella grenreferenser, taggar och markeringar.

Observera att fast-import automatiskt byter packfil när den aktuella packfilen når --max-pack-size, eller 4 GiB, beroende på vilket gränsvärde som är lägst. Vid ett automatiskt packfilsbyte uppdaterar fast-import inte grenreferenser, taggar eller markeringar.

Eftersom ett checkpoint kan kräva betydande mängd CPU-tid och disk-I/O (för att beräkna packfilens övergripande SHA-1-kontrollsumma, generera motsvarande indexfil och uppdatera referenserna) kan ett enskilt checkpoint-kommando lätt ta flera minuter att slutföra.

Importverktyg kan välja att utfärda kontrollpunkter under extremt stora och långkörande importer, eller när de behöver ge en annan Git-process åtkomst till en gren. Med tanke på att ett Subversion-kodförråd på 30 GiB kan laddas in i Git via fast-import på omkring 3 timmar kan explicita kontrollpunkter dock vara onödiga.

LF efter kommandot är valfri (den var tidigare obligatorisk).

Gör att fast-import skriver ut hela progress-raden oförändrad till sin standardutdatakanal (fildeskriptor 1) när kommandot behandlas från inmatningsströmmen. Kommandot påverkar i övrigt varken den aktuella importen eller fast-imports interna tillstånd.

<any>-delen av kommandot kan innehålla valfri bytesekvens som inte innehåller LF. LF efter kommandot är valfri. Anropare kan vilja bearbeta utdatan med ett verktyg som sed för att ta bort den inledande delen av raden, till exempel:

Om ett progress-kommando placeras direkt efter ett checkpoint får läsaren veta när checkpoint har slutförts och när det är säkert att komma åt referenserna som fast-import uppdaterade.

Gör att fast-import skriver ut SHA-1 som motsvarar en markering till stdout eller till fildeskriptorn som tidigare angivits med argumentet --cat-blob-fd. Kommandot påverkar i övrigt inte den aktuella importen; syftet är att hämta SHA-1 som senare incheckningar kan vilja referera till i sina incheckningsmeddelanden.

Se “Responses To Commands” nedan för detaljer om hur utdatan läses på ett säkert sätt.

Gör att fast-import skriver ut en blob till en fildeskriptor som tidigare angivits med argumentet --cat-blob-fd. Kommandot påverkar i övrigt inte den aktuella importen; huvudsyftet är att hämta blobbar som kan finnas i fast-imports minne men inte är åtkomliga från målkodförrådet.

<dataref> kan vara antingen en tidigare satt mark-referens (:<idnum>) eller en fullständig 40-byte SHA-1 för en Git-blob, redan befintlig eller redo att skrivas.

Utdata använder samma format som git cat-file --batch:

Kommandot kan användas där ett filemodify-direktiv kan förekomma, vilket gör att det kan användas mitt i en incheckning. För en filemodify som använder ett inline-direktiv kan det också förekomma precis före data-direktivet.

Se “Responses To Commands” nedan för detaljer om hur utdatan läses på ett säkert sätt.

Skriver information om objektet på en sökväg till en fildeskriptor som tidigare angivits med argumentet --cat-blob-fd. Detta gör det möjligt att skriva ut en blob från den aktiva incheckningen (med cat-blob) eller kopiera en blob eller ett träd från en tidigare incheckning för användning i den aktuella (med filemodify).

Kommandot ls kan också användas där ett filemodify-direktiv kan förekomma, vilket gör att det kan användas mitt i en incheckning.

Se filemodify ovan för en detaljerad beskrivning av <path>.

Utdata använder samma format som git ls-tree <tree> -- <path>:

<dataref> representerar blobben, trädet eller incheckningsobjektet vid <path> och kan användas i senare kommandon get-mark, cat-blob, filemodify eller ls.

Om det inte finns någon fil eller något underträd på den sökvägen rapporterar git fast-import i stället

Se “Responses To Commands” nedan för detaljer om hur utdatan läses på ett säkert sätt.

Kräv att fast-import stöder den angivna funktionen, eller avbryt om den inte gör det.

<feature>-delen av kommandot kan vara någon av följande:

Bearbetar det angivna alternativet så att git fast-import beter sig på ett sätt som passar frontändens behov. Observera att alternativ som anges av frontänden åsidosätts av alternativ som användaren anger till git fast-import självt.

<option>-delen av kommandot kan innehålla vilket som helst av alternativen i avsnittet OPTIONS som inte ändrar importsemantiken, utan inledande --, och behandlas på samma sätt.

Alternativkommandon måste vara de första kommandona i indata (feature-kommandon räknas inte); att ge ett alternativkommando efter ett icke-alternativkommando är ett fel.

Följande kommandoradsalternativ ändrar importsemantiken och får därför inte skickas som option:

Om funktionen done inte används behandlas det som om EOF lästes. Detta kan användas för att få fast-import att avsluta tidigare.

Om kommandoradsalternativet --done eller kommandot feature done används är kommandot done obligatoriskt och markerar slutet på strömmen.

Vid konvertering av ett kodförråd, använd en unik markering per incheckning (mark :<n>) och ange alternativet --export-marks på kommandoraden. fast-import skriver då ut en fil som listar varje markering och motsvarande Git-objekts SHA-1. Om frontänden kan koppla markeringarna tillbaka till källkodförrådet är det enkelt att verifiera importens korrekthet och fullständighet genom att jämföra varje Git-incheckning med motsvarande källrevision.

För den som kommer från ett system som Perforce eller Subversion bör detta vara ganska enkelt, eftersom fast-import-markeringen också kan vara Perforces ändringsmängdsnummer eller Subversions revisionsnummer.

Lägg inte kraft på att optimera frontänden för att hålla sig till en gren i taget under en import. Även om det kan vara något snabbare för fast-import tenderar det att öka komplexiteten i frontändens kod avsevärt.

Den inbyggda gren-LRU:n i fast-import fungerar i regel mycket bra, och kostnaden för att aktivera en inaktiv gren är så låg att hopp mellan grenar i praktiken inte påverkar importprestandan.

Vid import av en omdöpt fil eller katalog, ta helt enkelt bort de gamla namnen och ändra de nya namnen i motsvarande incheckning. Git upptäcker namnbyten i efterhand, snarare än explicit under en incheckning.

Vissa andra SCM-system låter användaren skapa en tagg från flera filer som inte kommer från samma incheckning/ändringsmängd. Eller skapa taggar som bara är en delmängd av filerna i kodförrådet.

Att importera sådana taggar oförändrade i Git är omöjligt utan att göra minst en incheckning som “fixar upp” filerna så att de matchar taggens innehåll. Använd fast-imports reset-kommando för att nollställa en hjälpgren utanför det normala grenutrymmet till baskommitten för taggen, checka sedan in en eller flera fil-fixup-incheckningar och tagga till sist hjälpgrenen.

Eftersom alla normala grenar till exempel lagras under refs/heads/ kan tagg-fixup-grenen heta TAG_FIXUP. Då kan fixup-grenen som importören använder inte få namnrymdskonflikter med riktiga grenar importerade från källan (namnet TAG_FIXUP är inte refs/heads/TAG_FIXUP).

Vid fixup-incheckningar kan merge användas för att koppla incheckning(ar) som levererar filrevisioner till fixup-grenen. Då kan verktyg som git blame följa den verkliga incheckningshistoriken och annotera källfilerna korrekt.

När fast-import har avslutats behöver frontänden köra rm .git/TAG_FIXUP för att ta bort hjälpgrenen.

Så snart fast-import är klart är Git-kodförrådet helt giltigt och redo att användas. Vanligtvis tar detta bara mycket kort tid, även för stora projekt (100 000+ incheckningar).

Ompackning av kodförrådet behövs dock för att förbättra datalokalitet och åtkomstprestanda. Det kan också ta timmar i extremt stora projekt (särskilt om -f och ett stort värde för --window används). Eftersom ompackning är säker att köra parallellt med läsare och skribenter kan ompackningen köras i bakgrunden och bli klar när den blir klar. Det finns ingen anledning att vänta med att utforska det nya Git-projektet!

Om ompackningen inväntas, försök inte köra prestandatester förrän ompackningen är klar. fast-import producerar mindre optimala packfiler som normalt aldrig ses i verkliga användningsfall.

Vid ompackning av mycket gammal importerad data (t.ex. äldre än det senaste året), överväg att använda lite extra CPU-tid och ange --window=50 (eller högre) när git repack körs. Det tar längre tid, men ger också en mindre packfil. Detta behöver bara göras en gång, och alla som använder projektet får nytta av det mindre kodförrådet.

Låt frontänden skicka ett progress-meddelande till fast-import då och då. Innehållet i meddelandena är helt fritt, så ett förslag är att skriva ut aktuell månad och år varje gång den aktuella incheckningsdagen går in i nästa månad. Användarna känner sig tryggare när de vet hur stor del av dataströmmen som har behandlats.

fast-import upprätthåller en minnesstruktur för varje objekt som skrivs under körningen. På ett 32-bitars system är strukturen 32 byte, på ett 64-bitars system är den 40 byte (på grund av större pekarstorlek). Objekt i tabellen frigörs inte förrän fast-import avslutas. Import av 2 miljoner objekt på ett 32-bitars system kräver ungefär 64 MiB minne.

Objekttabellen är i praktiken en hash-tabell nycklad på objektnamnet (den unika SHA-1). Lagringskonfigurationen gör att fast-import kan återanvända ett befintligt eller redan skrivet objekt och undvika att skriva dubletter till utdata-packfilen. Duplicerade blobbar är förvånansvärt vanliga i en import, ofta på grund av grensammanslagningar i källan.

Markeringar lagras i en gles array, med 1 pekare (4 eller 8 byte, beroende på pekarstorlek) per markering. Även om arrayen är gles uppmuntras frontänder starkt att använda markeringar mellan 1 och n, där n är det totala antalet markeringar som krävs för importen.

Grenar klassificeras som aktiva eller inaktiva. Minnesanvändningen för de två klasserna skiljer sig avsevärt.

Inaktiva grenar lagras i en struktur som använder 96 eller 120 byte (32- respektive 64-bitars system), plus längden på grennamnet (vanligen under 200 byte), per gren. fast-import hanterar utan problem så många som 10 000 inaktiva grenar med under 2 MiB minne.

Aktiva grenar har samma overhead som inaktiva grenar, men innehåller också kopior av varje träd som nyligen har ändrats på grenen. Om underträdet include inte har ändrats sedan grenen blev aktiv laddas dess innehåll inte in i minnet, men om underträdet src har ändrats av en incheckning sedan grenen blev aktiv laddas dess innehåll in i minnet.

Eftersom aktiva grenar lagrar metadata om filerna på grenen kan deras minnesstorlek växa till en betydande nivå (se nedan).

fast-import flyttar automatiskt aktiva grenar till inaktiv status baserat på en enkel least-recently-used-algoritm. LRU-kedjan uppdateras vid varje commit-kommando. Maximalt antal aktiva grenar kan ökas eller minskas på kommandoraden med --active-branches=.

Träd (d.v.s. kataloger) använder bara 12 byte minne utöver minnet som krävs för deras poster (se “per active file” nedan). Kostnaden för ett träd är i praktiken 0, eftersom overheaden amorteras över de enskilda filposterna.

Filer (och pekare till underträd) inom aktiva träd kräver 52 eller 64 byte (32/64-bitars plattformar) per post. För att spara utrymme samlas fil- och trädnamn i en gemensam strängtabell, vilket gör att filnamnet "Makefile" bara använder 16 byte (efter att stränghuvudet har inkluderats) oavsett hur många gånger det förekommer inom projektet.

Den aktiva gren-LRU:n, tillsammans med strängpool för filnamn och lat inläsning av underträd, gör att fast-import effektivt kan importera projekt med 2 000+ grenar och 45 114+ filer med mycket begränsat minnesavtryck (mindre än 2,7 MiB per aktiv gren).