Para ajudar na depuração de front-ends, o fast-import ignora qualquer linha que comece com # (ASCII libra/hash) até, e incluindo, a linha que termina com LF. Uma linha de comentário pode conter qualquer sequência de bytes que não contenha um LF e, portanto, pode ser utilizado 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 do fast-import.

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

O fast-import aceita vários comandos para atualizar o repositório atual e controlar o processo de importação. Discussões mais detalhadas (com exemplos) de cada comando virão depois.

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

onde <ref> é o nome do ramo no qual o commit deve ser feito. Normalmente, os nomes dos ramos são prefixados com refs/heads/ no Git, portanto, a importação do símbolo do ramo CVS RELENG-1_0 utilizaria refs/heads/RELENG-1_0 como o valor de <ref>. O valor de <ref> deve ser um "refname" válido no Git. Como LF não é válido em um "refname" do Git, nenhuma sintaxe de aspas ou de escape é compatível aqui.

Um comando de marcação mark pode aparecer opcionalmente, solicitando ao fast-import para salvar uma referência ao commit recém-criado para uso futuro através do front-end (veja abaixo). É muito comum que os front-ends marquem cada commit criado, permitindo assim a criação futura de ramificações a partir de qualquer commit importado.

O comando data após o committer deve suprir a mensagem do commit (veja abaixo a sintaxe do comando data). Para importar uma mensagem vazia de commit, utilize os dados com 0 de comprimento. As mensagens do commit são de livre formato e não são interpretadas pelo Git. Atualmente, elas devem ser codificadas em UTF-8, pois o fast-import não permite que outras codificações sejam utilizadas.

Zero ou mais comandos como filemodify, filedelete, filecopy, filerename, filedeleteall e notemodify podem ser incluídos para atualizar o conteúdo do ramo antes de criar o commit. Estes comandos podem ser utilizados em qualquer ordem. No entanto, é recomendado que um comando filedeleteall preceda todos os comandos filemodify, filecopy, filerename e notemodify no mesmo commit, já que filedeleteall limpa a ramificação (veja abaixo).

O LF após o comando é opcional (costumava ser obrigatório). Observe que por razões de retrocompatibilidade, caso o commit termine com um comando data (ou seja, não tiver nenhum comando from, merge, filemodify, filedelete, filecopy, filerename, filedeleteall ou notemodify) então dois comandos LF podem aparecer no final do comando em vez de apenas um.

Organiza fast-import para salvar uma referência ao objeto atual, permitindo que o front-end recupere este objeto em um momento futuro, sem conhecer o seu SHA-1. Aqui, o objeto atual é o comando de criação do objeto no qual o comando mark aparece. 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 ASCII decimal inteiro. O valor 0 é reservado e não pode ser utilizado como uma marcação. Somente os valores maiores ou iguais a 1 podem ser utilizados como marcação.

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

Fornece o nome do objeto no sistema de controle de origem original. o fast-import simplesmente ignorará esta diretiva, porém os processos de filtro que operam e modificam o fluxo antes de alimentar o fast-import podem ter usos para essas informações

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

Cria uma tag anotada referente a um commit específico. Para criar tags leve (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 um refname válido no Git e portanto, pode conter barras. Como LF não é válido em um "refname" do Git, nenhuma sintaxe de aspas ou de escape é compatível aqui.

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 após o tagger deve fornecer a mensagem anotada do tag (veja abaixo a sintaxe do comando data). Para importar uma mensagem de tag vazia, utilize dados com 0 de comprimento. As mensagens de tag são de forma livre e não são interpretados pelo Git. Atualmente, elas devem ser codificadas em UTF-8, pois o fast-import não permite que outras codificações sejam utilizadas.

A assinatura de tags anotadas durante a importação com fast-import não é compatível. Não é recomendável tentar incluir na sua própria assinatura PGP/GPG, pois o front-end não tem (facilmente) acesso ao conjunto completo de bytes que normalmente entra nessa assinatura. Caso a assinatura seja necessária, crie tags leve a partir do fast-import com reset e crie as versões anotadas dessas tags desconectadas com o processo predefinido git tag.

Cria (ou recria) a ramificação nomeada, iniciando opcionalmente a partir de uma revisão específica. O comando reset permite que um front-end emita um novo comando `from para uma ramificação 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 utilizado para criar tags leves (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 do arquivo no pacote do arquivo. A revisão não está conectada a nenhum commit; essa conexão deve ser formada com um comando commit subsequente referenciando a bolha através de uma marcação atribuída.

O comando mark é opcional aqui, pois alguns front-ends optaram por gerar o SHA-1 do Git para a bolha por conta própria e alimentá-la diretamente para o commit. No entanto, normalmente é mais trabalhoso do que vale a pena, pois as marcas são baratas de armazenar e fáceis de usar.

Fornece os dados brutos (para uso como o conteúdo bolha/arquivo, as mensagens do commit ou as mensagens de anotação das tags) para o fast-import. Os dados podem ser informados utilizando uma contagem exata de bytes ou delimitados por uma linha final. Os front-ends reais destinados para conversões de qualidade de produção devem sempre usar o formato exato de contagem de bytes, pois são mais robustos e têm um melhor desempenho. O formato delimitado destina-se principalmente ao teste de importação rápida.

As linhas de comentário que aparecem na parte <raw> dos comandos data sempre são consideradas parte do corpo dos dados e portanto, nunca são ignoradas pelo fast-import. Isso torna seguro importar qualquer conteúdo do 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 o fast-import alterna automaticamente os arquivos do pacote quando o arquivo do pacote atual alcance --max-pack-size ou 4 GiB, o que for menor. Durante uma troca automática do pacote de arquivos fast-import não atualiza os `refs, tags ou 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-end podem optar por emitir checkpoints durante as importações extremamente grandes e de execução demorada, ou quando precisam permitir que outro processo do Git acesse uma ramificação. No entanto, dado que um repositório do Subversion com 30 GiB pode ser carregado no Git através do fast-import em cerca de 3 horas, talvez não seja necessário um checkpoint explícito.

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

Faz com que o fast-import imprima toda a linha progress sem modificação em seu canal de saída predefinido (descritor do arquivo 1) quando o comando é processado a partir do fluxo de entrada. Caso contrário, o comando não tem impacto na importação atual ou em qualquer outro estado interno do fast-import.

A parte <any> do comando pode conter qualquer sequência de bytes que não contenha um LF. O LF após o comando é opcional. Os chamadores podem desejar processar a saída por meio de uma ferramenta como sed para remover a parte principal 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 o fast-import imprima uma bolha em um descritor do arquivo previamente organizado com o argumento --cat-blob-fd. Caso contrário, o comando não tem impacto na importação atual; o seu principal objetivo é recuperar as bolhas que podem estar na memória do fast-import, mas não acessíveis no 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 pronto para ser gravado.

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

Este comando pode ser usado onde uma diretiva filemodify possa aparecer, permitindo que ela seja usada no meio de um commit. Para um filemodify usando uma diretiva inline, ele também pode aparecer logo antes da diretiva data.

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

Imprime as informações sobre o objeto em um caminho para um descritor do arquivo organizado anteriormente com a opção --cat-blob-fd. Permite a impressão de uma bolha a partir do commit ativo (com cat-blob) ou copiando uma bolha ou árvore de um commit anterior para uso 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 utilizada para que o fast-import do git se comporte de maneira que atenda às necessidades do front-end. Observe que as opções utilizadas pelo front-end são substituídas por quaisquer opções que o usuário possa especificar para obter o próprio 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 o EOF fosse lido. Isso pode ser utilizado para dizer à importação rápida para terminar 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 de repositório, utilize uma marcação única por commit (mark :<n>) e forneça a opção --export-marks na linha de comando. O fast-import despeja um arquivo que lista todas as marcações e o objeto Git SHA-1 que coincida com ela. Se o front-end puder vincular as marcações ao repositório de origem, é fácil verificar a precisão e a integridade da importação comparando cada commit do Git com a revisão de origem coincidente.

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 tente otimizar o front-end para manter uma ramificação por vez durante uma importação. Embora isso possa ser um pouco mais rápido para o fast-import, ele tende a aumentar consideravelmente a complexidade do código do front-end.

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, simplesmente exclua os nomes antigos e modifique os novos nomes durante o commit correspondente. O Git executa a detecção de renomeação após o fato, em vez de explicitamente detectá-lo durante um commit.

Alguns outros sistemas SCM permitem ao usuário criar uma tag a partir de vários arquivos que não pertencem ao mesmo commit/changeset. Ou para criar as tags que são um subconjunto dos arquivos disponíveis no repositório.

A importação dessas tags como está no Git é impossível sem qe seja feito pelo menos um commit que “corrija” os arquivos para coincidir com o conteúdo da tag. Utilize o comando reset do fast-import para redefinir uma ramificação fantasia fora do seu ramo normal para um commit base para a tag, depois confirme um ou mais correções dos arquivos de commits e por fim, identifique a ramificação fantasia.

Uma vez que todas as ramificações normais são armazenadas em refs/heads/, nomeie a tag de manutenção como TAG_FIXUP por exemplo. Dessa forma, é impossível que a ramificação de correção utilizada pelo importador tenha os conflitos do espaço de nomes com as ramificações reais importadas da origem (o nome TAG_FIXUP não é refs/heads/TAG_FIXUP).

Ao fazer os commits das correções, considere o uso de merge para conectar os commits para fornecer as revisões dos arquivos ao ramo de correção. Isso permitirá que ferramentas como o git blame rastreiem o histórico real do commit e anotem adequadamente 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.

Logo que o fast-import conclua, o repositório Git estará completamente válido e pronto para uso. Normalmente, o processo consome muito pouco tempo, mesmo para projetos consideravelmente grandes (com mais de 100.000 commits).

No entanto, é necessário reembalar o repositório para melhorar a localidade dos dados e melhorar o desempenho. Projetos extremamente grandes pode levar horas (especialmente se -f e um parâmetro --window grande for utilizado). Como a reembalagem é segura para ser executada ao lado de leitores e escritores, execute a re-embalagem em segundo plano e deixe acabar quando finalizar. Não há motivo para esperar a exploração do seu novo projeto Git!

Caso opte por aguardar o reembalo, não tente executar benchmarks ou testes de desempenho até que o processo termine. o fast-import gera arquivos de pacotes otimizados que simplesmente nunca são vistos em situações de uso real.

Se você estiver reembalando dados importados muito antigos (por exemplo, mais antigos que no ano passado), considere gastar algum tempo extra da CPU e fornecer --window = 50 (ou superior) ao executar o git repack. Isso levará mais tempo, mas também produzirá um pacote menor. Você só precisa perder tempo uma vez e todos os usuários do seu projeto se beneficiarão do repositório menor.

Para importar rapidamente, de vez em quando o seu front-end emite uma mensagem de progresso. O conteúdo das mensagens é totalmente livre, portanto, uma sugestão seria gerar a informação do mês e o ano atual cada vez que a data do commit atual passar para o próximo mês. Os seus usuários se sentirão melhor ao saber quanto do fluxo de dados foi processado.

O fast-import mantém uma estrutura na memória para todos os objetos gravados nesta execução. Em um sistema de 32 bits a estrutura é de 32 bytes; em um sistema de 64 bits a estrutura é de 40 bytes (devido aos tamanhos maiores do ponteiro). Os objetos na tabela não são desalocados até que o fast-import termine. A importação de 2 milhões de objetos em um sistema de 32 bits exigirá aproximadamente 64 MiB de memória.

A tabela de objetos é na verdade uma "hashtable" (tabela hash) codificada no nome do objeto com o SHA-1. Essa configuração de armazenamento permite que o fast-import reutilize um objeto existente ou já gravado e evite gravar duplicatas no saída do arquivo de pacote. Em uma importação, as bolhas duplicadas são muito comuns, geralmente devido a mesclagem do ramo na origem.

As marcações são armazenadas em uma origem esparsa, utilizando 1 ponteiro (4 bytes ou 8 bytes, dependendo do tamanho do ponteiro) por marcação. Embora a origem seja escassa, os front-end ainda são fortemente incentivados a usar marcas entre 1 e n, onde n é a quantidade total de marcações necessárias para essa importação.

Os ramos são classificados como ativos e inativos. O uso de memória das duas classes é significativamente diferente.

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

As ramificações ativas têm a mesma sobrecarga das ramificações inativas, mas também contêm as cópias de todas as árvores que foram modificadas recentemente nesta ramificação. Se a subárvore include não tenha sido modificada, desde o momento que a ramificação se tornou ativa, o seu conteúdo não será carregado na memória, mas o seu conteúdo será carregado na memória caso a subárvore src tenha sido modificada por um commit.

À 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).

Com base num algoritmo simples, o fast-import move automaticamente as ramificações ativas para a condição inativa utilizando um algorítimo simples. A cadeia LRU é atualizada a cada comando commit. A quantidade máxima de ramificações ativas pode se aumentado ou diminuído na linha de comando com a opção --active-branches=.

As árvores (também conhecidas como diretórios) usam apenas 12 bytes de memória no topo da memória necessária para as suas entradas (consulte “por arquivo ativo” abaixo). O custo de uma árvore é praticamente 0, pois sua sobrecarga é amortizada pelas entradas de arquivo individuais.

Os arquivos (e os ponteiros para as subárvores) nas árvores ativas requerem 52 ou 64 bytes (plataformas de 32/64 bits) por entrada. Para economizar espaço, os nomes dos arquivos e as árvores são agrupados em uma tabela de cadeias comuns, permitindo que o nome do arquivo “Makefile” utilize apenas 16 bytes (depois de incluir a sobrecarga do cabeçalho da cadeia), não importa quantas vezes 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 em um espaço de memória muito limitado (menos de 2,7 MiB por ramo ativo).