git-svn - Operação bidirecional entre um repositório do Subversion e o Git

git svn é um canal simples para os conjuntos das alterações entre o Subversion e o Git. Ele fornece um fluxo bidirecional das alterações entre um Subversion e um repositório Git.

O git svn pode monitorar um repositório Subversion padrão, seguindo o layout comum "trunk/branches/tags", com a opção --stdlayout. Ele também pode seguir as ramificações e as tags em qualquer layout com as opções -T/-t/-b (consulte as opções para init abaixo e também para o comando clone).

Depois de monitorar um repositório Subversion (com qualquer um dos métodos acima), o repositório Git pode ser atualizado no Subversion através do comando fetch e o Subversion atualizado no Git através do comando dcommit.

Como as opções noMetadata, rewriteRoot, rewriteUUID, useSvnsyncProps e useSvmProps afetam os metadados gerados e usados pelo comando git svn; eles devem ser definidos no arquivo de configuração antes que qualquer histórico seja importado e estas configurações nunca devem ser alteradas depois que forem definidas.

Além disso, apenas uma destas opções podem ser utilizadas por uma seção svn-remote porque elas afetam a linha de metadados git-svn-id:, exceto para rewriteRoot e rewriteUUID, que podem ser utilizadas juntas.

Monitorando e contribuindo para o trunk de um projeto gerenciado pelo Subversion (ignorando as tags e as ramificações):

Monitorando e contribuindo para todo um projeto gerenciado pelo Subversion (completo com um trunk, tags e ramificações):

O comando git svn clone inicial pode consumir bastante tempo (especialmente para grandes repositórios Subversion). Caso várias pessoas (ou uma pessoa com várias máquinas) quiserem usar o comando git svn para interagir com o mesmo repositório do Subversion, você poderá executar o comando git svn clone inicial em um repositório em um servidor e fazer com que cada pessoa clone esse repositório com o comando clone git:

Prefira usar o comando git svn rebase ou o git rebase, em vez do comando git pull ou o git merge para sincronizar os commits que não foram integrados a um ramo com git svn. Isso manterá o histórico linear dos commits não integrados em relação ao repositório SVN upstream e permitirá a utilização do subcomando git svn dcommit preferido para impulsionar os commits que não foram integrados de volta ao SVN.

Originalmente, o comando git svn recomendava que os desenvolvedores extraíssem ou mesclassem o ramo git svn. Isso ocorreu porque o autor favoreceu o git svn set tree B para o commit um único cabeçalho, em vez da notação git svn set-tree A..B para fazer o commit de vários commits. O uso do comando git pull ou do git merge com o git svn set tree A..B fará com que o histórico não linear seja achatado ao fazer o commit no SVN e isso pode levar a uma mesclagem dos commits, revertendo de forma inesperada os commits anteriores no SVN.

Embora o git svn possa monitorar a cópia do histórico (incluindo as ramificações e as tags) dos repositórios que adotam um layout padrão, ele ainda não pode representar o histórico da mesclagem que ocorreu dentro do git de volta para os usuários do SVN. Portanto, é recomendável que os usuários mantenham o histórico o mais linear possível dentro do Git para facilitar a compatibilidade com o SVN (consulte a seção RESSALVAS abaixo).

Caso o git svn estiver configurado para buscar as ramificações (e a opção --follow-branches estiver em vigor), às vezes ele criará várias ramificações Git para um ramo SVN, onde as ramificações adicionais terão nomes no formato nomedoramo@nnn (onde nnn é o número de revisão SVN). Estas ramificações adicionais são criadas caso o comando git svn não puder encontrar um commit parente para o primeiro commit em um ramo SVN, para conectar o ramo ao histórico das outras ramificações.

Normalmente, o primeiro commit em um ramo SVN consiste em uma operação de cópia. o git svn irá ler este commit obtendo a revisão SVN onde o ramo foi criado. Ele tentará encontrar o commit do Git que coincida com esta revisão do SVN e vai usá-lo como o parente do ramo. Contudo, é possível que não haja um commit Git adequado para servir como parente. Isso acontecerá, dentre outros motivos, caso o ramo SVN seja uma cópia de uma revisão que não foi buscada pelo git svn (como por exemplo, porque é uma revisão antiga que foi ignorada com a opção --revision), ou no caso do SVN ter sido copiado de um diretório que não é monitorado pelo git svn (como um ramo que não é monitorado de maneira alguma ou um subdiretório de um ramo monitorado). Nesses casos, o comando git svn ainda criará um ramo Git, porém, em vez de utilizar um commit Git já existente como parente do ramo, ele lerá o histórico SVN do diretório onde o ramo foi copiado e criará os commits Git apropriadas. Isto é indicado através da mensagem "Initializing parent: <nome-do-ramo>" (Inicializando parente: <nomedoramo>).

Além disso, ele criará um ramo especial chamado <nome-do-ramo>@<SVN-Revision>, onde <Revisão SVN> é o número da revisão do SVN onde o ramo foi copiado. Este ramo apontará para o commit da origem recém-criado do ramo. Se no SVN o ramo foi excluído e posteriormente recriado a partir de uma versão diferente, haverá vários ramos com um @.

Observe que isso pode significar que vários commits do Git sejam criados para uma única revisão do SVN.

Um exemplo: em um repositório SVN com um layout predefinido de trunk/tags/branches, um diretório trunk/sub é criado na r.100. Em r.200, o trunk/sub é ramificado ao copiá-lo para branches/. O comando git svn clone -s criará um ramo sub. Ele também criará novos commits do Git para r.100 até r.199 e os utilizará como o histórico do ramo sub. Portanto, haverá dois commits do Git para cada revisão de r.100 até r.199 (um contendo trunk/, outro contendo trunk/sub/). Finalmente será criado o ramo sub@200 apontando para o novo commit parente do ramo sub (o commit para r.200 e o trunk/sub/ por exemplo).

Por uma questão de simplicidade e interoperação com o Subversion, é recomendável que todos os usuários do git svn clonem, busquem e desfaçam um commit diretamente no servidor SVN e evitem todas as operações dos comandos git clone/pull/merge/push entre os repositórios e as ramificações do Git. O método recomendado da troca do código entre os ramos e os usuários do Git é git format-patch e git am, ou apenas desfazendo o commit com dcommit no repositório SVN.

Executar o comando git merge ou o git pull NÃO é recomendado em um ramo onde você planeja fazer um dcommit, porque os usuários do Subversion não podem ver nenhuma mesclagem que você tenha feito. Além disso, caso você mescle ou extraia de um ramo Git que seja um espelho de um ramo SVN, o dcommit poderá fazer o commit do ramo errado.

Caso você mescle, observe a seguinte regra: o git svn dcommit tentará fazer o commit sobre o commit do SVN informado em

Você deve garantir, portanto, que o commit mais recente do ramo que você queira fazer o commit seja o primeiro pai da mesclagem. O caos ocorrerá de outra forma, especialmente caso o primeiro pai seja um commit mais antigo no mesmo ramo SVN.

O comando git clone não clona as ramificações sob a hierarquia refs/remotes/, qualquer metadado git svn ou configuração. Portanto, os repositórios criados e gerenciados com a utilização do git svn devem utilizar o rsync para a clonagem, caso a clonagem precise ser feita.

Como o dcommit usa o rebase internamente, qualquer ramificação do Git para onde você fez o comando git push antes do dcommit exigirá uma reposição da "ref" existente no repositório remoto. Isso geralmente é considerado uma má prática, consulte a documentação do git-push[1] para obter mais detalhes.

Não utilize a opção --amend do git-commit[1] nas alterações que você já tenha desfeito no commit. Não é considerado uma boa prática utilizar a opção --amend nos commits que você já impulsionou para um repositório remoto para outros usuários, desfazer o commit com SVN é análogo a isto.

Ao clonar um repositório SVN, caso nenhuma das opções para descrever o layout do repositório seja usada (--trunk, --tags, --branches, --stdlayout), o comando git svn clone criará um repositório Git com o histórico completamente linear, onde as ramificações e as tags aparecerão como diretórios separados na cópia de trabalho. Embora essa seja a maneira mais fácil de se obter uma cópia de um repositório completo, para os projetos com muitas ramificações, ela resultará em uma cópia de trabalho muitas vezes maior do que apenas o trunk. Portanto, para os projetos que utilizem a estrutura predefinida dos diretórios (trunk/branches/tags), é recomendável clonar com a opção --stdlayout. Caso o projeto use uma estrutura fora do padrão e/ou caso as ramificações e as tags não forem necessárias, é mais fácil clonar um diretório (normalmente o trunk), sem fornecer as opções do layout do repositório. Caso o histórico completo das ramificações e das tags seja necessário, as opções --trunk / --branches / --tags devem ser usadas.

Quando utilizar vários --branches ou --tags, o comando git svn não lida com as colisões dos nomes de forma automática (caso dois ramos com caminhos diferentes tiverem o mesmo nome ou caso um ramo e uma marcação tiverem o mesmo nome por exemplo). Nestes casos, utilize init para configurar o seu repositório Git antes do seu primeiro fetch, edite o arquivo $GIT_DIR/config para que as ramificações e as tags sejam associadas com diferentes espaços de nome. Por exemplo:

Ignoramos todas as propriedades SVN, exceto o svn:executable. Quaisquer propriedades não manipuladas são registradas no $GIT_DIR/svn/<refname>/unhandled.log

Os diretórios renomeados e copiados não são detectados pelo Git e portanto, não são monitorados ao fazer o commit com o SVN. Não pretendo adicionar suporte para isso, pois é bastante difícil e demorado trabalhar para todos os casos possíveis (o Git também não faz isso). Fazer o commit dos arquivos renomeados e copiados é totalmente compatível caso eles sejam semelhantes o suficiente para que o Git os detecte.

No SVN, é possível (embora desencorajado) fazer o commit nas alterações em uma tag (porque uma tag é apenas uma cópia do diretório, portanto tecnicamente o mesmo que um ramo). Ao clonar um repositório SVN, o comando git svn não pode saber se tal commit com uma tag ocorrerá no futuro. Portanto, ele age de maneira conservadora e importa todas as tags SVN como ramificações, prefixando o nome da tag com tags/.

O git svn armazena as informações de configuração [svn-remote] no arquivo $GIT_DIR/config do repositório. É semelhante às seções principais do Git [remote], exceto que as teclas fetch não aceitam os argumentos globais; porém eles são manipulados pelas teclas branches e tags. Como alguns repositórios SVN são configurados de forma estranha com vários projetos, as expansões globais são permitidas, como as listadas abaixo:

Lembre-se que o curinga * (asterisco) da referência local (à direita do :) deve ser o componente mais distante do caminho à direita; no entanto, o curinga remoto pode estar em qualquer lugar, desde que seja um componente independente do caminho (cercado por / ou EOL (um caractere que indica o final da linha)). Este tipo de configuração não é criado de forma automática pelo init e deve ser inserido manualmente com um editor de texto ou utilizando o comando git config.

Observe também que apenas um asterisco é permitido por palavra. Por exemplo:

corresponderá às ramificações release, rese, re123se, no entanto

irá produzir um erro.

Também é possível capturar um subconjunto de ramos ou tags utilizando uma lista com os nomes separados por vírgulas dentro de colchetes. Por exemplo:

São compatíveis várias chaves de captura, ramificações e tags:

A criação de uma ramificação nessa configuração requer desambiguar qual o local usar com a flag -d ou --destination:

Observe que o git-svn acompanha a revisão mais alta onde um ramo ou uma tag tenha aparecido. Caso o subconjunto das ramificações ou das tags seja alterada após a busca, então $GIT_DIR/svn/.metadata deverá ser editado manualmente para remover (ou redefinir) branches-maxRev e/ou tags-maxRev, conforme seja apropriado.

git-rebase[1]

Parte do conjunto git[1]