Para ajudar na depuração dos "front-ends", A importação rápida ignora qualquer linha que comece com # (libra/hash ASCII), inclusive, até a linha que termina em LF. Uma linha de comentário pode conter qualquer sequência de bytes que não contenha um LF e, portanto, pode ser usada para incluir qualquer informação detalhada de depuração que possa ser específica do "front-end" e útil ao inspecionar um fluxo de dados de importação rápida.

Os seguintes formatos de data são compatíveis. Um "front-end" deve selecionar o formato que será utilizado para esta importação, repassando o nome do formato na opção da linha de comando --date-format=<fmt>.

A importação rápida aceita vários comandos para atualizar o repositório atual e controlar o processo de importação atual. Uma discussão mais detalhada (com exemplos) de cada comando será apresentada posteriormente.

Crie ou atualize uma ramificação com um novo commit, registrando uma alteração lógica no projeto.

Onde <ref> é o nome do ramo onde o commit deve ser feito. Normalmente, os nomes das ramificações são prefixados com refs/heads/ no Git, portanto, a importação do símbolo de ramificação do CVS RELENG-1_0 usaria refs/heads/RELENG-1_0 para o valor de <ref>. O valor de <ref> deve ser um nome de referência válido no Git. Como LF não é válido num refname do Git, aqui não há suporte para sintaxe de citação ou escape.

Um comando mark pode ser exibido opcionalmente, solicitando que a importação rápida salve uma referência ao commit recém-criado para uso futuro pelo "frontend" (veja o formato abaixo). É muito comum que os "front-ends" marquem cada commit que eles criam, permitindo assim a criação futura das ramificações a partir de qualquer commit que for importado.

O comando data que segue o committer deve repassar a mensagem do commit (veja abaixo a sintaxe do comando data). Para importar uma mensagem vazia do commit, use dados de comprimento 0. As mensagens do commit são de formato livre e não são interpretadas pelo Git. Atualmente, eles devem ser codificados em UTF-8, pois o "fast-import" não permite que outras codificações sejam definidas.

Zero ou mais comandos como filemodify, filedelete, filecopy, filerename, filedeleteall e notemodify podem ser incluídos para atualizar o conteúdo do ramo antes da criação do commit. Esses comandos podem ser repassados em qualquer ordem. No entanto, recomenda-se que um comando filedeleteall preceda todos os comandos filemodify, filecopy, filerename e notemodify no mesmo commit, pois o filedeleteall limpa a ramificação (veja abaixo).

O LF após o comando é opcional (antes era obrigatório). Observe que, por motivos de compatibilidade com as versões anteriores, se o commit terminar com um comando data (ou seja, não tiver comandos from, merge, filemodify, filedelete, filecopy, filederename, filedeleteall ou notemodify), dois comandos LF poderão aparecer no final do comando em vez de apenas um.

Faz com que a importação rápida salve uma referência ao objeto atual, permitindo que o "front-end" recupere esse objeto num momento futuro, sem conhecer o seu SHA-1. Aqui, o objeto atual é o comando de criação de objeto onde o comando mark aparece. Isso pode ser commit, tag e blob, mas commit é o uso mais comum.

Onde <idnum> é o número atribuído pelo "front-end" a esta marcação. O valor de <idnum> é expresso como um número inteiro decimal ASCII. O valor 0 é reservado e não pode ser usado como marcação. Apenas podem ser usados valores maiores ou iguais a 1 como marcações.

Novas marcações são criadas automaticamente. As marcas existentes podem ser movidas para outro objeto simplesmente reutilizando o mesmo <idnum> em outro comando mark.

Fornece o nome do objeto no sistema de controle da fonte original. A importação rápida simplesmente ignorará essa diretriz, porém, os processos de filtragem que operam e modificam o fluxo antes de alimentar a importação rápida podem usar estas informações

onde <identificador-do-objeto> é qualquer cadeia de caracteres que não contenha LF.

Cria uma etiqueta anotada referente a um commit específico. Para criar etiquetas simples (não anotadas), consulte o comando reset abaixo.

onde <nome> é o nome da tag a ser criada.

Os nomes das tags são prefixados automaticamente com refs/tags/ quando armazenados no Git, portanto, a importação do símbolo do ramo CVS RELENG-1_0-FINAL usaria apenas RELENG-1_0-FINAL para <nome> e o fast-import irá escrever um ref correspondente como refs/tags/RELENG-1_0-FINAL.

O valor de <nome> deve ser uma referência de nome válido no Git e, portanto, pode conter barras. Como LF não é válido num refname do Git, aqui não há suporte para sintaxe de citação ou escape.

O comando from é o mesmo que no comando commit; veja acima para detalhes.

O comando tagger usa o mesmo formato que committer dentro de commit; veja novamente acima para obter detalhes.

O comando data que segue o tagger deve repassar a mensagem da etiqueta anotada (veja abaixo a sintaxe do comando data). Para importar uma mensagem vazia do commit, use dados com comprimento 0. As mensagens da etiqueta são de formato livre e não são interpretadas pelo Git. Atualmente, eles devem ser codificados em UTF-8, pois o "fast-import" não permite que outras codificações sejam definidas.

Não há suporte para a assinatura das etiquetas anotadas durante a importação a vindas da importação rápida. Tentar incluir a sua própria assinatura PGP/GPG não é recomendável, pois o "front-end" não tem acesso (fácil) ao conjunto completo de bytes que normalmente é incluído numa assinatura deste tipo. Se a assinatura for necessária, crie etiquetas simples a partir da importação rápida com reset e, em seguida, crie as versões anotadas dessas etiquetas off-line com o processo padrão do comando git tag.

Cria (ou recria) o ramo nomeado, opcionalmente a partir de uma revisão específica. O comando reset permite que um "frontend" emita um novo comando from para uma ramificação já existente ou crie uma nova ramificação a partir de um commit existente sem criar um novo commit.

Para uma descrição detalhada sobre <ref> e <commit-ish> veja acima em commit e` from`.

O LF após o comando é opcional (costumava ser necessário).

O comando reset também pode ser usado para criar etiquetas simples (não anotadas). Por exemplo:

criaria a tag leve refs/tags/938 se referindo a qualquer marcação do commit :938.

Solicita a gravação de uma revisão de arquivo no pacote de arquivos. A revisão não está conectada a nenhum commit; essa conexão deve ser formada com um comando commit subsequente, referenciando a bolha por meio de uma marcação atribuída.

Aqui o comando "mark" é opcional, pois alguns "front-ends" optaram por gerar o Git SHA-1 para a bolha por conta própria e alimentá-lo diretamente no commit. No entanto, isso geralmente dá mais trabalho do que vale a pena, pois as marcações tem baixo custo de armazenamento e são fáceis de usar.

Fornece dados brutos para importação rápida (visando a utilização como conteúdo da bolha/arquivo, mensagens dos commits ou as mensagens das etiquetas anotadas). Os dados podem ser fornecidos usando uma contagem exata de bytes ou delimitados com uma linha de terminação. Os "front-ends" reais destinados a conversões com qualidade de produção devem sempre usar o formato de contagem exata de bytes, pois ele é mais robusto e tem melhor desempenho. O formato delimitado foi criado principalmente para testar a importação rápida.

As linhas de comentário que aparecem na parte <raw> dos comandos data são sempre consideradas como parte do corpo dos dados e, portanto, nunca são ignorados pela importação rápida. Isso torna seguro importar qualquer conteúdo de arquivo/mensagem cujas linhas possam começar com #.

Registre que uma marcação se refere a um determinado objeto sem criar primeiro nenhum novo objeto.

Para uma descrição detalhada do <commit-ish> veja acima em from.

Impõem o fast-import a fechar o arquivo de pacote atual, iniciar um novo e salvar todas os refs, tags e marcas das ramificações atuais.

Observe que a importação rápida alterna automaticamente os pacote de arquivos quando o pacote de arquivos atual atinge --max-pack-size ou 4 GiB, o que for menor. Durante uma troca automática do pacote de arquivos, a importação rápida não atualiza as referências, as etiquetas ou as marcações do ramo.

Como um checkpoint pode exigir uma quantidade significativa de tempo de CPU e E/S de disco (para calcular a soma de verificação SHA-1 do pacote geral, gerar o arquivo do índice correspondente e atualizar as refs), pode levar vários minutos para um único comando checkpoint para concluir.

Os "front-ends" podem optar por emitir pontos de controle durante importações extremamente grandes e de longa duração, ou quando precisarem permitir que outro processo do Git acesse um ramo. No entanto, como um repositório "Subversion" com 30 GiB pode ser carregado no Git através da importação rápida em cerca de 3 horas, o ponto de verificação explícito pode não ser necessário.

O LF após o comando é opcional (costumava ser necessário).

Faz com que a importação rápida imprima toda a linha progress sem alterações em seu canal de saída predefinida (descritor de arquivo 1) quando o comando é processado a partir do fluxo de entrada. O comando não tem impacto sobre a importação atual ou sobre qualquer condição interna da importação rápida.

A parte <qualquer> do comando pode conter qualquer sequência de bytes que não contenha um LF. O LF após o comando é opcional. Os invocadores podem querer processar a saída através de uma ferramenta como sed para remover a parte inicial da linha, por exemplo:

A colocação de um comando progress imediatamente após um checkpoint informará ao leitor quando o checkpoint seja concluído e ele poderá acessar com segurança os refs que o fast-import atualizaram.

Faz com que o fast-import imprima o SHA-1 correspondente a uma marcação em stdout ou ao descritor de arquivo previamente organizado com o argumento --cat-blob-fd. Caso contrário, o comando não tem impacto na importação atual; seu objetivo é recuperar o SHA-1s que commits posteriores podem querer se referir em suas mensagens de commit.

Consulte “RESPOSTAS AOS COMANDOS” abaixo para obter detalhes sobre como ler esta saída com segurança.

Faz com que a importação rápida grave uma bolha num descritor de arquivo previamente organizado com a opção --cat-blob-fd. O comando não tem impacto sobre a importação atual; o seu principal objetivo é recuperar as bolhas que podem estar na memória da importação rápida, mas que não podem ser acessadas pelo repositório de destino.

O <dataref> pode ser uma marcação de referência (:<idnum>) definida anteriormente ou um SHA-1 completo com 40 bytes de uma bolha Git pré-existente ou pronta para ser gravada.

A saída usa o mesmo formato que git cat-file --batch:

Este comando também pode ser usado quando um comando filemodify aparecer, permitindo que ele seja usado no meio de um commit. Para um filemodify que usa um comando em linha, ele também pode aparecer logo antes da opção data.

Consulte “RESPOSTAS AOS COMANDOS” abaixo para obter detalhes sobre como ler esta saída com segurança.

Exibe informações sobre o objeto num caminho para num descritor de arquivo previamente organizado com a opção --cat-blob-fd. Isso permite a exibição de uma bolha ativa do commit (com cat-blob) ou a cópia de uma bolha ou de uma árvore de um commit anterior para que seja usada no atual (com filemodify).

O comando ls também pode ser usado onde uma diretiva filemodify possa aparecer, permitindo que ela seja usada no meio de um commit.

Consulte filemodify acima para uma descrição detalhada de <caminho>.

A saída usa o mesmo formato que git ls-tree <árvore> -- <caminho>:

O <dataref> representa o objeto bolha, árvore ou commit no <caminho> e pode ser utilizado posteriormente nos comandos get-mark, cat-blob, filemodify ou ls.

Caso não haja um arquivo ou subárvore nesse caminho, o git fast-import o reportará

Consulte “RESPOSTAS AOS COMANDOS” abaixo para obter detalhes sobre como ler esta saída com segurança.

Exija que a importação rápida ofereça suporte ao recurso especificado ou o anule.

A parte <característica> do comando pode ser qualquer um dos seguintes:

Processa a opção especificada para que o comando git fast-import se comporte de uma forma que atenda às necessidades do frontend. Observe que as opções especificadas pelo frontend são substituídas por quaisquer opções que o usuário possa definir para o próprio comando git fast-import.

A parte <opção> do comando pode conter qualquer uma das opções listadas na seção OPTIONS que não alteram a semântica de importação, sem o -- principal e são tratadas da mesma maneira.

Os comandos de opção devem ser os primeiros comandos na entrada (sem contar os comandos de recurso), para fornecer um comando de opção após um erro que não seja de opção.

As seguintes opções de linha de comando alteram a semântica de importação e, portanto, não podem ser passadas como opção:

Se o recurso done não estiver em uso, será tratado como se um EOF tivesse sido lido. Isso pode ser usado para dizer à importação rápida para encerrar mais cedo.

Caso a opção de linha de comando --done ou o comando feature done estiver em uso, o comando done é obrigatório e marca o final do fluxo.

Ao fazer uma conversão do repositório, use uma marcação exclusiva por commit (mark :<n>) e use a opção --export-marks na linha de comando. O comando fast-import fará o despejo de um arquivo que lista todas as marcações e o objeto SHA-1 do Git que lhes corresponda. Se o frontend puder vincular as marcações ao repositório de origem, será fácil verificar a precisão e a integridade da importação comparando cada commit do Git com a revisão de origem correspondente.

Vindo de um sistema como o "Perforce" ou o "Subversion", isso deve ser bastante simples, pois a marcação do fast-import também pode ser o número do conjunto de alterações do "Perforce" ou o número da revisão do "Subversion".

Não se preocupe em tentar otimizar o frontend para se ater a um ramo de cada vez durante uma importação. Embora isso possa ser um pouco mais rápido para a importação rápida, tende a aumentar consideravelmente a complexidade do código do frontend.

O LRU do ramo incorporado ao fast-import tende a se comportar muito bem e o custo de ativar uma ramo inativo é tão baixo que o movimento entre os ramos praticamente não tem impacto no desempenho da importação.

Ao importar um arquivo ou diretório renomeado, basta excluir o(s) nome(s) antigo(s) e alterar o(s) novo(s) nome(s) durante o commit correspondente. O Git realiza a detecção de renomeação após o fato, em vez de fazê-lo explicitamente durante um commit.

Alguns outros sistemas SCM permitem que o usuário crie uma etiqueta a partir de vários arquivos que não sejam do mesmo commit ou de um conjunto de alterações. Ou para criar etiquetas que sejam um subconjunto dos arquivos disponíveis no repositório.

É impossível importar estas etiquetas como estão no Git sem fazer pelo menos um commit que "corrija" os arquivos para que então correspondam ao conteúdo da etiqueta. Use o comando reset do fast-import para redefinir um ramo fictício fora do seu espaço normal de ramificações para o commit base da etiqueta, depois faça um ou mais commits para correção de arquivos e, finalmente, marque a ramificação fantasia.

Por exemplo, como todas as ramificações normais são armazenadas em refs/heads/, nomeie a etiqueta da ramificação de correção como TAG_FIXUP. Desta maneira, é impossível que o ramo de correção usado pelo importador tenha conflitos no espaço de nome com ramos reais que foram importados da fonte (o nome TAG_FIXUP não é refs/heads/TAG_FIXUP).

Ao fazer o commit com as correções, considere o uso de merge para conectar o(s) commit(s) que está(ão) fornecendo revisões dos arquivos ao ramo com as correções. Isso permitirá que ferramentas como o git blame rastreiem o histórico real dos commits e anotem corretamente os arquivos de origem.

Quando o fast-import encerrar, o front-end precisará executar o comando rm .git/TAG_FIXUP para remover a ramificação fantasia.

Assim que o comando fast-import for concluído, o repositório Git estará completamente válido e pronto para uso. Normalmente, isso leva muito pouco tempo, mesmo em projetos consideravelmente grandes (com mais de 100.000 commits).

No entanto, é necessário reempacotar o repositório para melhorar a localidade dos dados e o desempenho do acesso. Isso também pode levar horas em projetos extremamente grandes (especialmente se for usado o parâmetro -f e uma grande janela --window). Como o reempacotamento é seguro para ser executado junto com os leitores e os escritores, execute o reempacotamento em segundo plano e deixe-o ser concluído quando acabar. Não há razão para esperar a exploração do seu novo projeto Git!

Se você optar por esperar o reempacotamento, não tente executar "benchmarks" ou testes de desempenho até a conclusão do reempacotamento. A importação rápida gera pacotes com arquivos abaixo do ideal que nunca são vistos em situações reais de uso.

Se estiver reempacotando e importando dados muito antigos (mais antigos que o último ano por exemplo), considere gastar algum tempo extra de CPU e usar a opção --window=50 (ou mais) ao executar o comando git repack. Vai demorar mais, contudo, produzirá pacote de arquivos menores. Você só precisa se esforçar uma vez, e todos os usuários do seu projeto se beneficiarão de um repositório menor.

De vez em quando, faça com que o seu frontend emita uma mensagem de progresso progress para o comando fast-import. O conteúdo das mensagens é totalmente livre, portanto, uma sugestão seria exibir o mês e o ano atual sempre que a data do commit atual passar para o mês seguinte. Os seus usuários se sentirão melhor sabendo quanto do fluxo de dados foi processado.

O fast-import mantém uma estrutura na memória para cada objeto registrado nessa execução. Num sistema com 32 bits, a estrutura é de 32 bytes; num sistema com 64 bits, a estrutura é de 40 bytes (devido ao tamanho maior do ponteiro). Os objetos da tabela não são desalocados até a conclusão do fast-import. A importação de 2 milhões de objetos num sistema com 32 bits exigirá aproximadamente 64 MiB de memória.

A tabela de objetos é, na verdade, uma tabela hash com a chave no nome do objeto (o SHA-1 exclusivo). Essa configuração de armazenamento permite que o fast-import reutilize um objeto já existente ou que já tenha sido gravado e evite gravar duplicatas no pacote de arquivos que for gerado. As bolhas duplicadas são surpreendentemente comuns numa importação, geralmente devido a mesclas das ramificações na origem.

As marcações são armazenadas numa matriz esparsa, usando 1 ponteiro (4 bytes ou 8 bytes, dependendo do tamanho do ponteiro) por marcação. Embora a matriz seja esparsa, os frontends ainda são fortemente incentivados a usar marcações entre 1 e n, onde n é o número total de marcações necessárias para essa importação.

As ramificações são classificadas como ativa e inativa. O uso de memória das duas classes é consideravelmente diferente.

As ramificações inativas são armazenadas numa estrutura que usa 96 ou 120 bytes (nos sistemas com 32 bits ou 64 bits, respectivamente), mais o comprimento do nome da ramificação (normalmente abaixo de 200 bytes), por ramificação. O fast-import processa facilmente até 10.000 ramificações inativas usando menos de 2 MiB de memória.

Os ramos ativos têm a mesma sobrecarga dos ramos inativos, mas também contêm cópias de todas as árvores que foram alteradas recentemente neste ramo. Se a subárvore include não tiver sido alterada desde que a ramificação se tornou ativa, o seu conteúdo não será carregado na memória, mas se a subárvore src tiver sido alterada por um commit desde que a ramificação se tornou ativa, o seu conteúdo será carregado na memória.

À medida que as ramificações ativas armazenam metadados sobre os arquivos existentes nessa ramificação, o tamanho do armazenamento na memória pode aumentar consideravelmente (veja abaixo).

O fast-import move automaticamente as ramificações ativas para a condição inativa com base num algoritmo simples de uso menos recente. A cadeia LRU é atualizada em cada comando commit. A quantidade máxima de ramificações ativas pode ser aumentada ou diminuída na linha de comando com --active-branches=.

As árvores (também conhecidas como diretórios) usam apenas 12 bytes de memória além da memória necessária para as suas respectivas inserções (consulte “por arquivo ativo” abaixo). O custo de uma árvore é praticamente zero, pois a sua sobrecarga é amortizada pelas entradas individuais do arquivo.

Os arquivos (e os ponteiros para as subárvores) dentro das árvores ativas precisam de 52 ou 64 bytes (nas plataformas com 32/64 bits) por entrada. Para economizar espaço, os nomes dos arquivos e árvores são agrupados numa tabela de strings comum, o que permite que o nome do arquivo “Makefile” use apenas 16 bytes (após incluir a sobreposição do cabeçalho da string), independentemente da quantidade de vezes que isso ocorra no projeto.

O LRU do ramo ativo, quando associado ao conjunto da cadeia de caracteres do nome do arquivo e ao carregamento lento das subárvores, permite que a eficiência da importação rápida dos projetos com mais de 2.000 ramificações e mais de 45.114 arquivos num espaço de memória muito limitado (menos de 2,7 MiB por ramo ativo).