Projects/MoveToGit/UsingSvn2Git (pt BR)
This page documents how to go about getting a KDE module ready for the Great Git Migration of 2010.
Servidores para todos os desenvolvedores
KDE Sysadmin dispõe de 3 servidores que estão configurados para escrever regras. Você pode encontrar mais informações sobre isso em: http://community.kde.org/Sysadmin/DeveloperAccessForRuleWriting.
Todos os desenvolvedores do KDE registados têm acesso a essas máquinas. O restante deste documento assume uma configuração no seu computador local, você está livre para configurá-lo em seu computador local, mas não há nenhuma necessidade. Você pode usar os servidores fornecidos pelo KDE Sysadmin.
Obtendo as ferramentas
As ferramentas necessárias estão hospedadas na http://www.gitorious.org/svn2git. Para começar, faça:
git clone git://gitorious.org/svn2git/svn2git.git
git clone git://git.kde.org/kde-ruleset.git
Então instale o pacote libsvn-dev.
Isso vai te dar o código-fonte para dar um build no svn2git e nos arquivos de conjunto de regras do KDE como ele estão atualmente. Dê um build na ferramenta svn2git antes de passar para a próxima etapa.
Building svn2git
Verifique se você tem Qt4 instalado, então use os comandos qmake && make para dar um no build the executável chamado "svn-all-fast-export"
Como o conjuntos de regras funcionam
O formato das regras svn2git é bastante simples. Em primeiro lugar você tem que declarar alguns repositórios:
create repository kdelibs end repository
Isto diz svn2git que deve criar um repositório git chamado "kdelibs" que mais tarde, podemos usar para dar commits nele.
O resto do arquivo são regras de correspondência para patches específicos no Subversion, cada regra especifica o que fazer com o commit que aparecer no path especificado. As possíveis ações possíveis são ignorá-los ou adicioná-las a uma determinado branch ou a um repositório específico. Nota: Ignorar é feito simplesmente por deixar de fora as informações sobre o repositório e do branch.
Como exemplos são mais explicativos, a regra a seguir coloca todos os commits do 123453 até 456789 do path / trunk / KDE / kdelibs para o branch master do kdelibs:
match /trunk/KDE/kdelibs/ min revision 123453 max revision 456789 repository kdelibs branch master end match
A revisão min e max são úteis nos casos em que o mesmo path no SVN contém código para diferentes branchs. Um exemplo seria KDevelop3, onde 3,3 KDevelop foi colocado com o KDE 3.5 até 3.5.7, 3.5.8 contendo KDevelop 3.4 e 3.5.9 contendo KDevelop 3.5 e todas as versões do kdevelop agora estão sob a / branches/KDE/3.5/kdevelop.
Os dois parâmetros de revisão não são obrigatórios, se eles são deixados de fora, então todas os commits para o path dado no SVN são retomadas no branch especificada.
Para gerar tags com o git você usa um formato especial para o parâmetro do branch: refs / tags / <tagname>. Então, para colocar todos os commits de /tags/KDE/4.4.0/kdelibs para a tag v4.4.0 no repositório git do kdelibs a regra seria a seguinte:
match /tags/KDE/4.4.0/kdelibs/ repository kdelibs branch refs/tags/v4.4.0 end match
Para mais exemplos ver o diretório svn2git/samples/ e as regras no repositório kde-ruleset. A ação é um hack para dizer svn2git recurse em um diretório que acabou copiado ou que existia, porque é de interesse.
Exemplo: Se estamos importando kdelibs, existe em trunk/KDE/kdelibs. No branch, alguém fez:
svn cp $SVNROOT/trunk/KDE $SVNROOT/branches/KDE/4.4
SVN gravado naquele commit no branches/KDE/4.4 que era o único path mudado.
Isso significa que a regra
branches/KDE/[^/]+/kdelibs/
não vai corresponder.
Nós precisamos dizer a ferramenta que algo interessante aconteceu e deveria ser aplicado. Em seguida, ele irá solicitar novamente todas as regras para os arquivos que existem nesse ponto, ponto em que as regras irão coincidir.
Detalhes Importantes
- Todas as regras de correspondência precisam terminar com uma '/', ou então a ferramenta irá falhar em algum ponto. Este é um bug conhecido. A única exceção são as regras usando o recurso de ação.
- Regras de correspondência podem usar expressões regulares (de acordo com a sintaxe QRegExp) na linha de partida e pode usar backreferences nos parâmetros repositório e filiais usando \n (n = 1,2,3 ,...) para reduzir a quantidade de regras.
- As regras formam uma lista ordenada que a ferramenta percorre preenchendo os patches correspondentes em cada commit. Portanto, se duas regras correspondem ao mesmo path e nenhum dos dois tem mais critérios de correspondência, a regra que está escrita mais acima no arquivo tem prioridade. Isso é útil para excluir certos commits a partir do processo de extração, se você olhar para o conjunto de regras existentes você vai notar que no topo algumas revisões são ignoradas.
Setting up your system
Você vai precisar de ~ 65GB de espaço em disco para começar, pois o processo requer uma cópia do banco de dados CVS do KDE. Existe um script que irá transferir este para você (e que pode ser usado para atualizá-lo periodicamente com o rsync) na kde-ruleset/bin/startSync.
more stuff goes here ...
Passo-a-passo para escrever regras para um módulo
Analisando o histórico do Subversion para escrever regras
Primeiro de tudo você deve verificar se já existem regras para este módulo no repositório kde-regras. Se já existir alguma regra, por favor vá em "Running svn2git".
Se não há regras, no entanto, vamos começar com a brunch master (aka trunk). A maneira mais fácil de descobrir o histórico com o SVN é executando:
svn log -v --stop-on-copy file:///path/to/kde_svn/trunk/KDE/module
Por favor, note que '/path/to/kde_svn/' é o path para o 65GB você baixou, e o 'trunk/KDE/module' é o módulo que você quer escrever as regras, mas aqueles colocados dois juntos *não* é um caminho que existe fisicamente no disco. svn log é inteligente o suficiente para fazer o que quiser.
Isto lhe dará uma história do dado módulo no porta-malas, ele vai parar na primeira cometer o código que copiou de outro lugar. A saída detalhada permitirá que você veja onde esta cópia veio.
Agora temos um ponto de partida para escrever uma regra, queremos que todos os commits a deste path em nosso repositório no branch master:
match /trunk/KDE/module/ repository module branch master end match
Se o log pára em uma confirmação de que copiou o módulo de algum lugar, precisamos acompanhar este também terá a história importada a partir do local "velho" o módulo residia. O comando svn mesmo pode ser usado com o argumento de path um pouco diferente:
svn log -v --stop-on-copy file:///path/to/kde_svn/some/other/path@revision
A @revision é importante, pois o path original geralmente não existe mais. Com isso podemos escrever a próxima regra para o arquivo de regras e repetir até que tenhamos finalmente chegado ao ponto em que o código foi inicialmente importado para o svn (ou CVS, provavelmente, nos velhos tempos)
Agora nós podemos cuidar das branches, isto é um pouco mais complicado já que pode haver várias branches espalhadas pelo diretório /branches no svn. Você pode usar os mesmos comandos de antes de descobrir o histórico de um branch, se você sabe o path. Desta vez, porém você pode parar de seguir o código da copy-operations, uma vez que você encontrou um código que já foram encontrados em uma regra. Dessa forma, seu ramo estarão ligados ao ramo que o originou (que geralmente é conhecido como trunk aka master) no git.
Uma ajuda útil em encontrar branches é svn ls em combinação com o path@revision sintaxe, dessa forma você pode visualizar o conteúdo de um diretório específico svn como era em uma versão antiga. Com isso, você pode até encontrar ramos que não são visíveis (foram excluídos) na versão atual.
A regra para colocar compromete-se em um ramo no repositório git final só é um pouco diferente (o exemplo é de um módulo central):
match /branches/KDE/4.4/module repository module branch 4.4 end match
E por último, estão as tags, este funciona da mesma forma como as branches e trunk, exceto usando o branch refs/tags/v<tag-version> para o parâmetro do branch.
Executando svn2git
Este é o mais fácil, mas que consome mais tempo. Como exemplo, vamos dizer que em nosso diretório de trabalho atual, temos as regras no repositório kde-ruleset subdir, a ferramenta svn2git na subdir svn2git e o repositório do KDE do no subdir kde_svn:
svn2git/svn-all-fast-export --identity-map kde-ruleset/account-map --rules kde-ruleset/module kde_svn
Isso irá levar algumas horas normalmente, mas ele vai mostrar o progresso. A ferramenta também escreve um log em module.log, caso algo dê errado, você pode encontrar mais detalhes lá.
Tendo isso feito, você deve ter um novo "módulo" de repositório git no seu diretório de trabalho atual.
Verificando um histórico adequado no novo respositório git
Uma maneira muito fácil de verificar se o histórico foi importado corretamente é usar a ferramenta gitk do git. Ele mostra uma representação gráfica da história no repositório git que torna fácil identificar onde algo está errado.
A ferramenta deve ser executada com a - todas as chaves para que ele mostre todos as branches.
Agora você pode percorrer o histórico para verificar se as coisas foram importadas corretamente.
Em primeiro lugar deve haver o branch master, começando no topo com o mais recente commit para o trunk/ e terminando no mais antigo commit que importado o código no SVN do KDE ou o repositório cvs.
A partir do branch master deve haver várias branches para cada branch importada. E eventualmente também branches que partem de uma outra non-master branch.
Coisas que você deve checar são branchs que começam "em lugar nenhum", que é o primeiro commit no ramo não tem nenhum pai em outro ramo ou mestre. Isso significa que svn2git não vêum commit que criou este branch de outro usando o comando svn cp. Isso pode significar que você pode ter esquecido de adicionar uma regra para algum path ou que o mesmo path foi usado para diferentes branches em revisões diferentes. O mesmo se aplica a tags que tenham um commit sem parent.
Isto normalmente pode ser corrigido usando svn log e svn ls para acompanhar o histórico do branch. Eventualmente você pode precisar aplicar os parâmetros min / max da revisão.
Você perceberá que algumas marcas estão procurando desta forma:
| * * <v1.2.3> | | * * | / *
Isso é normal para nossas tags, mesmo que um pouco feio. A razão é que, muitas vezes de compile-fixes são feitas no trunk/ após o tag ter sido criada e, em seguida, o commit foi mesclar (merge) com a tag. Outra coisa, porém, são as tags que são nomeados vx.y.z_124321. Estas são as tags que foram apagadas e recriadas depois.
Normalmente você pode ver que, no log do histórico do svn, essas tags podem ser excluídas manualmente após a criação do repositório usando git tag ou você pode adicionar regras que ignorem certas revisões do tag-path antes de o colocar os commits no repositório git:
match /tags/KDE/3.3.2/kdelibs min revision 424234 max revision 424236 end match match /tags/KDE/3.3.2/kdelibs repository kdelibs branch refs/tags/3.3.2 end match
Se você optar por excluí-los manualmente, por favor certifique-se de documentar com um arquivo texto ou dentro do arquivo de regras, caso alguém faça a conversão novamente mais tarde ele vai saber os passos que você fez.
Antes de publicar o recém criado repositório git certifique-se de empacotá-lo. Isso pode reduzir muito o seu tamanho (por exemplo, Phonon do repositório git poderia ser compactado de 18 MB para 5,2 MB)
Como atualizar o arquivo account-map
No momento, o arquivo account-map está sendo gerado com script 'generateAccountMap' [1] que analisa kde-common/accounts [2] e kde-common/disabled-accounts [3] do SVN.
Depois de ter seu repositório git, você deve verificar se há contas não listadas no arquivo account-map (você pode usar checkMissingAccounts [4]), se for o caso, verifique se as contas que faltam estão listadas no kde-common/accounts ou kde-common/disabled-accounts, se ele não tem um sysadmin bug report [5] para ter a sua conta excluída em incluída nas disabled-accounts. Depois de ter suas contas em falta incluídas nas disabled-accounts, você poderia gerar o arquivo account-map executando 'bin/generateAccountMap', em seguida, execute svn-all-fast-export novamente. Não editar o arquivo account-map diretamente!
Troubleshooting
Ação Recurse não funciona com cvs2svn tag commit
Você pode ter que lidar com um commit feito por cvs2svn para criar uma tag, por exemplo:
r386536 | (no author) | 2005-02-05 22:16:00 +0100 (Sat, 05 Feb 2005) | 2 lines Changed paths: A /branches/beta_0_7_branch (from /trunk:386535) D /branches/beta_0_7_branch/art-devel D /branches/beta_0_7_branch/arts D /branches/beta_0_7_branch/bugs D /branches/beta_0_7_branch/devel-home D /branches/beta_0_7_branch/developer.kde.org D /branches/beta_0_7_branch/enterprise.kde.org D /branches/beta_0_7_branch/events.kde.org D /branches/beta_0_7_branch/foundation D /branches/beta_0_7_branch/kckde D /branches/beta_0_7_branch/kde-common D /branches/beta_0_7_branch/kde-i18n D /branches/beta_0_7_branch/kde-qt-addon D /branches/beta_0_7_branch/kde-women.kde.org D /branches/beta_0_7_branch/kdeaccessibility D /branches/beta_0_7_branch/kdeaddons D /branches/beta_0_7_branch/kdeadmin D /branches/beta_0_7_branch/kdeartwork D /branches/beta_0_7_branch/kdebase D /branches/beta_0_7_branch/kdebindings D /branches/beta_0_7_branch/kdeedu D /branches/beta_0_7_branch/kdeextragear-1 D /branches/beta_0_7_branch/kdeextragear-2 M /branches/beta_0_7_branch/kdeextragear-3 D /branches/beta_0_7_branch/kdeextragear-3/Makefile.am.in D /branches/beta_0_7_branch/kdeextragear-3/Makefile.cvs D /branches/beta_0_7_branch/kdeextragear-3/README D /branches/beta_0_7_branch/kdeextragear-3/configure.in.bot D /branches/beta_0_7_branch/kdeextragear-3/configure.in.in D /branches/beta_0_7_branch/kdeextragear-3/digikam D /branches/beta_0_7_branch/kdeextragear-3/digikamimageplugins D /branches/beta_0_7_branch/kdeextragear-3/doc D /branches/beta_0_7_branch/kdeextragear-3/filelight D /branches/beta_0_7_branch/kdeextragear-3/kcfgcreator D /branches/beta_0_7_branch/kdeextragear-3/kconfigeditor D /branches/beta_0_7_branch/kdeextragear-3/kdebluetooth D /branches/beta_0_7_branch/kdeextragear-3/kdetv D /branches/beta_0_7_branch/kdeextragear-3/keurocalc D /branches/beta_0_7_branch/kdeextragear-3/kiosktool D /branches/beta_0_7_branch/kdeextragear-3/klicker D /branches/beta_0_7_branch/kdeextragear-3/kplayer D /branches/beta_0_7_branch/kdeextragear-3/pwmanager D /branches/beta_0_7_branch/kdeextragear-libs-1 D /branches/beta_0_7_branch/kdegames D /branches/beta_0_7_branch/kdegraphics D /branches/beta_0_7_branch/kdeinstaller D /branches/beta_0_7_branch/kdejava D /branches/beta_0_7_branch/kdekiosk D /branches/beta_0_7_branch/kdelibs D /branches/beta_0_7_branch/kdemultimedia D /branches/beta_0_7_branch/kdenetwork D /branches/beta_0_7_branch/kdenonbeta D /branches/beta_0_7_branch/kdenox D /branches/beta_0_7_branch/kdepim D /branches/beta_0_7_branch/kdeplayground-artwork D /branches/beta_0_7_branch/kdeplayground-base D /branches/beta_0_7_branch/kdeplayground-edu D /branches/beta_0_7_branch/kdeplayground-games D /branches/beta_0_7_branch/kdeplayground-ioslaves D /branches/beta_0_7_branch/kdeplayground-multimedia D /branches/beta_0_7_branch/kdeplayground-network D /branches/beta_0_7_branch/kdeplayground-pim D /branches/beta_0_7_branch/kdeplayground-utils D /branches/beta_0_7_branch/kdereview D /branches/beta_0_7_branch/kdesdk D /branches/beta_0_7_branch/kdesecurity D /branches/beta_0_7_branch/kdesupport D /branches/beta_0_7_branch/kdetoys D /branches/beta_0_7_branch/kdeutils D /branches/beta_0_7_branch/kdevelop D /branches/beta_0_7_branch/kdewebdev D /branches/beta_0_7_branch/kdoc D /branches/beta_0_7_branch/kfte D /branches/beta_0_7_branch/khtmltests D /branches/beta_0_7_branch/klyx D /branches/beta_0_7_branch/kmusic D /branches/beta_0_7_branch/koffice D /branches/beta_0_7_branch/kofficetests D /branches/beta_0_7_branch/konstruct D /branches/beta_0_7_branch/qt-copy D /branches/beta_0_7_branch/quanta D /branches/beta_0_7_branch/sysconfig D /branches/beta_0_7_branch/valgrind D /branches/beta_0_7_branch/www This commit was manufactured by cvs2svn to create branch 'beta_0_7_branch'.
If you do this
match /branches/beta_0_7_branch/kdeextragear-3/krecipes/ repository krecipes branch 0.7 end match match /branches/beta_0_7_branch/ min revision 386536 max revision 386536 action recurse end match
svn-all-fast-export will fail, you'll get an error sayining that '/foo/bar/path' was not found where '/foo/bar/path' is one of the deleted paths in the cvs2svn commit. This is because some paths were deleted in the same commit where you want to do an 'action recurse'. Therefore, to avoid matching the deleted paths you should do an action recurse on each intermediate directory from '/branches/beta_0_7_branch/' to '/branches/beta_0_7_branch/kdeextragear-3/krecipes/' and you should use a final '$' to make sure that the deleted paths will not be considered, thusly:
match /branches/beta_0_7_branch/kdeextragear-3/krecipes/ repository krecipes branch 0.7 end match match /branches/beta_0_7_branch/kdeextragear-3/$ min revision 386536 max revision 386536 action recurse end match match /branches/beta_0_7_branch/$ min revision 386536 max revision 386536 action recurse end match
Pedindo Ajuda
Se você topar com coisas estranhas ou não consegue encontrar uma regra para algo que você precisa, você pode falar com a equipe de migração do KDE Git no IRC: irc.freenode.org, #kde-git ou na kde-scm-interest mailinglist