Tutorial – Usuário Subversion

Prefácio

O Subversion, CVS, e outros sistemas de versionamento preferem utilizar esta solução como uma alternativa ao trancamento dos arquivos. Neste modelo, cada usuário contata o repositório e copia para si a chamada “working copy”, que é uma cópia fiel da estrutura de arquivos e diretórios do servidor. Esses usuários trabalham em suas cópias particulares em paralelo, e finalmente suas modificações são unidas em uma versão final. Na maioria das vezes o repositório cuida do trabalho de fazer a união ocorrer corretamente, mas em última instância um ser humano deve cuidar desse processo. Na prática, suponhamos que dois usuários obtivessem working copies para si e comecassem a editá-las. Se um deles submeter suas modificações primeiro, quando o outro tentar mandar suas alterações o repositório lhe retornará um erro de “out-of-date” (arquivo antigo). Neste caso, o usuário receberá uma cópia do arquivo novo e deverá comparar esta nova versão com a sua, alterada localmente. Há uma boa chance de que as modificações não sejam conflitantes, e ele então poderá unir suas modificações com as de seu colaborador e submeter uma nova versão, com ambas as contribuições. Mas e se as alterações forem conflitantes? Como o próprio nome indica, nesse caso temos um “conflict” (conflito), e este deverá ser resolvido pelo usuário (uma vez que o programa não é capaz de tomar as decisões inteligentemente). Após resolver o conflito preexistente, possivelmente após uma conversa com o outro usuário, ele poderá então mandar a versão final e funcional.

O modelo utilizado pelo Subversion pode parecer caótico, mas quando vamos observá-lo mais de perto veremos que ele funciona de forma transparente; conflitos são infrequentes, e, quando ocorrem, são resolvidos rapidamente. Isso depende, contudo, de uma comunidade comunicativa e responsiva.

Comandos do Subversion

Vamos ver agora o Subversion em ação. Utilizaremos nos exemplos o cliente de linha de comando do Subversion, “svn”. No quarto capítulo apresentarei ainda alguns clientes gráficos do Subversion para poupar aqueles de vocês que não apreciam a interface de texto.

Primeiramente, suponhamos que iremos acessar um repositório exemplo. Vamos cuidar então da primeira parte, que será obter nossa working copy. Talvez fosse uma boa idéia ver a estrutura de diretórios do repositório exemplo na web, através de um visualizador como o WebSVN; digamos que a estrutura dos diretórios no servidor fosse a seguinte:

svn/
.
. exemplo/
. tags/
. branches/
. trunk/
. README
.
. outros/
. x/
. y/
. z/

Vamos começar então com o comando mais importante de todos – como obter ajuda:

[shell]$ svn help

O comando acima mostraria todos os complementos possíveis ao “svn”, e poderíamos então descobrir qual comando é o mais apropriado para o nosso problema. Supondo agora que gostaríamos de obter uma working copy do repositório exemplo, digitaríamos então o seguinte comando:

[shell]$ svn checkout http://www.foo.bar/svn/exemplo
A  exemplo
A  exemplo/tags
A  exemplo/branches
A  exemplo/trunk
A  exemplo/trunk/README
Checked out revision 1.

Este comando faria o checkout, ou cópia, da pasta “exemplo”, com todo o seu conteúdo, para o diretório atual. Isto quer dizer que, com este comando, obteríamos uma working copy para edição local, possibilitando-nos que trabalhássemos nela de pronto.

Podemos observar naquela última linha “Checked out revision 1”; vejamos o que ela exatamente quer nos dizer: ela nos informa que acabamos de fazer o checkout (ou cópia) dos arquivos do servidor pertencentes à revisão 1. Quando dizemos “revisão 1”, estamos nos referindo ao estado exato do repositório quando este se encontrava na referida revisão 1. Após alguém mandar alterações ao repositório, este passará à revisão 2, que será a mais recente (também conhecida como HEAD). Mas a revisão 1 ainda estará lá, e podemos vê-la ou recuperá-la com os comandos nativos do subversion, normalmente adicionando o switch “-r” ou “–revision”.

Podemos nos referir às revisões de três formas: a mais comum é através do número, que é único e crescente (como em “revision 1”); outra forma é através de palavras-chave que o Subversion nos fornece, como por exemplo HEAD (que se refere à revisão mais recente no repositório); finalmente, podemos nos utilizar ainda de datas em formatos predefinidos.

Expliquemos ainda a estrutura de diretórios dividida em trunk/, branches/ e tags/, largamente utilizada como padrão em repositórios: o diretório trunk/ contém a linha principal de desenvolvimento do projeto, e é nela que boa parte do código é desenvolvido. Pode ser necessário, no entanto, que se desenvolva uma nova capacidade ou característica de um programa, por exemplo. Tal desenvolvimento potencialmente tornaria o código da linha trunk/ instável, e, para evitar esse fato criaríamos um branch do projeto, focado unicamente em desenvolver essa característica específica que seria posteriormente portada de volta à árvore trunk/. Esta é superficialmente a função do diretório branches/.

É também perfeitamente possível que um programa, documento, etc, chegue em um nível de estabilidade tal que poderia ser liberado ao público e no qual não seria desejável nenhuma alteração. Essa é a função do diretório tags/, no qual residem as denominadas versões “estáveis” do projeto em questão.

Retornando aos comandos do Subversion, suponhamos agora que você deixou sua working copy parada por uns tempos e agora resolveu voltar a trabalhar nela. É possível, na verdade provável, que o estado do repositório tenha sido alterado desde sua última conexão. Para trabalhar em cima das versões mais recentes, é necessário que baixemos as modificações, e o faremos através do svn update:

[shell]$ svn update
U  exemplo/trunk/README
U  exemplo/trunk/novo.txt
Updated to revision 2.

Este comando deverá ser executado sob o diretório em que se encontra a working copy, obviamente. Ele irá buscar no servidor as modificações ocorridas em relação à versão local e aplicá-las de imediato.

A esta altura você deve ter notado as letras que apareceram nos últimos comando, A e U. Mas o que elas querem dizer? Vamos ver a seguir:

• U: o arquivo foi “Updated” (atualizado) a partir do servidor
• A: o arquivo ou diretório foi “Added” (adicionado) à sua working copy
• D: o arquivo ou diretório foi “Deleted” (deletado) da sua working copy
• R: o arquivo ou diretório foi “Replaced” (substituído) em sua working copy, ou seja, um elemento foi deletado e posteriormente outro com o mesmo nome foi adicionado; embora tenham o mesmo nome o repositório consegue percebê-los como arquivos diferentes
• G: o arquivo no servidor recebeu alterações, mas sua cópia local tinha as suas modificações; ou as alterações não interceptavam ou eram idênticas às suas, então o Subversion conseguiu colocá-las em  estado de “merGed” (união) sem problemas
• C: o arquivo recebeu alterações “Conflicting” (conflitantes) com as suas, ou seja, na mesma seção do arquivo; trataremos deste caso mais adiante no capítulo

Agora que já temos nossa working copy, podemos começar a trabalhar nela. Temos a possibilidade de fazer dois tipos de mudança: em arquivos específicos ou em diretórios (adicionando e removendo arquivos, por exemplo). No primeiro caso, não é necessário informar o Subversion com algum comando específico, pois ele será capaz de perceber quais arquivos foram mudados e submeter essas alterações ao servidor. Já no segundo caso, poderemos usar um dos quatro comandos básicos para manipulação de arquivos, explicados abaixo:

• svn add

[shell]$ svn add novo.txt
A novo.txt

Este comando irá adicionar o arquivo “novo.txt” ao sistema de controle de versões, e ele também passará a ser versionado pelo repositório Subversion. Isto quer dizer que o arquivo existia para o seu computador mas era ignorado pelo Subversion, e, ao usar o “svn add”, você informou o Subversion que ele deve agora ser versionado. Se fosse um diretório, ele e todos os seus arquivos subjacentes seriam também adicionados. Vale lembrar que este passo não é opcional: não basta criar o arquivo, o “svn add” é fundamental.

• svn delete

[shell]$ svn delete novo.txt
D novo.txt

Este outro comando irá agendar “novo.txt” para deleção do repositório. Se este fosse um arquivo ou link simbólico, ele seria imediatamente deletado da sua working copy; se fosse um diretório, seria deletado apenas após mandarmos as alterações ao servidor. É importante frisar que, após mandarmos as mudanças de volta ao repositório, o arquivo será deletado apenas da revisão mais recente, mas ainda estará presente nas revisões anteriores.

• svn copy

[shell]$ svn copy novo.txt velho.txt
A velho.txt

O “svn copy” acima irá copiar o arquivo “novo.txt”, juntamente com seu histórico, para um arquivo denominado “velho.txt”, que será imediatamente agendade para adição no repositório. O histórico do arquivo criado irá indicar que ele é proveniente de um outro.

• svn move

[shell]$ svn move novo.txt velho.txt
A velho.txt
D novo.txt

Como pode ser visto acima, o “svn move” irá apenas fazer o papel de “svn copy” e “svn delete” em um só comando; ele irá copiar o arquivo com um outro nome e depois irá deletar o original, o que seria basicamente o equivalente a renomear um arquivo qualquer.

Agora que já editamos o que fosse necessário ou desejável, seria interessante verificar o que foi modificado antes de mandar nossas alterações ao repositório, criando uma nova revisão. Podemos fazê-lo através do svn status (certamente o comando que você deve, espera-se, mais utilizar no Subversion):

[shell]$ svn status
M      bar.c
?      foo.o
!      qq_dir
I      .screenrc
A  +   moved_dir
M  +   moved_dir/README
D      outros/teste.c
A      outros/calc/soma.h
C      outros/calc/divide.c
R      xyz.c
S  outros/game

Temos acima um possível exemplo de saída do comando “svn status”, que nos ajudará a explicar os status mais importantes a serem compreendidos. Na primeira coluna, temos:

• A: o arquivo/diretório foi agendado para adição no repositório
• C: o arquivo está em estado de conflito e será necessário resolvê-lo antes de mandar as alterações ao servidor
• D: o arquivo/diretório foi agendado para deleção no repositório
• M: o conteúdo do arquivo foi modificado
• R: o arquivo foi agendado para substituição no repositório, com o mesmo nome de um que foi deletado
• ?: o arquivo em questão não está sob controle de versão (possivelmente foi criado e não foi utilizado o “svn add”)
• !: o arquivo não está presente por algum motivo, possivelmente tendo sido deletado sem o uso de um comando Subversion
• I: o arquivo foi configurado para ser ignorado pelo sistema de controle de versões;

Na coluna seguinte poderemos ver um “+” ou não, indicando que um arquivo foi agendado para adição no repositório com a preservação de seu histórico. Isso provavelmente nos dirá que ele é proveniente de uma cópia com o “svn copy” (A+), ou, além de ter sido copiado também foi modificado localmente (M+). A última coluna nos dirá se um arquivo ou diretório foi deslocado do caminho do restante de sua working copy, com o comando “svn switch”, para um branch ou tag (explicados mais à frente). Para a referência completa dos possíveis outputs do “svn status” consulte o manual oficial do Subversion.

Adicionando o switch “-u” ou “–show-updates” ao “svn status”, juntamente com a opção “-v” ou “–verbose” (para maior detalhamento), ele irá contatar o servidor e comparar suas modificações com as revisões que lá se encontram, e irá informar sobre arquivos antigos (out-of-date):

[shell]$ svn status –show-updates –verbose
M      *        44        23    john      README
M               44        20    david     bar.c
*        44        35    susan     outros/teste.c
Status against revision:   46

Os asteriscos acima nos indicam que caso fosse utilizado o “svn update” neste ponto os arquivos “README” e “teste.c” receberiam modificações. Isto quer dizer que nossa revisão local está desatualizada e devemos fazer um update para receber as modificações nestes arquivos e conferir se estas conflitam com a versão local.

Digamos agora que queremos saber exatamente quais modificações fizemos aos arquivos antes de mandá-las ao servidor; esta seria uma boa hora para usar o svn diff, que mostrará as diferenças entre a nossa versão modificada e a versão obtida inicialmente (que fica no diretório oculto .svn):

[shell]$ svn diff
Index: teste.c
===================================================================
— teste.c (revision 3)
+++ teste.c (working copy)
@@ -1,7 +1,12 @@
+#include
+#include
+#include
+
+#include

int main(void) {
–  printf(“Ola mundo\n”);
+  printf(“Ola de novo mundo\n”);
return 0;
}

As modificações são mostradas em formato diff unificado, sendo as linhas adicionadas mostradas com um “+” antes e as deletadas mostradas com um “-“. É interessante notar que podemos facilmente produzir um patch (arquivo incluido apenas as modificações em um arquivo) com o auxílio do svn diff, como no exemplo abaixo:

[shell]$ svn diff > patchfile

Suponhamos então que você descobrisse que as suas alterações ao “teste.c” acima foram feitas por engano, e que portanto você gostaria de retornar este arquivo ao seu estado original; é um bom momento para utilizar o svn revert:

$ svn revert teste.c
Reverted ‘teste.c’

Isto retornará nosso arquivo “teste.c” ao seu estado original, quando fizemos nosso último checkout a partir do repositório. É um processo semelhante ao utilizado para recuperar eventuais modificações mandadas ao servidor mas que foram desastrosas.

Neste último caso, bastaria dar um checkout em uma revisão anterior e funcional (usando o switch “–revision”), e posteriormente mandar esta revisão correta ao servidor novamente, se tornando HEAD.

Vale lembrar ainda que estes trás últimos comandos, muito embora lidem diretamente com os arquivos antigos, dispensam uma conexão com a rede, pois o Subversion inteligentemente mantém uma cópia imodificada dos arquivo em uma pasta oculta “.svn”, e depois apenas compara o conteúdo desta pasta com as modificações feitas pelo usuário.

Já estamos praticamente finalizados com nossa tarefa diária: sabemos adicionar e deletar arquivos, verificar as modificações feitas, conferir se estas estão desatualizadas e resolver conflitos simples, processo automatizado pelo Subversion. Mas ainda resta uma dúvida: e se nossas modificações não resultarem em um conflito simples, no qual nossa alteração intercepta diretamente a de um colaborador? Vejamos a saída de um svn update que causará esse problema:

[shell]$ svn update
U  INSTALL
G  README
C  teste.c
Updated to revision 46.

As letras U e G caem naqueles casos estudados anteriormente: no primeiro foi feito um update simples e no segundo o Subversion conseguiu unir as modificações locais e remotas sem maiores problemas. Já a terceira ocorrência poderá nos causar um problema, pois indica um conflito (C). Neste caso surgirão três arquivos no diretório de trabalho: [ARQUIVO].mine (com as alterações locais), [ARQUIVO].r[OLD] (arquivo imodificado desde o último update) e [ARQUIVO].r[NEW] (o arquivo proveniente do update, diretamente do repositório). Serão ainda colocados marcadores de conflito no arquivo original, a fim de auxiliar o processo de análise. Poderemos resolver o conflito de três formas:

• Unir os arquivos manualmente:

Pode parecer ameaçador, mas fazer a união dos arquivos é na verdade realmente simples: analisar-se-á as alterações feitas remotamente e estas serão comparadas às locais. O usuário deverá decidir qual delas é a melhor, ou então poderá juntar ambas as soluções. De qualquer maneira, é imprescindível que haja uma boa comunicação entre os colaboradores, pois seria conveniente que houvesse uma discussão entre eles para decidir o melhor caminho.

• Escolher uma das opções:

Pode-se ainda optar por simplesmente copiar uma das soluções inteiramente, ou a local ou a remota. Nesse caso, bastaria um “cp” simples dos sistemas UNIX-like para resolver o conflito.

• Descartar as edições locais:

Finalmente, é também possível perceber que as alterações feitas localmente não deveriam ser mandadas ao repositório. Neste último caso, bastaria um “svn revert” para encerrar o conflito e retornar os arquivos aos seus estados originais.

Uma vez resolvidos todos os conflitos, devemos informar o Subversion, e o faremos com o comando svn resolved:

[shell]$ svn resolved teste.c

Com este comando os arquivos extras que haviam sido criados serão excluídos e a condição de conflito desaparecerá. Agora sim poderemos mandar nossas modificações ao repositório (finalmente!), e o faremos com o comando svn commit:

[shell]$ svn commit -m “Algumas modificacoes simples no arquivo teste.c”
Sending        teste.c
Transmitting file data .
Committed revision 47.

O comando acima submeterá nossas modificações locais ao repositório, e a mensagem passada através do switch “–message” ou “-m” será a mensagem de log do commit. É importantíssimo que essa mensagem descreva precisamente o que foi modificado, assim ficará muito mais fácil recuperar o repositório após um engano, além de ajudar os usuário a utilizar o sistema com mais eficiência. Essa mensagem pode ser ainda passada através de um arquivo, com o switch “–file”.

Existem ainda muitos outros comandos que este tutorial não cobriu, afinal o seu foco é de que seja uma fonte rápida para consulta e aprendizado. Dentre estes encontram-se comandos de pesquisa e administrativos. É altamente recomendada a leitura, complementar, do manual oficial do Subversion.

Front-ends

Desde a versão original deste documento, o número de front-ends disponíveis para o Subversion aumentou drasticamente, exigindo total reformulação desta seção. Aos programas descritos originalmente (RapidSVN, WebSVN e TortoiseSVN), juntaram-se vários outros dignos de nota e de usos variados, e que tornam esse sistema de controle de versão ainda mais interessante de ser utilizado. De clientes stand-alone até aqueles integrados ao desktop, passando por aplicações para browsing via web ou IDE, o número de opções para acessar e operar repositórios SVN é tanto que seria até injusto eleger alguns poucos para figurar neste tutorial.

Assim sendo, irei utilizar o mesmo approach da página de links do site oficial do Subversion (http://subversion.tigris.org/links.html): por categorias, cada aplicação e um link para sua página será apresentado, bem como uma breve descrição do programa. Sem mais delongas, vamos à lista:

• Clientes Stand-Alone

1. Cornerstone: cliente gráfico Subversion para Mac OS X. Não é open source, mas possui versão trial gratuita disponível
2. eSvn: cliente gráfico multiplataforma baseado em QT para o Subversion
3. FSVS: rápido cliente de linha de comando para o Subversion centrado em implantação de software
4. KDESvn: cliente Subeversion para o KDE
5. QSvn: cliente gráfico multiplataforma para o Subversion
6. RapidSVN: cliente gráfico multiplataforma para o Subversion
7. RSVN: script Python que permite múltiplas operações de repositório em uma única transação atômica
8. SmartSVN: cliente gráfico multiplataforma para o Subversion. Não é open source, mas está disponível em versões gratuita e comercial
9. Subcommander: cliente gráfico multiplataforma para o Subversion, inclui ferramenta para merge textual
10. SvnX: cliente gráfico multiplataforma para Mac OS X Panther
11. Syncro SVN Client: cliente gráfico multiplataforma para o Subversion. Não é open source, mas possui versão trial disponível para Mac OS X, Windows e Linux
12. WorkBench: ambiente de desenvolvimento multiplataforma utilizando Subversion, escrito em Python
13. Versions: cliente gráfico Subversion para Mac OS X. Não é open source; requer licença comercial
14. ZigVersion: interface Subversion para Mac OS X. Interface voltada a workflows típicos de programadores. Não é open source

• Clientes integrados ao Desktop

1. Cascade: driver de sistema de arquivos multiplataforma para o Subversion, tanto gráfico quanto em linha de comando. Também provê outras funcionalidades de alto nível. Não é open source; gratuito para uso pessoal
2. KSvn: cliente Subversion para o KDE; um plugin para o Konqueror
3. SCPlugin: integração Subversion para o Finder do Mac OS X
4. TortoiseSVN: um cliente Subversion, implementado como extensão do shell do Windows

• Plugins para IDEs (vale lembrar que muitas IDEs suportam o Subversion nativamente ou por plugins inclusos; esta seção lista os plugins não-inclusos com as IDEs)

1. Aigenta Unified SCC: plugin Subversion/CVS para programas compatíveis com MSSCCI, incluindo o Microsoft Visual Studio e outros. Não é open source, mas possui versão trial gratuita disponível
2. AnkhSVN: integração Subversion para o Microsoft Visual Studio
3. CW Subversion: plugin VCS para o Metrowerks CodeWarrior
4. Subclipse: plugin Subversion para o Eclipse
5. Subversive: plugin Subversion para o Eclipse
6. SVN SCC Proxy: plugin SCC para SVN. Este não é um projeto open source
7. VisualSVN: integração Subversion para o Visual Studio .NET 2003, 2005 & 2008. Este é um produto comercial de código fechado
8. WLW-SVN: extensão Subversion para o WebLogic Workshop (8.1.3/8.1.4)

• Outros plugins

1. psvn.el: interface Subversion para o emacs
2. Vcscommand.vim: plugin de integração CVS/SVN/SVK para o editor vim

• Ferramentas de alto nível que utilizam o Subversion

1. Trac: o Trac é um sistema web minimalista para gerenciamento de projetos e tracking de bugs e requisições. Ele provê uma interface ao sistema de controle de versões (Subversion), um Wiki integrado e funcionalidades de report
2. Collaboa: browser de repositório e tracker de requisições, similar ao Trac

• Browsers de repositório

1. SVN::Web
2. ViewVC (previamente conhecido como ViewCVS)
3. WebSVN
4. Insurrection: Repositório em http://svn.sinz.com/svn/Insurrection/
5. Chora
6. SVN::RaWeb::Light
7. FlexySvn
8. perl_svn
9. mod_svn_view
10. bsSvnBrowser
11. sventon
12. WebClient for SVN

Conclusão

Espero que este documento tenha sido de ajuda para o seu aprendizado, leitor, e através dele estou certo de que foi possível aprender os passos fundamentais para um dia de trabalho completo em um repositório Subversion. Agradeço a leitura e boa utilização dos repositórios!

fonte: http://pwsys.com.br/index.php?option=com_content&view=article&id=67:tutorial-usuario-subversion&catid=41:tutoriais&Itemid=66