9.2 Git e Outros Sistemas - Migrando para o Git

Se você leu a seção anterior sobre o uso do git svn, poderá facilmente usar essas instruções para fazer o git svn clone de um repositório; em seguida, pare de usar o servidor Subversion, dê um push para um novo servidor Git e comece a usá-lo. Se você quiser o histórico, você pode fazer isso o mais rápido que puder extraindo os dados do servidor Subversion (o que pode demorar um pouco).

No entanto, a importação não é perfeita; e como demorará muito, você pode fazer isso da maneira correta. O primeiro problema é a informação do autor. No Subversion, cada pessoa submetida tem um usuário no sistema que é gravado nas informações de commit. Os exemplos na seção anterior mostram schacon em alguns lugares, como a saída blame e o git svn log. Se você deseja mapear isso para obter melhores dados de autor do Git, é necessário um mapeamento dos usuários do Subversion para os autores do Git. Crie um arquivo chamado users.txt que possua esse mapeamento em um formato como este:

Para obter uma lista dos nomes de autores que o SVN usa, você pode executar o seguinte:

Isso gera a saída do log no formato XML, mantém apenas as linhas com informações do autor, descarta duplicatas e retira as tags XML. Obviamente, isso só funciona em uma máquina com o grep, sort e perl instalados. Em seguida, redirecione a saída para o arquivo users.txt, para que você possa adicionar os dados equivalentes do usuário do Git ao lado de cada entrada.

Você pode fornecer esse arquivo ao git svn para ajudá-lo a mapear os dados do autor com mais precisão. Você também pode informar o git svn a não incluir os metadados que o Subversion importa normalmente, passando o --no-metadata para o comando clone ou init. Os metadados incluem um git-svn-id dentro de cada mensagem de commit que o Git irá gerar durante a importação. Isso pode inchar o seu log do Git e torná-lo um pouco incerto.

Isso faz o seu comando de import parecer com isto:

Agora você deve ter uma importação (import) do Subversion melhor em seu diretório my_project. Em vez dos commits que se parecem com isto:

eles se parecem assim:

Não apenas o campo Autor (Author) parece muito melhor, mas o git-svn-id não está mais lá também.

Você também deve fazer um pouco de limpeza pós-importação (post-import cleanup). Por um lado, você deve limpar as referências estranhas que o git svn configurou. Primeiro, você moverá as tags para que sejam de fato tags, em vez de ramificações (branches) remotas estranhas e, em seguida, moverá o restante das filiais para que sejam locais.

Para mover as tags para se tornarem em tags adequadas do Git, execute:

Isso utiliza as referências (refs) que eram filiais (branches) remotas que começavam com refs/remotes/tags/ e as torna verdadeiras tags (mais leves).

Em seguida, mova o restante das referências sob o refs/remotes para que se tornem em ramificações (branches) locais:

Pode acontecer que você veja alguns branches extras com o sufixo @xxx (onde xxx é um número), enquanto no Subversion você vê apenas uma filial. Na verdade, trata-se de um recurso do Subversion chamado “peg-revisions” (revisões vinculadas), que é algo pelo qual o Git simplesmente não possui contrapartida sintática. Por isso, o git svn simplesmente adiciona o número da versão SVN ao nome da branch, da mesma forma que você o escreveria no SVN para abordar a peg-revision daquele branch. Se você não se importa mais com as peg-revisions, simplesmente as remova:

Agora, todos os branches antigos são realmente branches do Git e todas as tags antigas são as do Git.

Há uma última coisa para limpar. Infelizmente, o git svn cria um branch extra chamado trunk, no qual mapeia para a branch padrão do Subversion, mas o trunk aponta ao mesmo lugar que o master. Desde que o master é mais idomaticamente Git, aqui está o modo de como se remover o branch a mais:

A última coisa a fazer é adicionar o seu novo servidor Git como um arquivo remoto e fazer um push a ele. Aqui está um exemplo sobre como adicionar seu servidor como um controle remoto:

Como você deseja que todas os seus branches e tags se levantem, agora você pode executar isso:

Todos as suas filiais (branches) e tags devem estar no seu novo servidor Git em uma importação limpa e agradável.

Uma vez que o Mercurial e o Git têm modelos bastante parecidos para a representação de versões, e visto que o Git é um pouco mais flexível, converter de um repositório no Mercurial para o Git é bem simples, utilizando-se a ferramenta chamada "hg-fast-export", da qual você precisará uma cópia:

O primeiro passo para a conversão é efetuar um clone por completo do repositório no Mercurial a que se queira converter:

O próximo passo é a criação de um arquivo para o mapeamento dos autores. O Mercurial é mais tolerante do que o Git em virtude do que colocará no campo dos autores em relação aos conjuntos de alterações (changesets); sendo assim, essa é a hora de limpar a casa. A geração dele é na base de um comando de linha única no shell do bash:

Isto deve levar alguns segundos, a depender em quão longo seja a história do seu projeto, e logo após, o arquivo /tmp/authors se parecerá com algo do tipo:

Nesse exemplo, a mesma pessoa (Bob) criou os changesets com quatro nomes diferentes, com o qual somente um deles pareça correto, e onde um deles seja completamente inválido por um commit no Git. A hg-fast-export nos permite consertar a fazer com que cada linha se torne uma regra: "<input>"="<output>", ao mapear um <input> em favor de um <output>. Dentro das sequências de strings (strings) <input> e <output>, todas as saídas das sequências codificadas do string_escape no Python são suportadas. Se o arquivo de mapeamento do autor não conter uma correspondência com o <input>, o mesmo autor será enviado ao Git sem sofrer as alterações. Se todos os nomes dos usuários parecem bem, não será necessário a sua presença num arquivo para eles em momento nenhum. No exemplo, nós queremos que o nosso arquivo pareça assim:

O mesmo tipo do arquivo de mapeamento pode ser usado na renomeação dos branches e das tags quando o nome no Mercurial não for permitido pelo Git.

O próximo passo é criar o nosso novo repositório no Git e rodar o script de exportação:

A bandeira (flag) -r diz ao hg-fast-export onde encontrar o repositório do Mercurial que desejamos converter, e a bandeira -A nos diz onde encontrar o arquivo para os mapeamentos de autoria (os arquivos de mapeamentos das branches e das tags são especificados com as flags -B e -T, respectivamente). O script faz a análise sintática (parses) aos changesets do Mercurial e os converte em um script voltado para o recurso do Git, "fast-import" (do qual discutiremos detalhadamente mais à frente). Isto toma um pouco do seu tempo (apesar de ser muito mais rápido do que numa base em rede (network)), e a saída (output) costuma ser muito prolixa:

É quase tudo o que há nisto. Todas as tags do Mercurial foram convertidas para as tags do Git, e as filiais (branches) e os favoritos (bookmarks) do Mercurial foram convertidos para as branches do Git. Agora você se encontra pronto para subir o seu repositório num push no lado dos servidores da sua casa (server-side home):

O próximo sistema ao qual você abordará para importações é o Perforce. Conforme o que foi discutido anteriormente, existem duas maneiras das quais se possa fazer com que o Git e o Perforce conversem um com o outro: git-p4 e o Perforce Git Fusion.

Se o seu sistema não estiver entre nenhum dos listados acima, você deve procurar por um importador de forma online - os importadores de qualidade estão disponíveis em muitos outros sistemas, incluindo os de CVS, Clear Case, Visual Source Safe e até mesmo o diretório de arquivos. Se nenhuma dessas ferramentas funcionar para você, se você tiver uma ferramenta mais obscura ou se precisar de um processo de importação mais personalizado, use o git fast-import. O comando em questão ler as simples instruções do stdin ao escrever na especificação de dados do Git. Nesta maneira, criar objetos no Git é muito mais fácil do que se você estivesse rodando os comandos no Git em formatos crus, ou no caso da tentativa em redigir aos objetos neste mesmo formato (confira o Git Internals (Por Dentro do Git) para mais informações). Neste sentido, você pode escrever o script de um importador que ler as informações necessárias do lado de fora do sistema no qual você fará a importação, e fará a impressão sem rodeios das informações para o stdout. Em seguida, você pode executar esse programa e encaminhar sua saída para o git fast-import por meio de um pipe.

Para demonstrarmos mais rápido, você redigirá um importador simples. Suponha que você trabalhe em current, faça backups ocasionais do projeto copiando o diretório para um diretório de backup com data no formato back_YYYY_MM_DD e queira importar esse conteúdo para o Git. A estrutura do seu diretório se assemelha com isto:

Ao se importar um diretório no Git, você terá de fazer as revisões na maneira de como o Git guarda a base dos seus dados. Como você deve se lembrar, o Git é fundamentalmente uma lista encadeada de objetos commit que apontam para um snapshot do conteúdo. Tudo o que se deve fazer é contar ao fast-import que tipo de conteúdo os snapshots são, quais dados de commits lhes direcionam, e na ordem aos quais neles entram. Sua estratégia deve ser seguir pelos snapshots a um nível de cada vez, e criar os seus commits pelo conteúdo em cada um de seus diretórios, se ligando em todo e cada submetimento de volta ao de modo antecedente.

Assim como fizemos no Uma Política de Exemplo Imposta pelo Git, nós redigiremos isso em Ruby, já que este é pelo qual trabalhamos no modo geral, bem como tem a tendência em possuir uma leitura mais fácil. Você pode redigir a este exemplo de uma maneira muito simples sobre qualquer coisa na qual possua maior familiaridade – isto só necessita de sua impressão das devidas informações em prol do stdout. Se estiver usando o Windows, isso significa que você deverá tomar um cuidado especial para não inserir retornos de carro no final das linhas – o git fast-import exige apenas avanços de linha (LF), e não a combinação de retorno de carro e avanço de linha (CRLF) usada pelo Windows.

Para começar, entre no diretório de destino e identifique cada subdiretório; cada um deles é um snapshot que você deseja importar como um commit. Você fará a troca por entre cada um dos subdiretórios e imprimir os comandos que sejam necessários à finalidade de os exportar. O laço principal básico será semelhante a este:

Você executa print_export dentro de cada diretório; o método recebe o manifesto e a marca do snapshot anterior e retorna o manifesto e a marca do snapshot atual, permitindo encadeá-los corretamente. “Mark” é o termo usado pelo fast-import para um identificador atribuído a um commit; conforme cria os commits, você atribui uma marca a cada um deles para poder referenciá-lo a partir de outros commits. Assim, a primeira coisa que deva ser feita no seu método de print_export é gerar uma marca advinda do nome de seus diretórios:

Você fará isso criando um array de diretórios e usando o valor do índice como marca, pois uma marca precisa ser um número inteiro. Seu método tem a aparência de:

Agora que você tem uma representação inteira do commit, precisa de uma data para os metadados dele. Como a data está expressa no nome do diretório, você fará sua análise sintática. A linha seguinte no seu arquivo em print_export será:

onde convert_dir_to_date (converter diretório para data) se defina a partir de:

Isso retorna um valor inteiro para a data de cada diretório. A última metainformação necessária para cada commit são os dados do autor do commit, definidos diretamente em uma variável global:

Agora você está pronto para começar a imprimir os dados de commit para o importador. As informações iniciais indicam que você está definindo um objeto commit e em qual branch ele se encontra, seguidas pela marca gerada, pelos dados e pela mensagem do autor do commit e, por fim, pelo commit anterior, se houver. Os códigos tendem a ter essa visualização:

Você define diretamente o fuso horário (-0700), pois isso é simples. Se estiver importando de outro sistema, deverá especificar o fuso horário como um deslocamento. As mensagens dos envios têm de se expressar por um formato em especial:

O formato consiste na palavra data, no tamanho dos dados que serão lidos, em uma quebra de linha e, por fim, nos dados. Como mais adiante você precisará usar o mesmo formato para especificar o conteúdo dos arquivos, crie um método auxiliar, export_data:

Resta apenas especificar o conteúdo dos arquivos de cada snapshot. Isso é fácil, pois cada snapshot está em um diretório – você pode imprimir o comando deleteall, seguido pelo conteúdo de cada arquivo do diretório. O Git logo fará as gravações de cada snapshot da maneira em que se julgar como sendo a mais apropriada:

Observação: Como muitos sistemas tratam suas revisões como alterações de um commit para outro, o fast-import também aceita, em cada commit, comandos que especificam quais arquivos foram adicionados, removidos ou modificados e qual é o novo conteúdo. Você poderia calcular as diferenças entre os snapshots e fornecer apenas esses dados, mas isso é mais complexo – é mais simples fornecer todos os dados ao Git e deixar que ele descubra as diferenças. Se essa abordagem for mais adequada aos seus dados, consulte a página de manual do fast-import para saber como fornecê-los dessa maneira.

O formato para listar o conteúdo de um novo arquivo ou especificar um arquivo modificado com seu novo conteúdo é o seguinte:

Aqui, 644 é o modo (se houver arquivos executáveis, você precisará detectá-los e especificar 755), e inline indica que o conteúdo será listado imediatamente depois dessa linha. O seu método em conformidade do inline_data deve remeter num teor destas bases:

Você reutiliza o método export_data definido anteriormente, pois o formato é o mesmo usado para especificar os dados da mensagem de commit.

Por último, você precisa retornar a marca atual para que ela possa ser passada à próxima iteração:

Isto é tudo. Este é o script completo:

Se você executar esse script, obterá um conteúdo semelhante a este:

Para executar o importador, estando no diretório Git para o qual você deseja importar, encaminhe essa saída para o git fast-import por meio de um pipe. Como ponto de partida, você pode criar um diretório, executar git init nele e depois executar seu script:

Como você pode ver, quando a execução é concluída com sucesso, o programa apresenta várias estatísticas sobre o que realizou. Nesse caso, você importou um total de 13 objetos de 4 commits para 1 branch. Agora, execute git log para ver seu novo histórico:

Pronto: um repositório Git organizado e limpo. É importante observar que nenhum checkout foi feito – inicialmente, não há nenhum arquivo no seu diretório de trabalho. De se obtê-las, a obrigação será de fato às restaurações da forma contida no branch da onde a master se situa neste respectivo momento:

Você pode fazer muito mais com a ferramenta fast-import: lidar com modos diferentes, dados binários, várias branches e merges, tags, indicadores de progresso e muito mais. Há diversos exemplos de cenários mais complexos no diretório contrib/fast-import do código-fonte do Git.