Escolar Documentos
Profissional Documentos
Cultura Documentos
Ben Collins-Sussman
Brian W. Fitzpatrick
C. Michael Pilato
Controle de Verso com Subversion: Para Subversion 1.4:
(Compilado da reviso 365)
por Ben Collins-Sussman, Brian W. Fitzpatrick, e C. Michael Pilato
Publicado (TBA)
Copyright 2002, 2003, 2004, 2005, 2006, 2007 Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael
Pilato
Este trabalho est licenciado sob a licena Creative Commons Attribution License. Para obter uma cpia dessa licena, visite
http://creativecommons.org/licenses/by/2.0/ ou envie uma carta para Creative Commons, 559 Nathan Abbott Way, Stanford,
California 94305, USA.
ndice
Apresentao ............................................................................................................................. x
Prefcio .................................................................................................................................... xii
Pblico-Alvo ...................................................................................................................... xii
Como Ler Este Livro ........................................................................................................ xiii
Convenes Usadas Neste Livro ...................................................................................... xiii
Convenes tipogrficas ........................................................................................... xiv
cones ..................................................................................................................... xiv
Organizao Deste Livro .................................................................................................. xiv
Este Livro Livre ............................................................................................................. xv
Agradecimentos ................................................................................................................ xv
Agradecimentos de Ben Collins-Sussman ................................................................. xvi
Agradecimentos de Brian W. Fitzpatrick .................................................................... xvi
Agradecimentos de C. Michael Pilato ........................................................................ xvi
O Que o Subversion? .................................................................................................. xvii
Histrico do Subversion ........................................................................................... xvii
Caractersticas do Subversion ................................................................................. xviii
Arquitetura do Subversion ........................................................................................ xix
Componentes do Subversion .................................................................................... xxi
1. Conceitos Fundamentais ........................................................................................................ 1
O Repositrio ..................................................................................................................... 1
Modelos de Versionamento ................................................................................................ 1
O Problema do Compartilhamento de Arquivos ............................................................ 2
A Soluo Lock-Modify-Unlock .................................................................................... 2
A Soluo Copy-Modify-Merge .................................................................................... 4
Subversion em Ao .......................................................................................................... 6
URLs do Repositrio Subversion ................................................................................ 6
Cpias de Trabalho, ou Cpias Locais ........................................................................ 7
Revises .................................................................................................................. 10
Como as Cpias de Trabalho Acompanham o Repositrio .......................................... 11
Revises Locais Mistas ............................................................................................ 12
Sumrio ........................................................................................................................... 13
2. Uso Bsico .......................................................................................................................... 14
Help! ................................................................................................................................ 14
Colocando dados em seu Repositrio ............................................................................... 14
svn import ................................................................................................................ 14
Layout de repositrio recomendado ........................................................................... 15
Checkout Inicial ................................................................................................................ 15
Desabilitando o Cache de Senhas ............................................................................ 17
Autenticando como um Usurio Diferente .................................................................. 17
Ciclo Bsico de Trabalho .................................................................................................. 18
Atualizando Sua Cpia de Trabalho .......................................................................... 18
Fazendo Alteraes em Sua Cpia de Trabalho ........................................................ 19
Verificando Suas Alteraes ..................................................................................... 20
Desfazendo Modificaes de Trabalho ...................................................................... 23
Resolvendo Conflitos (Combinando Alteraes de Outros) .......................................... 24
Registrando Suas Alteraes .................................................................................... 28
Examinando o Histrico .................................................................................................... 29
Gerando uma lista de alteraes histricas ................................................................ 29
Examinando os detalhes das alteraes histricas ..................................................... 31
Navegando pelo repositrio ...................................................................................... 32
Retornando o repositrio a momentos antigos ........................................................... 33
s Vezes Voc S Precisa Limpar .................................................................................... 34
Sumrio ........................................................................................................................... 34
3. Tpicos Avanados .............................................................................................................. 35
Especificadores de Reviso .............................................................................................. 35
iii
Controle de Verso
com Subversion
iv
Controle de Verso
com Subversion
v
Controle de Verso
com Subversion
vi
Lista de Figuras
1. Arquitetura do Subversion ..................................................................................................... xx
1.1. Um tpico sistema cliente/servidor ........................................................................................ 1
1.2. O problema para evitar ........................................................................................................ 2
1.3. A soluo lock-modify-unlock ............................................................................................... 3
1.4. A soluo copy-modify-merge .............................................................................................. 4
1.5. A soluo copy-modify-merge (continuando) ......................................................................... 5
1.6. O Sistema de Arquivos do Repositrio ................................................................................. 8
1.7. O Repositrio .................................................................................................................... 10
4.1. Ramos de desenvolvimento ............................................................................................... 72
4.2. Layout Inicial do Repositrio .............................................................................................. 73
4.3. Repositrio com uma nova cpia ....................................................................................... 75
4.4. Ramificao do histrico de um arquivo .............................................................................. 77
8.1. Arquivos e diretrios em duas dimenses ......................................................................... 182
8.2. Versionando o tempoa terceira dimenso! ..................................................................... 182
vii
Lista de Tabelas
1.1. URLs de Acesso ao Repositrio .......................................................................................... 9
5.1. Comparativo dos Mecanismos de Armazenamento ............................................................ 107
6.1. Comparao das Opes para o Servidor Subversion ....................................................... 137
C.1. Clientes WebDAV Comuns .............................................................................................. 324
viii
Lista de Exemplos
5.1. txn-info.sh (Obtendo Informaes Sobre Transaes Pendentes) ....................................... 119
5.2. Script de hook pre-revprop-change para operao de espelhamento ................................... 130
5.3. Script de hook start-commit para operao de espelhamento ............................................. 131
6.1. Um exemplo de configurao para acesso annimo. ......................................................... 156
6.2. Um exemplo de configurao para acesso autenticado. ..................................................... 156
6.3. Um exemplo de configurao para acesso misto autenticado/annimo. ............................... 157
6.4. Desabilitando verificaes de caminho como um todo ........................................................ 158
7.1. Arquivo (.reg) com Entradas de Registro de Exemplo. ....................................................... 169
7.2. diffwrap.sh ....................................................................................................................... 177
7.3. diffwrap.bat ...................................................................................................................... 177
7.4. diff3wrap.sh ..................................................................................................................... 178
7.5. diff3wrap.bat .................................................................................................................... 178
8.1. Usando a Camada de Repositrio .................................................................................... 190
8.2. Usando a Camada de Repositrio com Python ................................................................. 192
8.3. Um Rastreador de Status em Python ................................................................................ 194
ix
Apresentao
Karl Fogel
Chicago, 14 de Maro de 2004
Uma base ruim de Perguntas Freqentes (FAQ), aquela que composta no de perguntas que as
pessoas realmente fizeram, mas de perguntas que o autor da FAQ desejou que as pessoas tivessem
feito. Talvez voc j tenha visto isto antes:
R: Muitos dos nossos clientes desejam saber como podem maximizar a produtividade
atravs de nossas inovaes patenteadas de groupware para escritrios. A
resposta simples: primeiro, clique no menu Arquivo. Desa at a opo
Aumentar Produtividade, ento
O problema com estas bases de FAQ que eles no so, propriamente ditas, FAQ. Ningum nunca
liga para o suporte tcnico e pergunta Como ns podemos maximizar a produtividade?. Em vez
disso, as pessoas fazem perguntas muito mais especficas, como: Como podemos alterar o sistema
de calendrio para enviar lembretes dois dias antes ao invs de um?, etc. Mas muito mais fcil forjar
Perguntas Freqentes imaginrias do que descobrir as verdadeiras. Compilar uma verdadeira base de
FAQ exige um esforo contnuo e organizado: atravs do ciclo de vida do software, as questes que
chegam devem ser rastreadas, respostas monitoradas, e tudo deve ser reunido em um todo coerente,
pesquisvel que reflete a experincia coletiva dos usurios em seu mundo. Isto requer a pacincia e
a atitude observadora de um cientista. Nenhuma grande teoria ou pronunciamentos visionrios aqui
olhos abertos e anotaes precisas so o principal.
O que eu amo neste livro que ele surgiu deste processo, e isto evidenciado em cada pgina. Ele o
resultado direto dos encontros entre os autores e usurios. Ele comeou quando Ben Collins-Sussman
observou que as pessoas estavam fazendo as mesmas perguntas bsicas diversas vezes nas listas
de discusso do Subversion, como por exemplo: Quais so os procedimentos-padro para se utilizar
o Subversion? Branches e tags funcionam do mesmo modo como em outros sistemas de controle de
verso? Como eu posso saber quem realizou uma alterao em particular?
Frustrado em ver as mesmas questes dia aps dia, Ben trabalhou intensamente durante um ms no
vero de 2002 para escrever The Subversion Handbook, um manual de sessenta pginas cobrindo
todas as funcionalidades bsicas do Subversion. O manual no tinha a pretenso de ser completo,
mas ele foi distribudo com o Subversion e auxiliou os usurios a ultrapassarem as dificuldades iniciais
na curva de aprendizado. Quando a O'Reilly and Associates decidiu publicar um livro completo sobre
o Subversion, o caminho menos crtico estava bvio: apenas estender o manual.
Para os trs co-autores do novo livro ento lhes foi dada uma oportunidade mpar. Oficialmente,
sua tarefa era escrever um livro numa abordagem top-down, comeando pelo sumrio e seu esboo
inicial. Mas eles tambm tinham acesso a um fluxo constantede fato, um giser incontrolvel
de contedo de origem bottom-up. O Subversion j esteve nas mos de centenas de usurios
anteriores, que geraram toneladas de feedback, no apenas sobre o Subversion, mas tambm sobre
sua documentao existente.
Durante todo o tempo em que eles escreveram o livro, Ben, Mike, e Brian habitaram as listas de
discusso e salas de bate-papo do Subversion, registrando cuidadosamente os problemas que os
usurio estavam tendo em situaes na vida-real. Monitorar este feedback, fazia parte da descrio
de sua funo na CollabNet, e isto lhes deu uma enorme vantagem quando comearam a documentar
o Subversion. O livro que eles produziram solidamente fundamentado na rocha da experincia, no
nas areias mutveis da iluso; ele combina os melhores aspectos de um manual de usurio e uma
base de FAQ. Esta dualidade talvez no seja perceptvel numa primeira leitura. Lido na ordem, de
frente para trs, o livro uma descrio bem direta de uma pea de software. Existe a viso geral, o
obrigatrio tour, o captulo sobre configurao administrativa, alguns tpicos avanados, e claro uma
referncia de comandos e um guia de resoluo de problemas. Somente quando voc o ler novamente
x
Apresentao
mais tarde, procurando a soluo para um problema especfico, que sua autenticidade reluzir: os
detalhes telling que s podem advir de um encontro com o inusitado, os exemplos surgidos de casos
de utilizao reais, e muito de toda a sensibilidade das necessidades e dos pontos de vista do usurio.
claro, que ningum pode prometer que este livro responder todas as dvidas que voc tem sobre o
Subversion. Certas vezes, a preciso com que ele antecipa suas perguntas parecer assustadoramente
teleptica; ainda sim, ocasionalmente, voc vai tropear em alguma falha no conhecimento da
comunidade, e sair de mo vazias. Quando isto acontecer, a melhor coisa que voc pode fazer
enviar um email para <users@subversion.tigris.org> e apresentar seu problema. Os autores
ainda esto l, continuam observando, e no somente os trs listados na capa, mas muitos outros que
contriburam com correes e materiais originais. Do ponto de vista da comunidade, resolver o seu
problema meramente um agradvel efeito de um projeto muito maiorrealmente, o ajuste paulatino
deste livro, e em ltimo caso, do prprio Subversion, para ver mais de perto como as pessoas o
utilizam. Eles esto ansiosos para ouvir voc no apenas porque eles querem ajud-lo, mas porque
voc tambm os ajuda. Com o Subversion, assim como em todo projeto ativo de software livre, voc
no est sozinho.
xi
Prefcio
importante no deixar que o perfeito se torne inimigo do bom, mesmo quando voc
puder estar certo sobre o que o perfeito . Duvide quando voc no puder. Como
desagradvel ser aprisionado pelos erros passados, voc no pode fazer qualquer
progresso tendo medo de sua prpria sombra durante a ao.
Greg Hudson
No mundo dos softwares open-source, o Concurrent Versions System (CVS) foi a ferramenta escolhida
para controle de verso por muitos anos. E com razo. O prprio CVS um software open-source
tambm, e seu modus operandi no-restritivo e o suporte a operaes de rede permitiram que diversos
programadores distribudos geograficamente compartilhassem seus trabalhos. Ele atende natureza
colaborativa do mundo open-source como um todo. O CVS e seu modelo de desenvolvimento semi-
catico se tornou um marco da cultura open-source.
Mas o CVS tambm tinha seus defeitos, e simplesmente corrigir estes defeitos prometia ser um enorme
esforo. Chega o Subversion. Desenvolvido para ser um sucessor do CVS, os criadores do Subversion
pretendiam ganhar a simpatia dos usurios CVS de duas maneirascriando um sistema open-source
com o projeto (e a aparncia) semelhante ao do CVS, e tentando evitar muitos de seus conhecidos
defeitos. Por mais que o resultado no seja necessariamente a prxima grande evoluo no projeto
de controle de verso, o Subversion muito poderoso, muito usvel, e muito flexvel. E agora muitos
projetos open-source, quase todos recm-iniciados, preferem agora o Subversion ao CVS.
Este livro foi escrito para documentar a srie 1.4 do sistema de controle de verso Subversion. Ns
tentamos ser bem profundos em nossa abordagem. Entretanto, o Subversion possui uma comunidade
de desenvolvedores prspera e cheia de energia, ento eles j tm um conjunto de recursos e melhorias
planejadas para futuras verses do Subversion que podem mudar alguns dos comandos e notas
especficas deste livro.
Pblico-Alvo
Este livro foi escrito para pessoas habituadas com computadores que desejam usar o Subversion para
gerenciar seus dados. Ainda que o Subversion rode em vrios sistemas operacionais diferentes, a sua
interface de usurio primria baseada em linha de comando. Essa ferramenta de linha de comando
(svn), e alguns programas auxiliares, so o foco deste livro.
Por motivo de consistncia, os exemplos neste livro presumem que o leitor esteja usando um sistema
operacional baseado em Unix e se sinta relativamente confortvel com Unix e com interfaces de linha de
comando. Dito isto, o programa svn tambm roda em plataformas no-Unix, como o Microsoft Windows.
Com poucas excees, como o uso de barras invertidas (\) em lugar de barras regulares (/) para
separadores de caminho, a entrada e a sada desta ferramenta, quando executada no Windows, so
idnticas s do seu companheiro Unix.
Enquanto que este livro presume que o leitor nunca usou um sistema de controle de verso, ns
tambm tentamos facilitar para os usurios do CVS (e outros sistemas) a migrao para o Subversion.
Ocasionalmente, notas especiais podero mencionar outros controles de verso. H tambm um
apndice que resume muitas das diferenas entre CVS e Subversion.
Note tambm que os exemplos de cdigo-fonte usados ao longo do livro so apenas exemplos. Ainda
que eles compilem com os truques apropriados do compilador, seu propsito ilustrar um cenrio em
particular, no necessariamente servir como exemplos de boas prticas de programao.
xii
Prefcio
Independente do seu estilo de aprendizado, este livro pretende ser til para os mais diversos tipos de
pessoas os que no possuem nenhuma experincia com controle de verso at os administradores
de sistema mais experientes. Dependendo do seu conhecimento, certos captulos podem ser mais ou
menos importantes para voc. A lista abaixo uma recomendao de leitura para os diversos tipos
de leitores:
Novos usurio
Seu administrador provavelmente j disponibilizou um servidor Subversion, e voc precisa
aprender a usar o cliente. Se voc nunca utilizou um sistema de controle de verso, ento o
Captulo 1, Conceitos Fundamentais ser vital para introduzir e mostrar as idias por trs do
controle de verso. O Captulo 2, Uso Bsico um guia do cliente do Subversion.
Usurios avanados
Seja voc um usurio ou um administrador, eventualmente seu projeto ir crescer muito. Voc ir
querer aprender a fazer coisas avanadas com o Subversion, como usar ramos e fazer fuses
(Captulo 4, Fundir e Ramificar), como usar as propriedades de suporte do Subversion (Captulo 3,
Tpicos Avanados), como configurar as opes de tempo de execu o (Captulo 7, Customizando
sua Experincia com Subversion), entre outras coisas. Estes captulos no so crticos no incio,
porm no deixe de l-los quando estiver familiarizado com o bsico.
Desenvolvedores
Presumidamente, voc j est familiarizado com o Subversion, e quer ou extend-lo ou construir
um novo software baseado nas suas diversas APIs. O Captulo 8, Incorporando o Subversion foi
feito justamente pra pra voc.
xiii
Prefcio
Convenes tipogrficas
Largura constante
Comandos usados, comando de sada, e opes
Itlico
Usado para nomes de arquivo e diretrio
cones
Este cone representa uma nota relacionada ao texto citado.
Prefcio
Cobre a histria do Subversion bem como suas caractersticas, arquitetura e compomentes.
xiv
Prefcio
Voc sempre ir encontrar a ltima verso deste livro no prprio repositrio Subversion do livro.
Voc pode fazer alteraes neste livro e redistribu-lo, entretanto voc deve faz-losob uma licena
livre. Sua nica obrigao manter o crditos originais dos autores. claro que, ao invs de distribuir
sua prpria verso deste livro, gostaramos muito mais que voc enviasse seu feedback e correes
para a comunidade de desenvolvimento do Subversion.
O site deste livro est em desenvolvimento, e muitos dos tradutores voluntrios esto se reunindo no
site http://svnbook.red-bean.com. L voc pode encontrar links para as ltimas verses lanadas e
verses compiladas deste livro em diversos formatos, bem como as instrues de acesso ao repositrio
Subversion do livro(onde est o cdigo-fonte em formato DocBook XML) Um feedback bem vindo
e encorajado tambm. Por favor, envie todos os seus comentrios, reclamaes, e retificaes dos
fontes do livro para o e-mail <svnbook-dev@red-bean.com>.
Agradecimentos
Este livro no existiria (nem seria til) se o Subversion no existisse. Assim, os autores gostariam de
agradecer ao Brian Behlendorf e CollabNet, pela viso em acreditar em um arriscado e ambicioso
xv
Prefcio
projeto de Cdigo Aberto; Jim Blandy pelo nome e projeto original do Subversionns amamos voc,
1
Jim; Karl Fogel, por ser um excelente amigo e grande lder na comunidade, nesta ordem.
Agradecimentos a O'Reilly e nossos editores, Linda Mui e Tatiana Diaz por sua paciente e apoio.
Finalmente, agrademos s inmeras pessoas que contriburam para este livro com suas revises
informais, sugestes e retificaes. Certamente, esta no uma lista completa, mas este livro estaria
incompleto e incorreto sem a ajuda de: David Anderson, Jani Averbach, Ryan Barrett, Francois
Beausoleil, Jennifer Bevan, Matt Blais, Zack Brown, Martin Buchholz, Brane Cibej, John R. Daily,
Peter Davis, Olivier Davy, Robert P. J. Day, Mo DeJong, Brian Denny, Joe Drew, Nick Duffek, Ben
Elliston, Justin Erenkrantz, Shlomi Fish, Julian Foad, Chris Foote, Martin Furter, Dave Gilbert, Eric
Gillespie, David Glasser, Matthew Gregan, Art Haas, Eric Hanchrow, Greg Hudson, Alexis Huxley,
Jens B. Jorgensen, Tez Kamihira, David Kimdon, Mark Benedetto King, Andreas J. Koenig, Nuutti
Kotivuori, Matt Kraai, Scott Lamb, Vincent Lefevre, Morten Ludvigsen, Paul Lussier, Bruce A. Mah,
Philip Martin, Feliciano Matias, Patrick Mayweg, Gareth McCaughan, Jon Middleton, Tim Moloney,
Christopher Ness, Mats Nilsson, Joe Orton, Amy Lyn Pilato, Kevin Pilch-Bisson, Dmitriy Popkov, Michael
Price, Mark Proctor, Steffen Prohaska, Daniel Rall, Jack Repenning, Tobias Ringstrom, Garrett Rooney,
Joel Rosdahl, Christian Sauer, Larry Shatzer, Russell Steicke, Sander Striker, Erik Sjoelund, Johan
Sundstroem, John Szakmeister, Mason Thomas, Eric Wadsworth, Colin Watson, Alex Waugh, Chad
Whitacre, Josef Wolf, Blair Zajac e a comunidade inteira do Subversion.
Agradeo minha extensa famlia e amigos por seus sinceros votos de encorajamento, apesar de no
terem qualquer interesse no assunto. (Voc sabe, tem uns que dizem: Voc escreveu um livro?, e
ento quando voc diz que um livro de computador, eles te olham torto.)
Agradeo aos meus amigos mais prximos, que me fazem um rico, rico homem. No me olhem assim
vocs sabem quem so.
Agradeo aos meus pais pela minha perfeita formao bsica, e pelos inacreditveis conselhos.
Agradeo ao meu filho pela oportunidade de passar isto adiante.
Mike e Ben, foi um prazer trabalhar com vocs neste livro. Heck, um prazer trabalhar com voc nesta
obra!
Para todos da comunidade Subversion e a Apache Software Foundation, agradeo por me receberem.
No h um dia onde eu no aprenda algo com pelo menos um de vocs.
xvi
Prefcio
Gavin, provavelmente no h muitas palavras neste livro que voc possa, com sucesso, pronunciar
nesta fase de sua vida, mas quando voc, finalmente, aprender a forma escrita desta louca lngua que
falamos, espero que voc esteja to orgulhoso de seu pai quanto ele de voc.
2
Aidan, Daddy luffoo et ope Aiduh yike contootoo as much as Aiduh yike batetball, base-ball, et bootball.
Me e Pai, agrao pelo apoio e entusiasmo constante. Sogra e Sogro, agradeo por tudo da mesma
forma e mais um pouco por sua fabulosa filha.
Tiro o chapu para Shep Kendall, foi atravs dele que o mundo dos computadores foi aberto pela
primeira vez a mim; Ben Collins-Sussman, meu orientador pelo mundo do cdigo-aberto; Karl Fogel
voc meu .emacs; Greg Stein, o difusor da programao prtica como-fazer; Brian Fitzpatrick
por compartilhar esta experincia de escrever junto comigo. s muitas pessoas com as quais eu estou
constantemente aprendendoe continuo aprendendo!
Finalmente, agradeo a algum que demonstra ser perfeitamente criativo em sua excelnciavoc.
O Que o Subversion?
Subversion um sistema de controle de verso livre/open-source. Isto , o Subversion gerencia
arquivos e diretrios, e as modificaes feitas neles ao longo do tempo. Isto permite que voc recupere
verses antigas de seus dados, ou que examine o histrico de suas alteraes. Devido a isso, muitas
pessoas tratam um sistema de controle de verso como uma espcie de mquina do tempo.
O Subversion pode funcionar em rede, o que lhe possibilita ser usado por pessoas em diferentes
computadores. Em certo nvel, a capacidade de vrias pessoas modificarem e gerenciarem o mesmo
conjunto de dados de seus prprios locais o que fomenta a colaborao. Progressos podem ocorrer
muito mais rapidamente quando no h um gargalo nico por onde todas as modificaes devam
acontecer. E como o trabalho est versionado, voc no precisa ter medo de que seu trabalho perca
qualidade por no ter essa via nica para modificaesse os dados sofrerem alguma modificao
indevida, apenas desfaa tal modificao.
Histrico do Subversion
No comeo do ano 2000, a CollabNet, Inc. (http://www.collab.net) comeou a procurar desenvolvedores
para desenvolver um substituto para o CVS. A CollabNet j tinha uma suite colaborativa chamada
CollabNet Enterprise Edition (CEE) cujo um de seus componentes era o controle de verso. Apesar
de o CEE usar o CVS como seu sistema de controle de verso inicial, as limitaes do CVS ficaram
evidentes desde o princpio, e a CollabNet sabia que eventualmente teria que procurar por algo melhor.
Infelizmente, o CVS havia se firmado como um padro de fact no mundo open source principalmente
porque no havia nada melhor, pelo menos sob licena livre. Ento a CollabNet decidiu desenvolver
um novo sistema de controle de verso a partir do zero, mantendo as idias bsicas do CVS, mas sem
os bugs e seus inconvenientes.
Em Fevereiro de 2000, eles contactaram Karl Fogel, o autor de Open Source Development with CVS
(Coriolis, 1999), e perguntaram se ele gostaria de trabalhar neste novo projeto. Coincidentemente,
2
Traduo: Papai te ama e espera que voc goste de computadores assim como voc ir gostar de basquete, basebol e futebol.
(Isso seria bvio?)
xvii
Prefcio
no momento Karl j estava discutindo o projeto para um novo sistema de controle de verso com
seu amigo Jim Blandy. Em 1995, os dois iniciaram a Cyclic Software, uma empresa que mantinha
contratos de suporte para o CVS, e apesar de terem vendido a empresa posteriormente, eles ainda
usavam o CVS todos os dias em seus trabalhos. Suas frustraes com o CVS levou Jim a pensar
cuidadosamente sobre melhores maneiras para gerenciar dados versionados, no que ele no apenas
j tinha pensado no nome Subversion, mas tambm com o projeto bsico para armazenamento de
dados do Subversion. Quando a CollabNet chamou, Karl concordou imediatamente em trabalhar no
projeto, e Jim sugeriu empresa em que trabalhava, Red Hat Software, essencialmente a ced-lo para
o projeto por um perodo de tempo indefinido. A CollabNet contratou Karl e Ben Collins-Sussman, e
um projeto detalhado de trabalho comeou em Maio. Com a ajuda e o bem-vindo incentivo de Brian
Behlendorf e Jason Robbins da CollabNet, e de Greg Stein ( poca, um desenvolvedor independente
trabalhando no processo de especificao do WebDAV/DeltaV), o Subversion rapidamente atraiu uma
comunidade ativa de desenvolvedores. Detectou-se que muitas pessoas tambm tinham as mesmas
experincias frustrantes com o CVS, agora satisfeitas com a oportunidade de finalmente fazer algo
sobre isso.
A equipe do projeto original determinou alguns objetivos simples. Eles no queriam romper com a
metodologia existente para controle de verso, eles apenas queriam corrigir o CVS. Eles decidiram
que o Subversion deveria ser compatvel com as caractersticas do CVS, e manter o mesmo modelo
de desenvolvimento, mas no reproduzir as falhas mais bvias do CVS. E mesmo que o novo sistema
no fosse um substituto definitivo para o CVS, ele deveria ser suficientemente semelhante a este para
que qualquer usurio do CVS pudesse migrar de sistema com pouco esforo.
Embora a CollabNet tenha iniciado o projeto, e ainda patrocine uma grande parte dos trabalhos (ela
paga os salrios de alguns poucos desenvolvedores do Subversion em tempo integral), o Subversion
mantido como a maioria dos projetos open source, gerenciado por um conjunto de regras transparentes
e de senso-comum, fundamentadas na meritocracia. A licena adotada pela CollabNet perfeitamente
compatvel com Definio Debian de Software Livre (DFSG). Em outras palavras, qualquer pessoa
livre para baixar o cdigo do Subversion, modific-lo, e redistribu-lo conforme lhe convier; no
necessrio pedir permisso CollabNet ou a quem quer que seja.
Caractersticas do Subversion
Ao discutir sobre que recursos o Subversion traz para o mbito do controle de verso, frequentemente
til falar deles em termos de que avanos eles representam aos recursos do CVS. Se voc no
est familiarizado com o CVS, voc pode no compreender todas essas caractersticas. E se voc no
estiver familiarizado com controle de verso como um todo, voc pode ficar bem confuso a menos que
voc leia antes Captulo 1, Conceitos Fundamentais, onde apresentamos uma suave introduo ao
controle de verso.
O Subversion proporciona:
Versionamento de diretrios
O CVS apenas rastreia o histrico de arquivos individuais, j o Subversion implementa um sistema
de arquivos virtual sob controle de verso que rastreia modificaes a toda a rvore de diretrio
ao longo do tempo. Os arquivos e os diretrios so versionados.
xviii
Prefcio
e renomear ambos os arquivos ou diretrios. E cada novo arquivo adicionado comea com um
histrico prprio e completamente novo.
Commits atmicos
Um conjunto de modificaes ou inteiramente registrado no repositrio, ou no registrado de
forma nenhuma. Isto possibilita aos desenvolvedores criarem e registrarem alteraes como blocos
lgicos, e tambm evita problemas que possam ocorrer quando apenas uma parte de um conjunto
de alteraes seja enviada com sucesso ao repositrio.
Versionamento de metadados
Cada arquivo e diretrio tem um conjunto de propriedadeschaves e seus valoresassociados
consigo. Voc pode criar e armazenar quaisquer pares chave/valor que quiser. As propriedades
so versionadas ao longo do tempo, tal como os contedos de arquivo.
Hackability
O Subversion no tem qualquer bagagem histrica; ele implementado como um conjunto de
bibliotecas C compartilhadas com APIs bem definidas. Isto torna o Subversion extremamente
manutenvel e usvel por outras aplicaes e linguagens.
Arquitetura do Subversion
Figura 1, Arquitetura do Subversion ilustra uma viso em alto nvel da estrutura do Subversion.
xix
Prefcio
Em uma ponta encontra-se um repositrio do Subversion que mantm todos os seus dados
versionados. No outro extremo est o seu programa cliente Subversion, que gerencia cpias locais
de partes desses dados versionados (chamadas de cpias de trabalho). Entre esses dois extremos
esto mltiplas rotas por entre vrias camadas de Acesso ao Repositrio (RA). Algumas dessas rotas
partem das redes de computadores at os servidores de rede, de onde ento acessam o repositrio.
Outras desconsideram a rede completamente e acessam diretamente o repositrio.
xx
Prefcio
Componentes do Subversion
Uma vez instalado, o Subversion consiste num conjunto de diversas partes. Uma breve viso geral
sobre tudo o que voc dispe mostrada a seguir. No se preocupe se as breves descries acabarem
fundindo a sua cucah muito mais pginas neste livro para acabar com essa confuso.
svn
O programa cliente de linha de comando.
svnversion
Um programa para informar o estado (em termos das revises dos itens presentes) da cpia de
trabalho.
svnlook
Uma ferramenta para inspecionar um repositrio Subversion diretamente.
svnadmin
Uma ferramenta para criao, ajuste e manuteno de um repositrio Subversion.
svndumpfilter
Um programa para filtragem de fluxos de um repositrio Subversion.
mod_dav_svn
Um mdulo plugin para o servidor Apache HTTP, usado para disponibilizar seu repositrio a outros
atravs da rede.
svnserve
Um especfico programa servidor independente, executvel como um processo daemon ou
invocvel via SSH; uma outra forma de disponibilizar seu repositrio a outros atravs da rede.
svnsync
Um programa para fazer espelhamento incremental de um repositrio para outro atravs da rede.
Uma vez que voc tenha instalado o Subversion corretamente, voc j deve estar pronto para iniciar.
Os prximos dois captulos vo gui-lo pela uso do svn, o programa cliente de linha de comando do
Subversion.
xxi
Captulo 1. Conceitos Fundamentais
Este captulo uma breve e casual introduo ao Subversion. Se voc novo em controle de verso,
este captulo definitivamente para voc. Ns comearemos com uma discusso sobre os conceitos
gerais de controle de verso, avanaremos para as idias especficas por trs do Subversion, e
mostraremos alguns exemplos simples do Subversion em uso.
Embora os exemplos neste captulo mostrem pessoas compartilhando colees de cdigo fonte de
programas, tenha em mente que o Subversion pode gerenciar qualquer tipo de coleo de arquivos -
ele no est limitado a ajudar programadores.
O Repositrio
O Subversion um sistema centralizado de compartilhamento de informao. Em seu ncleo est um
repositrio, que uma central de armazenamento de dados. O repositrio armazena informao em
forma de uma rvore de arquivos - uma hierarquia tpica de arquivos e diretrios. Qualquer nmero de
clientes se conecta ao repositrio, e ento l ou escreve nestes arquivos. Ao gravar dados, um cliente
torna a informao disponvel para outros; ao ler os dados, o cliente recebe informao de outros.
Figura 1.1, Um tpico sistema cliente/servidor ilustra isso.
Ento, por que razo isto interessante? At ao momento, isto soa como a definio de um tpico
servidor de arquivos. E, na verdade, o repositrio uma espcie de servidor de arquivos, mas no de
um tipo comum. O que torna o repositrio do Subversion especial que ele se lembra de cada alterao
j ocorrida nele: de cada mudana em cada arquivo, e at mesmo alteraes na rvore de diretrios
em si, como a adio, eliminao, e reorganizao de arquivos e diretrios.
Quando um cliente l dados de um repositrio, ele normalmente v apenas a ltima verso da rvore de
arquivos. Mas o cliente tambm tem a habilidade de ver os estados anteriores do sistema de arquivos.
Por exemplo, um cliente pode perguntar questes de histrico como, O que este diretrio continha
na ltima quarta-feira? ou Quem foi a ltima pessoa que alterou este arquivo, e que alteraes ela
fez? Estes so os tipos de questes que esto no corao de qualquer sistema de controle de verso:
sistemas que so projetados para monitorar alteraes nos dados ao longo do tempo.
Modelos de Versionamento
A misso principal de um sistema de controle de verso permitir a edio colaborativa e o
compartilhamento de dados. Mas diferentes sistemas usam diferentes estratgias para atingir esse
objetivo. importante compreender essas diferentes estratgias por vrias razes. Primeiro, ir ajud-
lo a comparar os sistemas de controle de verso existentes, no caso de voc encontrar outros sistemas
1
Conceitos Fundamentais
similares ao Subversion. Alm disso, ir ajud-lo ainda a tornar o uso do Subversion mais eficaz, visto
que o Subversion por si s permite trabalhar de diferentes formas.
Considere o cenrio mostrado em Figura 1.2, O problema para evitar. Vamos supor que ns temos
dois colegas de trabalho, Harry e Sally. Cada um deles decide editar o mesmo arquivo no repositrio ao
mesmo tempo. Se Harry salvar suas alteraes no repositrio primeiro, ento possvel que (poucos
momentos depois) Sally possa acidentalmente sobrescrev-lo com a sua prpria nova verso do
arquivo. Embora a verso de Harry no seja perdida para sempre (porque o sistema se lembra de cada
mudana), todas as mudanas feitas por Harry no vo estar presentes na verso mais recente do
arquivo de Sally, porque ela nunca viu as mudanas de Harry's para comear. O trabalho de Harry
efetivamente se perdeu - ou pelo menos desapareceu da ltima verso do arquivo - e provavelmente
por acidente. Trata-se definitivamente de uma situao que queremos evitar!
A Soluo Lock-Modify-Unlock
Muitos sistemas de controle de verso usam o modelo lock-modify-unlock (travar-modificar-destravar)
para resolver o problema de vrios autores destrurem o trabalho uns dos outros. Neste modelo, o
repositrio permite que apenas uma pessoa de cada vez altere o arquivo. Essa poltica de exclusividade
gerenciada usando locks (travas). Harry precisa travar (lock) um arquivo antes que possa fazer
alteraes nele. Se Harry tiver travado o arquivo, ento Sally no poder trav-lo tambm, e portanto,
2
Conceitos Fundamentais
no poder fazer nenhuma alterao nele. Tudo que ela pode fazer ler o arquivo, e esperar que
Harry termine suas alteraes e destrave (unlock) o arquivo. Depois que Harry destravar o arquivo,
Sally poder ter a sua chance de travar e editar o arquivo. A figura Figura 1.3, A soluo lock-modify-
unlock demonstra essa soluo simples.
O problema com o modelo lock-modify-unlock que ele um pouco restritivo, muitas vezes se torna
um obstculo para os usurios:
Locks podem causar problemas administrativos. Algumas vezes Harry ir travar o arquivo e se
esquecer disso. Entretanto, devido a Sally ainda estar esperando para editar o arquivo, suas
mos esto atadas. E Harry ento sai de frias. Agora Sally tem que pedir a um administrador
para destravar o arquivo que Harry travou. Essa situao acaba causando uma srie de atrasos
desnecessrios e perda de tempo.
Locking pode causar serializao desnecessria. E se Harry est editando o comeo de um arquivo
de texto, e Sally simplesmente quer editar o final do mesmo arquivo? Essas mudanas no vo
se sobrepor afinal. Eles podem facilmente editar o arquivo simultaneamente, sem grandes danos,
assumindo que as alteraes sero apropriadamente fundidas depois. No h necessidade de se
trabalhar em turnos nessa situao.
Locking pode criar falsa sensao de segurana. Suponha que Harry trave e edite o arquivo A,
enquanto Sally simultaneamente trava e edita o arquivo B. Mas e se A e B dependem um do
outro, e se as mudanas feitas em cada so semanticamente incompatveis? Subitamente A e B
no funcionam juntos mais. O sistema de locking no foi suficientemente poderoso para prevenir o
3
Conceitos Fundamentais
problema - ainda que de certa forma tenha proporcionado uma falsa sensao de segurana. fcil
para Harry e Sally imaginar que travando os arquivos, cada um est comeando uma tarefa isolada
segura, e assim no se preocupar em discutir as incompatibilidades que viro com suas mudanas.
Locking freqentemente se torna um substituto para a comunicao real.
A Soluo Copy-Modify-Merge
O Subversion, CVS, e muitos outros sistemas de controle de verso usam um modelo de copy-
modify-merge (copiar-modificar-fundir) como uma alternativa ao locking. Nesse modelo, cada usurio
se conecta ao repositrio do projeto e cria uma cpia de trabalho pessoal (personal working copy,
ou cpia local) - um espelho local dos arquivos e diretrios do repositrio. Os usurios ento
trabalham simultaneamente e independentemente, modificando suas cpias privadas. Finalmente, as
cpias privadas so fundidas (merged) numa nova verso final. O sistema de controle de verso
freqentemente ajuda com a fuso, mas, no final, a interveno humana a nica capaz de garantir
que as mudanas foram realizadas de forma correta.
Aqui vai um exemplo. Digamos que Harry e Sally criaram cada um a sua cpia de trabalho de um mesmo
projeto, copiadas do repositrio. Eles trabalharam simultaneamente fazendo alteraes no arquivo A
nas suas prprias cpias. Sally salva suas alteraes no repositrio primeiro. Quando Harry tentar
salvar suas alteraes mais tarde, o repositrio vai inform-lo que seu arquivo A est desatualizado
(out-of-date). Em outras palavras, o arquivo A do repositrio foi de alguma forma alterado desde a
ltima vez que ele foi copiado. Ento Harry pede a seu programa cliente para ajud-lo a fundir (merge)
todas as alteraes do repositrio na sua cpia de trabalho do arquivo A. Provavelmente, as mudanas
de Sally no se sobrepem com as suas prprias; ento, uma vez que ele tiver ambos os conjuntos
de alteraes integrados, ele salva sua cpia de trabalho de volta no repositrio. As figuras Figura 1.4,
A soluo copy-modify-merge e Figura 1.5, A soluo copy-modify-merge (continuando) mostram
este processo.
4
Conceitos Fundamentais
O modelo copy-modify-merge pode soar um pouco catico, mas, na prtica, ele funciona de forma
bastante suave. Os usurios podem trabalhar em paralelo, nunca esperando uns pelos outros. Quando
eles trabalham nos mesmos arquivos, verifica-se que a maioria de suas alteraes simultneas no
se sobrepe afinal; conflitos no so muito freqentes. E a quantidade de tempo que eles levam para
resolver os conflitos geralmente muito menor que o tempo perdido no sistema de locking.
No fim, tudo se reduz a um fator crtico: a comunicao entre os usurios. Quando os usurios se
comunicam mal, tanto conflitos sintticos como semnticos aumentam. Nenhum sistema pode forar
os usurios a se comunicarem perfeitamente, e nenhum sistema pode detectar conflitos semnticos.
Portanto, no h como confiar nessa falsa sensao de segurana de que o sistema de locking vai
prevenir conflitos; na prtica, o lock parece inibir a produtividade mais do que qualquer outra coisa.
5
Conceitos Fundamentais
Subversion em Ao
Chegou a hora de passar do abstrato para o concreto. Nesta seo, ns mostraremos exemplos reais
de utilizao do Subversion
Mas existem algumas nuances no manuseio de URLs pelo Subversion que so notveis. Por exemplo,
URLs contendo o mtodo de acesso file:// (usado para repositrios locais) precisam, de acordo
com a conveno, ter como nome do servidor localhost ou nenhum nome de servidor:
Alm disso, usurios do esquema file:// em plataformas Windows precisaro utilizar um padro
de sintaxe no-oficial para acessar repositrios que esto na mesma mquina, mas em um drive
diferente do atual drive de trabalho. Qualquer uma das seguintes sintaxes de URLs funcionaro, sendo
X o drive onde o repositrio reside:
Na segunda sintaxe, voc precisa colocar a URL entre aspas de modo que o caractere de barra vertical
no seja interpretado como um pipe. Alm disso, note que a URL utiliza barras normais, enquanto no
Windows os caminhos (no URLs) utilizam barra invertida.
6
Conceitos Fundamentais
web browser comum, ele l e mostra o contedo do local examinando o sistema de arquivos
diretamente. Entretanto, os recursos do Subversion existem em um sistema de arquivos
virtual (veja Camada de Repositrio), e o seu browser no vai saber como interagir com
este sistema de arquivos.
Por ltimo, convm notar que o cliente Subversion vai automaticamente codificar as URLs conforme
necessrio, de forma semelhante a um browser. Por exemplo, se a URL contiver espaos ou algum
caractere no-ASCII:
...ento o Subversion ir aplicar "escape" aos caracteres inseguros e se comportar como se voc tivesse
digitado:
Se a URL contiver espaos, certifique-se de coloc-la entre aspas, de forma que o seu shell trate-a
inteiramente como um nico argumento do programa svn.
Uma cpia de trabalho do Subversion uma rvore de diretrios comum no seu sistema de arquivos
local, contendo uma coleo de arquivos. Voc pode editar esses arquivos conforme desejar, e se eles
so arquivos de cdigo fonte, voc pode compilar o seu programa a partir deles da maneira usual.
Sua cpia de local sua rea de trabalho privada: O Subversion jamais incorporar as mudanas de
terceiros ou tornar as suas prprias alteraes disponveis para os outros, at que voc explicitamente
o diga para fazer isso. Voc pode ter mltiplas cpias de trabalho do o mesmo projeto.
Aps voc ter feito algumas alteraes nos arquivos de sua cpia de trabalho e verificado que
elas funcionam corretamente, o Subversion lhe disponibiliza comandos para publicar (commit) suas
alteraes para as outras pessoas que esto trabalhando com voc no mesmo projeto (gravando no
repositrio). Se outras pessoas publicarem alteraes, o Subversion disponibiliza comandos para fundir
(merge) essas alteraes em sua cpia de trabalho (lendo do repositrio).
Uma cpia de trabalho tambm contm alguns arquivos extras, criados e mantidos pelo Subversion,
para ajud-lo a executar esse comandos. Em particular, cada diretrio em sua cpia local contm um
subdiretrio chamado .svn, tambm conhecido como o diretrio administrativo da cpia de local. Os
arquivos em cada diretrio administrativo ajudam o Subversion a reconhecer quais arquivos possuem
alteraes no-publicadas, e quais esto desatualizados em relao ao trabalho dos outros.
Um tpico repositrio Subversion freqentemente detm os arquivos (ou cdigo fonte) para vrios
projetos, geralmente, cada projeto um subdiretrio na rvore de arquivos do repositrio. Desse modo,
uma cpia de trabalho de um normalmente corresponder a uma sub-rvore particular do repositrio.
Por exemplo, suponha que voc tenha um repositrio que contenha dois projetos de software, paint
e calc. Cada projeto reside em seu prprio subdiretrio, como mostrado em Figura 1.6, O Sistema
de Arquivos do Repositrio.
7
Conceitos Fundamentais
Para obter uma cpia local, voc deve fazer check out de alguma sub-rvore do repositrio. (O termo
check out pode soar como algo que tem a ver com locking ou com reserva de recursos, o que no
verdade; ele simplesmente cria uma cpia privada do projeto para voc.) Por exemplo, se voc fizer
check out de /calc, voc receber uma cpia de trabalho como esta:
$ ls -A calc
Makefile integer.c button.c .svn/
A lista de letras A na margem esquerda indica que o Subversion est adicionando um certo nmero
de itens sua cpia de trabalho. Voc tem agora uma cpia pessoal do diretrio /calc do repositrio,
com uma entrada adicional - .svn - a qual detm as informaes extras que o Subversion precisa,
conforme mencionado anteriormente.
Suponha que voc faa alteraes no arquivo button.c. Visto que o diretrio .svn se lembra da data
de modificao e contedo do arquivo original, o Subversion tem como saber que voc modificou o
arquivo. Entretanto o Subversion no torna as suas alteraes pblicas at voc explicitamente lhe
dizer para fazer isto. O ato de publicar as suas alteraes conhecido como committing (ou checking
in) no repositrio.
Para publicar as suas alteraes para os outros, voc deve usar o comando commit do Subversion.
8
Conceitos Fundamentais
Agora as suas alteraes no arquivo button.c foram submetidas no repositrio, com uma nota
descrevendo as suas alteraes (especificamente voc corrigiu um erro de digitao). Se outros
usurios fizerem check out de /calc, eles vero suas alteraes na ltima verso do arquivo.
Suponha que voc tenha um colaborador, Sally, que tenha feito check out de /calc ao mesmo tempo
que voc. Quando voc publicar suas alteraes em button.c, a cpia de trabalho de Sally ser
deixada intacta; o Subversion somente modifica as cpias locais quando o usurio requisita.
Para atualizar o seu projeto, Sally pede ao Subversion para realizar um update na cpia de trabalho
dela, usando o comando update do Subversion. Isto ir incorporar as suas alteraes na cpia local
dela, bem como as alteraes de todos que tenham feito um commit desde que ela fez check out.
$ pwd
/home/sally/calc
$ ls -A
.svn/ Makefile integer.c button.c
$ svn update
U button.c
Updated to revision 57.
A sada do comando svn update indica que o Subversion atualizou o contedo de button.c. Note que
Sally no precisou especificar quais arquivos seriam atualizados; o Subversion usou as informaes no
diretrio .svn, e mais algumas no repositrio, para decidir quais arquivos precisariam ser atualizados.
URLs do Repositrio
Para obter mais informaes sobre como o Subversion analisa as URLs, veja URLs do
Repositrio Subversion. Para obter mais informaes sobre os diferentes tipos de servidores de
rede disponveis para Subversion, veja Captulo 6, Configurao do Servidor.
9
Conceitos Fundamentais
Revises
Uma operao svn commit publica as alteraes feitas em qualquer nmero de arquivos o diretrios
como uma nica transao atmica. Em sua cpia de trabalho, voc pode alterar o contedo de
arquivos; criar, deletar, renomear e copiar arquivos e diretrios; e ento submeter um conjunto completo
de alteraes em uma transao atmica.
Por transao atmica, nos entendemos simplesmente isto: Ou so efetivadas todas as alteraes
no repositrio, ou nenhuma delas. O Subversion tenta manter esta atomicidade em face de quebras ou
travamentos do programa ou do sistema, problemas de rede ou outras aes de usurios.
Cada vez que o repositrio aceita um commit, isto cria um novo estado na rvore de arquivos, chamado
reviso. Cada reviso assinalada com um nico nmero natural, incrementado de um em relao
reviso anterior. A reviso inicial de um repositrio recm criado numerada com zero, e consiste em
nada alm de um diretrio raiz vazio.
A figura Figura 1.7, O Repositrio ilustra uma forma simples para visualizar o repositrio. Imagine
um array de nmeros de revises, iniciando em zero, alongando-se da esquerda para a direita. Cada
nmero de reviso tem uma rvore de arquivos pendurada abaixo dela, e cada rvore um snapshot
da forma como o repositrio podia ser visto aps um commit.
10
Conceitos Fundamentais
importante notar que nem sempre as cpias de trabalho correspondem a uma nica reviso do
repositrio; elas podem conter arquivos de vrias revises diferentes. Por exemplo, suponha que voc
faa checkout de uma cpia de trabalho cuja reviso mais recente seja 4:
calc/Makefile:4
integer.c:4
button.c:4
Neste momento, este diretrio de trabalho corresponde exatamente reviso nmero 4 no repositrio.
Contudo, suponha que voc faa uma alterao no arquivo button.c, e publique essa alterao.
Assumindo que nenhum outro commit tenha sido feito, o seu commit ir criar a reviso 5 no repositrio,
e sua cpia de trabalho agora ir parecer com isto:
calc/Makefile:4
integer.c:4
button.c:5
Suponha que neste ponto, Sally publique uma alterao no arquivo integer.c, criando a reviso 6. Se
voc usar o comando svn update para atualizar a sua cpia de trabalho, ento ela ir parecer com isto:
calc/Makefile:6
integer.c:6
button.c:6
A alterao de Sally no arquivo integer.c ir aparecer em sua cpia de trabalho, e a sua alterao
no arquivo button.c ainda estar presente. Neste exemplo, o texto do arquivo Makefile idntico
nas revises 4, 5, e 6, mas o Subversion ir marcar a sua cpia do arquivo Makefile com a reviso 6
para indicar que a mesma a corrente. Ento, depois de voc fazer uma atualizao completa na sua
cpia de trabalho, ela geralmente corresponder exatamente a uma reviso do repositrio.
em qual reviso o seu arquivo local baseado (isto chamado de reviso local do arquivo), e
a data e a hora da ltima vez que a cpia local foi atualizada a partir do repositrio.
Dadas estas informaes, conversando com o repositrio, o Subversion pode dizer em qual dos
seguintes quatro estados um arquivo local est:
No-Modificado, e corrente
O arquivo no foi modificado no diretrio local, e nenhuma alterao foi publicada no repositrio
desde a reviso corrente. O comando svn commit no arquivo no far nada, e um comando svn
update tambm no..
No-Modificado, e desatualizado
O arquivo no foi alterado no diretrio local, mas foi alterado no repositrio. O arquivo pode ser
eventualmente atualizado, para sincroniz-lo com a ltima reviso pblica. O comando svn commit
11
Conceitos Fundamentais
no arquivo no ir fazer nada, mas o comando svn update ir trazer as ltimas alteraes para
a sua cpia local.
Isto pode soar como muito para acompanhar, mas o comando svn status mostrar para voc o estado
de qualquer item em seu diretrio local. Para maiores informaes sobre este comando, veja Obtendo
uma viso geral de suas alteraes.
O principal efeito colateral dessa regra significa que uma cpia local tem que fazer uma escriturao
extra para acompanhar revises mistas, bem como ser tolerante a misturas. Isso fica mais complicado
pelo fato de os diretrios tambm serem versionados.
Por exemplo, suponha que voc tenha uma cpia local inteiramente na reviso 10. Voc edita o arquivo
foo.html e ento realiza um comando svn commit, o qual cria a reviso 15 no repositrio. Aps o
commit acontecer, muitos novos usurios poderiam esperar que a cpia local estivesse na reviso 15,
mas este no o caso! Qualquer nmero de alteraes poderia ter acontecido no repositrio entre
as revises 10 e 15. O cliente nada sabe sobre essas alteraes no repositrio, pois voc ainda no
executou o comando svn update , e o comando svn commit no baixou as novas alteraes no
repositrio. Se por outro lado, o comando svn commit tivesse feito o download das novas alteraes
automaticamente, ento seria possvel que a cpia local inteira estivesse na reviso 15 - mas ento
ns teramos quebrado a regra fundamental onde push e pull permanecem como aes separadas.
Portanto a nica coisa segura que o cliente Subversion pode fazer marcar o arquivo - foo.html
com a reviso 15. O restante da cpia local permanece na reviso 10. Somente executando o comando
svn update as alteraes mais recentes no repositrio sero baixadas, o a cpia local inteira ser
marcada com a reviso 15.
Freqentemente, os novos usurios nem tomam conscincia de que suas cpias locais contm revises
mistas. Isso pode ser confuso, pois muitos comandos no cliente so sensveis s revises que eles
12
Conceitos Fundamentais
esto examinando. Por exemplo, o comando svn log usado para mostrar o histrico de alteraes em
um arquivo ou diretrio (veja Gerando uma lista de alteraes histricas). Quando o usurio invoca
este comando em um objeto da cpia local, ele espera ver o histrico inteiro do objeto. Mas se a reviso
local do objeto muito velha (muitas vezes porque o comando svn update no foi executado por um
longo tempo), ento o histrico da verso antiga do objeto que ser mostrado.
Em segundo lugar, voc no pode publicar alteraes em metadados de diretrios a menos que ele
esteja completamente atualizado. Voc ir aprender a anexar propriedades aos itens em Captulo 3,
Tpicos Avanados. Uma reviso em um diretrio local define um conjunto especfico de entradas e
propriedades, e assim, publicar alteraes em propriedades de um diretrio desatualizado pode destruir
propriedades que voc ainda no viu.
Sumrio
Ns abordamos uma srie de conceitos fundamentais do Subversion neste captulo:
Vimos alguns exemplos simples de como dois colaboradores podem utilizar o Subversion para
publicar e receber as alteraes um do outro, utilizando o modelo copy-modify-merge.
Neste ponto, voc deve ter uma boa idia de como o Subversion funciona no sentido mais geral. Com
este conhecimento, voc j deve estar pronto para avanar para o prximo captulo, que um relato
detalhado dos comandos e recursos do Subversion.
13
Captulo 2. Uso Bsico
Agora entraremos nos detalhes do uso do Subversion. Quando chegar ao final deste captulo, voc ser
capaz de realizar todas as tarefas necessrias para usar Subversion em um dia normal de trabalho.
Iniciar acessando seus arquivos que esto no Subversion, aps ter obtido uma cpia inicial de seu
cdigo. Guiaremos voc pelo processo de fazer modificaes e examinar estas modificaes. Tambm
ver como trazer mudanas feitas por outros para sua cpia de trabalho, examin-las, e resolver
quaisquer conflitos que possam surgir.
Note que este captulo no pretende ser uma lista exaustiva de todos os comandos do Subversion
antes, uma introduo conversacional s tarefas mais comuns que voc encontrar no Subversion.
Este captulo assume que voc leu e entendeu o Captulo 1, Conceitos Fundamentais e est
familiarizado com o modelo geral do Subversion. Para uma referncia completa de todos os comandos,
veja Captulo 9, Referncia Completa do Subversion.
Help!
Antes de continuar a leitura, aqui est o comando mais importante que voc precisar quando usar o
Subversion: svn help. O cliente de linha de comando do Subversion auto-documentadoa qualquer
momento, um rpido svn help SUBCOMANDO descrever a sintaxe, opes, e comportamento do
subcomando.
Opes vlidas:
-q [--quiet] : imprime o mnimo possvel
-N [--non-recursive] : opera somente em um diretrio
svn import
O comando svn import um modo rpido para copiar uma rvore de arquivos no versionada em
um repositrio, criando diretrios intermedirios quando necessrio. svn import no requer uma cpia
de trabalho, e seus arquivos so imediatamente submetidos ao repositrio. Isto tipicamente usado
quando voc tem uma rvore de arquivos existente que voc quer monitorar em seu repositrio
Subversion. Por exemplo:
14
Uso Bsico
Commit da reviso 1.
Note que aps a importao terminar, a rvore inicial no est convertida em uma cpia de trabalho.
Para comear a trabalhar, voc ainda precisa obter(svn checkout) uma nova cpia de trabalho da
rvore.
Voc aprender mais sobre tags e branches no Captulo 4, Fundir e Ramificar. Para detalhes e
como configurar mltiplos projetos, veja Estrutura de Repositrio e Planejando a Organizao do
Repositrio para ler mais sobre razes dos projetos.
Checkout Inicial
Na maioria das vezes, voc comea a usar um repositrio Subversion fazendo um checkout de seu
projeto. Fazer um checkout de um repositrio cria uma cpia de trabalho em sua mquina local. Esta
cpia contm o HEAD (reviso mais recente) do repositrio Subversion que voc especificou na linha
de comando:
15
Uso Bsico
O que h em um Nome?
O Subversion tenta arduamente no limitar o tipo de dado que voc pode colocar sob controle
de verso. O contedo dos arquivos e valores de propriedades so armazenados e transmitidos
como dados binrios, e a seo Tipo de Contedo do Arquivo diz-lhe como dar ao Subversion
uma dica de que operaes textuais no tm sentido para um arquivo em particular. H
umas poucas ocasies, porm, onde o Subversion coloca restries sobre as informaes nele
armazenadas.
Adicionalmente, caminhos de arquivos so usados como valores de atributos XML nas trocas
WebDAV, bem como em alguns arquivos internamente mantidos pelo Subversion. Isto significa
que os caminhos de arquivos podem somente conter caracteres aceitos no XML (1.0). Subversion
tambm probe os caracteres TAB, CR, e LF em nomes de caminhos para prevenir que caminhos
sejam quebrados nos diffs, ou em sadas de comandos como svn log ou svn status.
Embora parea que h muito o que recordar, na prtica estas limitaes raramente so um
problema. Enquanto suas configuraes regionais so compatveis com UTF-8, e voc no usar
caracteres de controle nos nomes dos caminhos, voc no ter problemas na comunicao com
o Subversion. O cliente de linha de comando d um pouco de ajuda extraele automaticamente
adiciona informaes de escape para os caracteres ilegais nos caminhos em URLs que voc
digita, para criar verses legalmente corretas para uso interno quando necessrio.
Embora os exemplos acima efetuem o checkout do diretrio trunk, voc pode facilmente efetuar o
checkout em qualquer nvel de subdiretrios de um repositrio especificando o subdiretrio na URL
do checkout:
$ svn checkout \
http://svn.collab.net/repos/svn/trunk/subversion/tests/cmdline/
A cmdline/revert_tests.py
A cmdline/diff_tests.py
A cmdline/autoprop_tests.py
A cmdline/xmltests
A cmdline/xmltests/svn-test.sh
Apesar de sua cpia de trabalho ser igual a qualquer outra coleo de arquivos e diretrios
em seu sistema, voc pode editar os arquivos a vontade, mas tem que informar o
Subversion sobre tudo o mais que voc fizer. Por exemplo, se voc quiser copiar ou mover
um item em uma cpia de trabalho, voc deve usar os comandos svn copy or svn move em
vez dos comandos copiar e mover fornecidos por ser sistema operacional. Ns falaremos
mais sobre eles posteriormente neste captulo.
16
Uso Bsico
A menos que voc esteja pronto para submeter a adio de novos arquivos ou diretrios, ou
modificaes nos j existentes, no h necessidade de continuar a notificar o servidor Subversion que
voc tenha feito algo.
Cada diretrio em uma cpia de trabalho contm uma rea administrativa, um subdiretrio
nomeado .svn. Normalmente, comandos de listagem de diretrios no mostraro este
subdiretrio, mas este um diretrio importante. Faa o que fizer, no apague ou modifique nada
nesta rea administrativa! O Subversion depende dela para gerenciar sua cpia de trabalho.
Se voc remover o subdiretrio .svn acidentalmente, o modo mais fcil de resolver o problema
remover todo o contedo do diretrio (uma excluso normal pelo sistema, no svn delete), ento
executar svn update a partir do diretrio pai. O cliente Subversion far novamente o download
do diretrio que voc excluiu, bem como uma nova rea .svn.
Alm de voc certamente poder obter uma cpia de trabalho com a URL do repositrio como nico
argumento, voc tambm pode especificar um diretrio aps a URL do repositrio. Isto coloca sua
cpia de trabalho no novo diretrio que voc informou. Por exemplo:
Isto colocar sua cpia de trabalho em um diretrio chamado subv em vez de um diretrio chamado
trunk como fizemos anteriormente. O diretrio subv ser criado se ele no existir.
Para desabilitar o cache de senhas para um comando especfico uma vez, passe a opo --no-auth-
cache na linha de comando. Para desabilitar permanentemente o cache, voc pode adicionar a linha
store-passwords = no no arquivo de configurao local do seu Subversion. Veja Armazenando
Credenciais no Cliente para maiores detalhes.
17
Uso Bsico
o documento raiz de um servidor web. Neste caso, apenas passe a opo --username na linha de
comando e o Subversion tentar autenticar como aquele usurio, pedindo uma senha se necessrio.
svn update
Fazer alteraes
svn add
svn delete
svn copy
svn move
svn status
svn diff
svn revert
svn update
svn resolved
svn commit
$ svn update
U foo.c
U bar.c
Updated to revision 2.
Neste caso, algum submeteu modificaes em foo.c e bar.c desde a ltima vez que voc atualizou,
e o Subversion atualizou sua cpia de trabalho para incluir estas modificaes.
18
Uso Bsico
Quando o servidor envia as alteraes para sua cpia de trabalho por meio do svn update, uma letra
exibida como cdigo prximo de cada item para que voc saiba que aes o Subversion executou para
deixar sua cpia de trabalho atualizada. Para conferir o que essas letras significam, veja svn update.
H dois tipos de alteraes que voc pode fazer em sua cpia de trabalho: alteraes nos arquivos e
alteraes na rvore. Voc no precisa avisar ao Subversion que voc pretende modificar um arquivo;
apenas faa suas alteraes usando seu editor de texto, suite de escritrio, programa grfico, ou
qualquer outra ferramenta que voc use normalmente. O Subversion automaticamente ir identificar
que arquivos foram modificados, ele tambm vai manipular arquivos binrios da mesma forma que
manipula arquivos de textoe to eficientemente quanto. Para alteraes na rvore, voc pode solicitar
ao Subversion que marque os arquivos e diretrios para remoo, adio, cpia ou movimentao
agendada. Estas alteraes tero efeito imediatamente em sua cpia de trabalho, mas nenhuma adio
ou remoo vai acontecer no repositrio at que voc registre tais alteraes.
Aqui est uma viso geral dos cinco subcomandos do Subversion que voc vai usar mais
frequentemente para fazer alteraes na rvore.
19
Uso Bsico
Operaes em URL funcionam desta maneira porque os comandos que operam em uma cpia
de trabalho podem usar a cpia de trabalho como uma espcie de rea de teste onde executar
suas alteraes antes de registr-las efetivamente no repositrio. Os comandos que operam em
URLs no dispem deste luxo, ento quando voc opera diretamente em uma URL, quaisquer
das aes acima resultam em commits imediatos.
Os comandos svn status, svn diff, e svn revert podem ser usados sem nenhum acesso a rede
mesmo se seu repositrio for disponibilizado em rede. Isto facilitar a gerncia de suas alteraes
em curso quando voc estiver sem conexo de rede, como enquanto estiver voando de avio,
3
andando de trem ou mesmo usando seu notebook na praia.
O Subversion faz isso mantendo caches privados das verses intactas de cada arquivo sob
controle de verso dentro dos diretrios das reas administrativas .svn. Isto permite ao
Subversion reportare revertermodificaes locais nestes arquivos sem precisar acessar
a rede. Este cache (chamado de texto-base) tambm possibilita ao Subversion enviar as
modificaes locais do usurio durante um commit ao servidor como um arquivo compactado
delta (ou diferena) sobre a verso original do arquivo. Ter este cache representa um grande
benefciomesmo se voc tiver uma conexo rpida de rede, muito mais rpido enviar apenas
as modificaes do arquivo que enviar todo o arquivo para o servidor.
O Subversion est sendo otimizado para ajudar voc com esta tarefa e capaz de fazer muitas
coisas sem se comunicar com o repositrio. Em particular, sua cpia de trabalho contm um cache
3
Daquelas que no tenham acesso sem-fio. Achou que ia nos pegar, hein?
20
Uso Bsico
escondido com uma cpia intacta de cada arquivo sob controle de verso dentro da rea .svn. Por
isso, o Subversion pode rapidamente lhe mostrar como seus arquivos de trabalho mudaram, ou mesmo
permitir a voc desfazer suas alteraes sem contactar o repositrio.
Voc provavelmente costuma usar cvs update para ver que alteraes voc fez em sua cpia de
trabalho. O svn status lhe dar toda a informao de que voc precisa sobre o que mudou em
sua cpia de trabalhosem acessar o repositrio ou potencialmente incorporar novas alteraes
publicadas por outros usurios.
No Subversion, update faz apenas issoele atualiza sua cpia de trabalho com quaisquer
alteraes registradas no repositrio desde a ltima vez que voc atualizou sua cpia de trabalho.
Voc deve quebrar o hbito de usar o comando update para ver que alteraes locais voc fez.
Se voc executar svn status no topo de cpia de trabalho sem argumentos, ele ir detectar todas as
alteraes de arquivos e rvores que voc fez. Abaixo esto uns poucos exemplos dos cdigos mais
comuns de estado que o svn status pode retornar. (Note que o texto aps # no exibido pelo svn
status.)
Neste formato de sada svn status exibe seis colunas de caracteres, seguidas de diversos espaos
em branco, seguidos por um nome de arquivo ou diretrio. A primeira coluna indica o estado do arquivo
ou diretrio e/ou seu contedo. Os cdigos listados so:
A item
O arquivo, diretrio, ou link simblico item est agendado para ser adicionado ao repositrio.
C item
O arquivo item est em um estado de conflito. Isto , as modificaes recebidas do servidor
durante um update se sobrepem s alteraes locais feitas por voc em sua cpia de trabalho.
Voc deve resolver este conflito antes de submeter suas alteraes ao repositrio.
D item
O arquivo, diretrio, ou link simblico item est agendado para ser excludo do repositrio.
M item
O contedo do arquivo item foi modificado.
Se voc passar um caminho especfico para o svn status, voc vai obter informao apenas sobre
aquele item:
O svn status tambm tem uma opo --verbose (-v), a qual vai lhe mostrar o estado de cada item
em sua cpia de trabalho, mesmo se no tiver sido modificado:
21
Uso Bsico
$ svn status -v
M 44 23 sally README
44 30 sally INSTALL
M 44 20 harry bar.c
44 18 ira stuff
44 35 harry stuff/trout.c
D 44 19 ira stuff/fish.c
44 21 sally stuff/things
A 0 ? ? stuff/things/bloo.h
44 36 harry stuff/things/gloo.c
Esta a forma estendida da sada do svn status. As letras na primeira coluna significam o mesmo
que antes, mas a segunda coluna mostra a reviso de trabalho do item. A terceira e quarta coluna
mostram a reviso na qual o item sofreu a ltima alterao, e quem o modificou.
Nenhuma das execues anteriores de svn status contactam o repositrioao invs disso, elas
comparam os metadados no diretrio .svn com a cpia de trabalho. Finalmente, existe a opo --
show-updates (-u), que se conecta ao repositrio e adiciona informao sobre as coisas que esto
desatualizadas:
$ svn status -u -v
M * 44 23 sally README
M 44 20 harry bar.c
* 44 35 harry stuff/trout.c
D 44 19 ira stuff/fish.c
A 0 ? ? stuff/things/bloo.h
Status against revision: 46
Perceba os dois asteriscos: se voc executar svn update neste ponto, voc dever receber alteraes
nos arquivos README e trout.c. Isto lhe d alguma informao bastante tilvoc vai precisar
atualizar e obter as modificaes do servidor no arquivo README antes de executar um commit, ou o
repositrio vai rejeitar sua submisso por ter estar desatualizada. (Mais sobre este assunto mais tarde.)
O svn status pode exibir muito mais informao sobre os arquivos e diretrios em sua cpia de trabalho
do que o que mostramos aquipara uma descrio exaustiva do svn status e de sua sada, veja svn
status.
$ svn diff
Index: bar.c
===================================================================
--- bar.c (revision 3)
+++ bar.c (working copy)
@@ -1,7 +1,12 @@
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <stdio.h>
int main(void) {
22
Uso Bsico
Index: README
===================================================================
--- README (revision 3)
+++ README (working copy)
@@ -193,3 +193,4 @@
+Note to self: pick up laundry.
Index: stuff/fish.c
===================================================================
--- stuff/fish.c (revision 1)
+++ stuff/fish.c (working copy)
-Welcome to the file known as 'fish'.
-Information on fish will be here soon.
Index: stuff/things/bloo.h
===================================================================
--- stuff/things/bloo.h (revision 8)
+++ stuff/things/bloo.h (working copy)
+Here is a new file to describe
+things about bloo.
O comando svn diff produz esta sada comparando seus arquivos de trabalho com a cpia intacta
em cache que fica dentro da rea .svn. Os arquivos marcados para adio so exibidos com todo o
texto adicionado, e os arquivos marcados para excluso so exibidos com todo o texto excludo.
A sada exibida no formato diff unificado. Isto , linhas removidas so iniciadas com - e linhas
adicionadas so iniciadas com +. O svn diff tambm exibe o nome do arquivo e uma informao
de deslocamento (offset) que til para o programa patch, de forma que voc pode gerar
atualizaes (patches) redirecionando a sada do diff para um arquivo:
Voc pode, por exemplo, enviar um arquivo de atualizao por e-mail para outro desenvolvedor para
reviso ou teste prvio antes de submeter.
O Subversion usa seu mecanismo interno de diff, o qual gera o formato diff unificado, por padro.
Se voc quiser esta sada em um formato diferente, especifique um programa diff externo usando --
diff-cmd e passe as opes de sua preferncia para ele com --extensions (-x). Por exemplo,
para ver as diferenas locais no arquivo foo.c no formato de sada de contexto ao mesmo tempo
ignorando diferenas de maisculas e minsculas, voc poderia executar svn diff --diff-cmd /usr/bin/
diff --extensions '-i' foo.c.
23
Uso Bsico
O Subversion reverte o arquivo para seu estado antes da alterao sobrescrevendo-o com a cpia
intacta que est na rea .svn. Mas atente tambm que svn revert pode desfazer quaisquer
operaes agendadaspor exemplo, voc pode decidir que voc no quer mais adicionar um novo
arquivo:
svn revert ITEM tem exatamente o mesmo efeito de se excluir o ITEM de sua cpia de
trabalho e ento executar svn update -r BASE ITEM. Porm, se voc estiver revertendo
um arquivo, o svn revert tem uma notvel diferenaele no precisa se comunicar com
o repositrio para restaurar o seu arquivo.
$ svn update
U INSTALL
G README
C bar.c
Updated to revision 46.
J o C significa Conflito. Isto quer dizer que as modificaes do servidor se sobrepem com as suas
prprias, e que agora voc precisa escolher entre elas manualmente.
24
Uso Bsico
Sempre que um conflito ocorre, normalmente acontecem trs coisas para ajudar voc a compreender
e resolver este conflito:
O Subversion exibe um C durante o update, e lembra que o arquivo est num estado de conflito.
Para cada arquivo em conflito, o Subversion mantm trs arquivos extras no-versionados em sua
cpia de trabalho:
filename.mine
Este o seu arquivo como o que existia em sua cpia de trabalho antes de voc atualiz-la
isto , sem as marcaes de conflito. Este arquivo tem apenas as suas ltimas alteraes feitas
nele. (Se o Subversion considerar que o arquivo no mesclvel, ento o arquivo .mine no
criado, uma vez que seria idntico ao arquivo de trabalho.)
filename.rOLDREV
Este o arquivo que estava na reviso BASE antes de voc atualizar sua cpia de trabalho. Isto
, o arquivo em que voc pegou do repositrio antes de fazer suas ltimas alteraes.
filename.rNEWREV
Este o arquivo que seu cliente Subversion acabou de receber do servidor quando voc atualizou
sua cpia de trabalho. Este arquivo corresponde reviso HEAD do repositrio.
Aqui, OLDREV o nmero de reviso do arquivo em seu diretrio .svn e NEWREV o nmero de
reviso do repositrio HEAD.
Como exemplo, Sally faz modificaes no arquivo sandwich.txt no repositrio. Harry acabou de
alterar o arquivo em sua cpia de trabalho e o submeteu. Sally atualiza sua cpia de trabalho antes de
executar um commit o que resulta em um conflito:
$ svn update
C sandwich.txt
Updated to revision 2.
$ ls -1
sandwich.txt
sandwich.txt.mine
sandwich.txt.r1
sandwich.txt.r2
Neste ponto, o Subversion no vai deixar que voc submeta o arquivo sandwich.txt at que os trs
arquivos temporrios sejam removidos.
Se voc tiver um conflito, voc precisa fazer uma dessas trs coisas:
Fazer uma cpia de um dos arquivos temporrios em cima de seu arquivo de trabalho.
Executar svn revert <filename> para se desfazer de todas as suas modificaes locais.
25
Uso Bsico
Uma vez que voc tenha resolvido o conflito, voc precisa informar isto ao Subversion executando
svn resolved. Isso remove os trs arquivos temporrios e o Subversion no mais considera o arquivo
4
como estando em conflito.
Mesclando Conflitos na Mo
Mesclar conflitos na mo pode ser algo bem intimidante na na primeira vez que voc tentar, mas com
um pouco de prtica, pode ser tornar to fcil quanto andar de bicicleta.
Veja um exemplo. Por um problema de comunicao, voc e Sally, sua colaboradora, ambos editam
o arquivo sandwich.txt ao mesmo tempo. Sally submete suas alteraes, e quando voc atualizar
sua cpia de trabalho, voc ter um conflito e precisar editar o arquivo sandwich.txt para resolv-
los. Primeiro, vamos dar uma olhada no arquivo:
$ cat sandwich.txt
Top piece of bread
Mayonnaise
Lettuce
Tomato
Provolone
<<<<<<< .mine
Salami
Mortadella
Prosciutto
=======
Sauerkraut
Grilled Chicken
>>>>>>> .r2
Creole Mustard
Bottom piece of bread
<<<<<<< .mine
Salami
Mortadella
Prosciutto
=======
O texto entre o segundo e terceiro conjuntos de marcaes de conflito o texto das alteraes
submetidas por Sally:
=======
Sauerkraut
Grilled Chicken
>>>>>>> .r2
4
Voc sempre pode remover os arquivos temporrios voc mesmo, mas voc vai realmente querer fazer isso quando o
Subversion pode fazer por voc? Ns achamos que no.
26
Uso Bsico
Normalmente voc no vai querer apenas remover as marcaes e as alteraes de Sallyela ficaria
terrivelmente surpresa quando o sanduche chegar e no for o que ela queria. Ento este o momento
em que voc pega o telefone ou atravessa o escritrio e explica para Sally o que voc no gosta de
5
sauerkraut como iguaria italiana. Uma vez que vocs tenham chegado a um acordo sobre as alteraes
que sero mantidas, edite seu arquivo e remova as marcaes de conflito.
Agora execute svn resolved, e voc estar pronto para submeter suas alteraes:
Veja que o svn resolved, ao contrrio muitos dos outros comandos que abordamos neste captulo,
precisa de um argumento. Em todo caso, voc vai querer ter cuidado e s executar svn resolved
quando tiver certeza de ter resolvido o conflito em seu arquivoquando os arquivos temporrios
forem removidos, o Subversion vai deixar que voc submeta o arquivo ainda que ele permanea com
marcaes de conflito.
Se voc se confundiu ao editar o arquivo conflituoso, voc sempre pode consultar os trs arquivos que
o Subversion cria para voc em sua cpia de trabalhoinclusive o seu arquivo como era antes de voc
atualizar. Voc ainda pode usar uma ferramenta interativa de mesclagem de terceiros para examinar
esses trs arquivos.
$ svn update
C sandwich.txt
Updated to revision 2.
$ ls sandwich.*
sandwich.txt sandwich.txt.mine sandwich.txt.r2 sandwich.txt.r1
$ cp sandwich.txt.r2 sandwich.txt
$ svn resolved sandwich.txt
27
Uso Bsico
$ ls sandwich.*
sandwich.txt
Perceba que ao reverter um arquivo em conflito, voc no precisa executar svn resolved.
O comando svn commit envia todas as suas modificaes para o servidor. Quando voc registra uma
alterao, voc precisa informar uma mensagem de log, descrevendo sua alterao. Sua mensagem
de log ser anexada nova reviso que voc criar. Se sua mensagem de log for breve, voc pode
querer escrev-la na prpria linha de comando usando a opo --message (ou -m):
No entanto, se voc estiver escrevendo sua mensagem conforme for trabalhando, voc pode querer
informar ao Subversion para obter a mensagem a partir de um arquivo indicando-o com a opo --
file (-F):
Se voc no especificar a opo --message nem a --file, o Subversion vai abrir automaticamente
seu editor de texto preferido (veja a seo editor-cmd em Configurao) para compor a mensagem
de log.
Se voc estiver escrevendo a mensagem de log em seu editor neste ponto e decidir
cancelar seu commit, voc pode apenas sair do seu editor sem salvar suas alteraes.
Se voc j salvou sua mensagem de log, simplesmente exclua o texto, salve novamente,
ento feche o programa.
$ svn commit
Waiting for Emacs...Done
O repositrio no sabe nem mesmo se importa se suas modificaes sequer fazem sentido como
um todo; ele apenas garante que ningum mais tenha modificado nada dos mesmos arquivos que
voc enquanto voc no estava olhando. Se algum tiver feito isso, o commit todo ir falhar com uma
mensagem informando a voc que um ou mais de seus arquivos est desatualizado:
28
Uso Bsico
(Os dizeres exatos desta mensagem de erro dependem de qual protocolo de rede e qual servidor voc
est usando, mas a idia a mesma em todos os casos.)
Neste ponto, voc precisa executar svn update, lidar com quaisquer mesclagens ou conflitos
resultantes, e tentar executar o commit novamente.
Isto conclui o ciclo bsico de trabalho no uso do Subversion. H muitos outros recursos no Subversion
que voc pode usar para gerenciar seu repositrio e sua cpia de trabalho, mas muito de seu uso
cotidiano do Subversion vai envolver apenas os comandos que discutimos neste captulo. Vamos,
entretanto, abordar mais uns poucos comandos que voc tambm pode usar bastante.
Examinando o Histrico
O seu repositrio Subversion como uma mquina do tempo. Ele mantm um registro de cada
modificao submetida, e permite a voc explorar este histrico examinando verses anteriores de
seus arquivos e diretrios bem como os metadados a eles relacionados. Com apenas um comando do
Subversion, voc pode deixar o repositrio (ou restaurar uma cpia de trabalho existente) exatamente
como ele era em uma certa data ou em um nmero de reviso no passado. Porm, algumas vezes
voc s quer revisitar o passado ao invs de retornar ao passado.
H uma srie de comandos que podem lhe mostrar dados histricos do repositrio:
svn log
Exibe bastante informao: mensagens de log com informaes de data e autor anexadas s
revises, e quais caminhos mudaram em cada reviso.
svn diff
Exibe detalhes a nvel das linhas de uma alterao em particular.
svn cat
Recupera um arquivo como ele era em uma dada reviso e exibe seu contedo na tela.
svn list
Exibe os arquivos em um diretrio para uma dada reviso.
$ svn log
------------------------------------------------------------------------
r3 | sally | Mon, 15 Jul 2002 18:03:46 -0500 | 1 line
Initial import
------------------------------------------------------------------------
29
Uso Bsico
Veja que as mensagens de log so exibidas em ordem cronolgica inversa por padro. Se voc quiser
ver um intervalo de revises em uma ordem especfica, ou apenas uma nica reviso, utilize a opo
--revision (-r):
Voc tambm pode examinar o histrico de logs de um nico arquivo ou diretrio. Por exemplo:
Isto vai exibir as mensagens de log apenas para aquelas revises nas quais o arquivo de trabalho (ou
a URL) mudaram.
Se voc quiser ainda mais informao sobre um arquivo ou diretrio, o svn log tambm aceita uma
opo --verbose (-v). Como o Subversion lhe permite mover e copiar arquivos e diretrios,
importante ser capaz de rastrear alteraes de caminhos no sistema de arquivos, ento no modo
verboso, o svn log vai incluir na sua sada uma lista dos caminhos alterados em uma reviso:
$ svn log -r 8 -v
------------------------------------------------------------------------
r8 | sally | 2002-07-14 08:15:29 -0500 | 1 line
Changed paths:
M /trunk/code/foo.c
M /trunk/code/bar.h
A /trunk/code/doc/README
------------------------------------------------------------------------
O svn log tambm aceita uma opo --quiet (-q), que suprime o corpo da mensagem de log. Quando
combinada com a opo --verbose, ela apresentar apenas os nomes dos arquivos mudados.
Aps trabalhar um pouco com o Subversion, muitos usurios vo se deparar com algo como:
$ svn log -r 2
------------------------------------------------------------------------
$
primeira vista, isto parece ser um erro. Mas lembre-se de que as revises se aplicam a todo o
repositrio, ao passo que o svn log atua em um caminho no repositrio. Se voc no informar um
caminho, o Subversion usa o diretrio atual como argumento padro. Como resultado, se voc
estiver em um subdiretrio de sua cpia de trabalho e tentar ver o log de uma reviso em que
nem o diretrio nem qualquer item nele contido mudou, o Subversion vai lhe mostrar um log vazio.
Se voc quiser ver o que mudou naquela reviso, experimente chamar o svn log diretamente na
URL de mais alto nvel de seu repositrio, como em svn log -r 2 http://svn.collab.net/repos/svn.
30
Uso Bsico
Na realidade, tem-se que existem trs usos distintos para o svn diff:
$ svn diff
Index: rules.txt
===================================================================
--- rules.txt (revision 3)
+++ rules.txt (working copy)
@@ -1,4 +1,5 @@
Be kind to others
Freedom = Responsibility
Everything in moderation
-Chew with your mouth open
+Chew with your mouth closed
+Listen when others are speaking
$
31
Uso Bsico
Uma forma mais conveniente de se comparar uma reviso com sua anterior usando --change (-c):
Por ltimo, voc pode comparar revises no repositrio at quando voc no tem uma cpia de trabalho
em sua mquina local, apenas incluindo a URL apropriada na linha de comando:
svn cat
Se voc quiser visualizar uma verso antiga de um arquivo e no necessariamente as diferenas entre
dois arquivos, voc pode usar o svn cat:
32
Uso Bsico
svn list
O comando svn list lhe mostra que arquivos esto no repositrio atualmente sem carreg-los para
sua mquina local:
Se voc preferir uma listagem mais detalhada, inclua a opo --verbose (-v) para ter uma sada
desta forma:
As colunas lhe dizem a reviso na qual o arquivo ou diretrio sofreu a ltima (mais recente) modificao,
o usurio que o modificou, seu tamanho, se for um arquivo, a data desta ltima modificao, e o nome
do item.
Um svn list sem argumentos vai se referir URL do repositrio associada ao diretrio
atual da cpia de trabalho, e no ao diretrio local da cpia de trabalho. Afinal, se voc
quer listar o contedo de seu diretrio local, voc pode usar um simples ls (ou comando
equivalente em seu sistema no-Unix).
Muitos novatos no Subversion tentam usar o svn update deste exemplo para desfazer
modificaes submetidas, mas isso no funciona j que voc no pode no pode submeter
alteraes que voc obteve voltando uma cpia de trabalho se seus arquivos modificados
tiverem novas revises. Veja Ressucitando Itens Excludos para uma descrio de como
desfazer um commit.
Finalmente, se voc estiver criando uma verso final e quiser empacotar seus arquivos do Subversion
mas no gostaria de incluir os incmodos diretrios .svn de forma nenhuma, ento voc pode usar
o comando svn export para criar uma cpia local de todo o contedo de seu repositrio mas sem os
6
Viu? Ns dissemos que o Subversion era uma mquina do tempo.
33
Uso Bsico
diretrios .svn. Da mesma forma que com o svn update e svn checkout, voc tambm pode incluir
a opo --revision ao svn export:
E isto exatamente o que o svn cleanup faz: varre sua cpia de trabalho e executa quaisquer arquivos
de log que tenham ficado, removendo as travas da cpia de trabalho durante o processo. Se acaso o
Subversion lhe disser que alguma parte de sua cpia de trabalho est travada (locked), ento este
o comando que voc dever rodar. E ainda, o svn status mostrar um L prximo dos itens que
estiverem travados:
$ svn status
L somedir
M somedir/foo.c
$ svn cleanup
$ svn status
M somedir/foo.c
No confunda estas travas da cpia de trabalho com as travas ordinrias que os usurios do Subversion
criam ao usar o modelo de controle de verso travar-modificar-destravar; veja Os trs significados de
trava para mais esclarecimentos.
Sumrio
Agora ns cobrimos a maioria dos comandos do cliente Subversion. As excees notveis so
os comandos relacionados com ramificao e mesclagem (veja Captulo 4, Fundir e Ramificar) e
propriedades (veja Propriedades). Entretanto, voc pode querer tirar um momento para folhear
Captulo 9, Referncia Completa do Subversion para ter uma idia de todos os muitos comandos
diferentes que o Subversion possuie como voc pode us-los para tornar seu trabalho mais fcil.
34
Captulo 3. Tpicos Avanados
Se voc est lendo este livro captulo por captulo, do inicio ao fim, voc deve agora ter adquirido
conhecimentos suficientes para usar o cliente Subversion para executar a operaes de controle de
vero mais comuns. Voc entendeu como obter uma cpia de trabalho de um repositrio Subversion.
Voc sente-se confortvel para submeter e receber mudanas usando as funes svn commit e svn
update. Voc provavelmente desenvolveu um reflexo que lhe impele a executar o comando svn status
quase inconscientemente. Para todos os intentos e propsitos, voc est pronto para usar o Subversion
em um ambiente tpico.
Mas o conjunto de recursos do Subversion no para nas operaes de controle de verso comuns.
Ele tem outras pequenas funcionalidades alm de comunicar mudanas de arquivos e diretrios para
e a partir de um repositrio central.
Este captulo destaca alguns dos recursos do Subversion que, apesar de importantes, no fazem
pare da rotina diria de um usurio tpico. Ele assume que voc est familiarizado com capacidades
bsicas de controle de verso sobre arquivos e diretrios. Se no est, voc vai querer ler primeiro
o Captulo 1, Conceitos Fundamentais e Captulo 2, Uso Bsico. Uma vez que voc tenha dominado
estes fundamentos e terminado este captulo, voc ser um usurio avanado do Subversion!
Especificadores de Reviso
Como voc viu em Revises, nmeros de reviso no Subversion so bastante simplesnmeros
inteiros que aumentam conforme voc submete mais alteraes em seus dados versionados. Assim,
no demora muito para que voc no se lembre mais do que aconteceu exatamente em toda uma
dada reviso. Felizmente, o tpico ciclo de trabalho no Subversion frequentemente no precisa que
voc informe nmeros de reviso arbitrrios para as operaes que voc executa no Subversion. Para
aquelas operaes que precisam de um especificador de reviso, voc geralmente informa um nmero
de reviso que voc viu em um e-mail da submisso (e-mail de commit), na sada de alguma outra
operao do Subversion, ou em algum outro contexto que poderia fazer sentido para aquele nmero
em particular.
Mas ocasionalmente, voc precisa de um marco de um momento no tempo para o qual voc no
tem ainda um nmero de reviso memorizado ou em mos. Neste caso, alm de nmeros inteiros
de reviso, o svn permite como entrada algumas formas de especificadores de revisotermos de
reviso, e datas de reviso.
Termos de Reviso
O cliente Subversion entende um conjunto de termos de reviso. Estes termos podem ser usados no
lugar dos argumentos inteiros para a opo --revision (-r), e so resolvidos para nmeros de
reviso especficos pelo Subversion:
HEAD
A ltima (ou mais recente) reviso no repositrio.
BASE
O nmero de reviso de um item em uma cpia de trabalho. Se o item tiver sido modificado
localmente, a verso BASE refere-se forma como o item estaria sem estas modificaes locais.
35
Tpicos Avanados
COMMITTED
A reviso mais recente anterior, ou igual a, BASE, na qual o item foi modificado.
PREV
A reviso imediatamente anterior ltima reviso na qual o item foi modificado. Tecnicamente, isto
se resume a COMMITTED-1.
Como pode ser deduzido de suas descries, os termos de reviso PREV, BASE, e COMMITTED so
usados apenas quando se referirem a um caminho numa cpia de trabalhoeles no se aplicam a
URLs do repositrio. HEAD, por outro lado, pode ser usado em conjunto para qualquer um desses tipos
de caminho.
Datas de Reviso
Nmeros de reviso no revelam nada sobre o mundo fora do sistema de controle de verso, mas
algumas vezes voc precisa correlacionar um momento em tempo real com um momento no histrico de
revises. Para facilitar isto, a opo --revision (-r) tambm pode aceitar especificadores de data
delimitados por chaves ({ e }) como entrada. O Subversion aceita datas e horas no padro ISO-8601,
alm de alguns poucos outros. Aqui esto alguns exemplos. (Lembre-se de usar aspas para delimitar
quaisquer datas que contenham espaos.)
36
Tpicos Avanados
Quando voc especifica uma data, o Subversion resolve aquela data para a reviso mais recente do
repositrio com aquela data, e ento continua a operao usando o nmero de reviso obtido:
Se voc especificar uma nica data como uma reviso sem especificar uma hora do dia (por
exemplo 2006-11-27), voc pode pensar que o Subversion deveria dar a voc a ltima reviso
que tivesse ocorrido em 27 de novembro. Entretanto, voc vai obter uma reviso do dia 26, ou
mesmo anterior a isso. Lembre-se de que o Subversion vai procurar a reviso do repositrio mais
recente que a da data que voc informou. Se voc informar uma data sem a parte de horrio,
como 2006-11-27, o Subversion assume um horrio de 00:00:00, ento procurar pela reviso
mais recente no vai retornar nada do dia 27.
Se voc quiser incluir o dia 27 em sua busca, voc pode tanto especificar o dia 27 com o horrio
({"2006-11-27 23:59"}), ou apenas especificar o prximo dia ({2006-11-28}).
Voc tambm pode usar intervalos de datas. O Subversion vai encontrar todas as revises entre as
datas, inclusive:
Uma vez que a data e horrio (timestamp) de uma reviso armazenada como uma
propriedade da reviso no-versionada e passvel de alterao (veja Propriedades,
essas informaes de data e horrio podem ser modificadas para representar falsificaes
completas da cronologia real, ou mesmo podem ser removidas inteiramente. A capacidade
do Subversion de converter corretamente datas de reviso em nmeros de reviso
depende da manuteno da ordem seqencial desta informao temporalquanto mais
recente uma reviso, mais recente sua informao de data e horrio. Se esta ordenao
no for mantida, voc perceber que tentar usar datas para especificar intervalos de reviso
em seu repositrio nem sempre retornar os dados que voc espera.
Propriedades
Ns j abordamos em detalhes como o Subversion armazena e recupera vrias verses de arquivos
e diretrios em seu repositrio. Captulos inteiros tm sido focados nesta parte mais fundamental das
funcionalidades providas pela ferramenta. E se o suporte a versionamento parar por a, o Subversion
ainda seria completo do ponto de vista do controle de verso.
37
Tpicos Avanados
como tabelas de duas colunas que mapeiam nomes de propriedades a valores arbitrrios anexados a
cada item em sua cpia de trabalho. Falando de uma forma geral, os nomes e valores das propriedades
podem ser quaisquer coisas que voc queira, com a restrio de que os nomes devem ser texto
legvel por humanos. E a melhor parte sobre estas propriedades que elas, tambm, so versionadas,
tal como o contedo textual de seus arquivos. Voc pode modificar, submeter, e reverter alteraes
em propriedades to facilmente como em qualquer alterao no contedo de arquivos. E o envio e
recebimento das modificaes em propriedades ocorrem como parte de suas operaes de submisso
(commit) e atualizao (update)voc no tem que mudar seus procedimentos bsicos para utiliz-los.
Propriedades aparecem em qualquer parte no Subversion, tambm. Da mesma maneira que arquivos
e diretrios podem ter nomes de propriedades arbitrrios e valores anexados a eles, cada reviso
como um todo pode ter propriedades arbitrrias anexadas a si prpria. As mesmas restries se
aplicam;mdash;nomes que sejam legveis por humanos e valores com qualquer coisa que voc
queira, inclusive dados binrios. A principal diferena que as propriedades de uma reviso no so
versionadas. Em outras palavras, se voc modificar o valor de, ou excluir uma propriedade de uma
reviso, no h uma forma de recuperar seu valor anterior no Subversion.
Nesta seo, vamos examinar a utilidadetanto para os usurios quanto para o prprio Subversion
do suporte a propriedades. Voc vai aprender sobre os subcomandos de svn que lidam com
propriedades, e como alteraes nas propriedades afetam seu fluxo de trabalho normal no Subversion.
Digamos que voc quer elaborar um website que armazene muitas fotos digitais, e as exiba com
legendas e a data e hora em que foram tiradas. S que seu conjunto de fotos est mudando
constantemente, e voc gostaria de automatizar este site tanto quanto possvel. Estas fotos podem ser
um pouco grandes, ento, como muito comum em sites desse tipo, voc quer disponibilizar prvias em
miniatura de suas fotos para os visitantes de seu site.
Agora, voc pode ter esta funcionalidade usando arquivos tradicionais. Isto , voc pode ter seus
arquivos image123.jpg e image123-thumbnail.jpg lado a lado em um diretrio. Ou se voc
quiser manter os mesmos nomes de arquivos, voc poderia ter suas miniaturas em um diretrio
diferente, como thumbnails/image123.jpg. Voc tambm pode armazenar suas legendas e datas
e horrios de forma parecida, tambm separadas do arquivo da foto original. Mas o problema aqui
que o conjunto de arquivos aumenta aos mltiplos para cada nova foto adicionada ao site.
38
Tpicos Avanados
Agora considere o mesmo website desenvolvido de forma a fazer uso das propriedades de arquivo
do Subversion. Imagine ter um nico arquivo de imagem, image123.jpg, e ento propriedades
definidas neste arquivo chamadas caption, datestamp, ou mesmo thumbnail (respectivamente
para a legenda, data e hora, e miniatura da imagem). Agora sua cpia de trabalho parece muito mais
gerencivelde fato, numa primeira visualizao, no parece haver nada mais alm dos arquivos de
imagem l dentro. Mas seus scripts de automao sabem mais. Eles sabes que podem usar o svn
(ou melhor ainda, eles podem usar a linguagem incorporada ao Subversionveja Usando as APIs)
para para extrair as informaes extras que seu site precisa exibir sem ter que l-las de um arquivo de
ndices nem precisar de preocupar em estar manipulando caminhos dos arquivos.
Tentar localizar uma propriedade especfica de uma reviso geralmente envolve executar uma
busca linear ao longo de todas as revises do repositrio, perguntando para cada reviso, "Voc
tem a propriedade que eu estou procurando?" Tentar encontrar uma propriedade versionada
complicado, tambm, e quase sempre envolve um recursivo svn propget ao longo de toda a
cpia de trabalho. Esta situao pode at no ser to ruim quando uma busca linear por todas as
revises. Mas certamente deixa muito a desejar tanto em termos de performance quanto mesmo
da probabilidade de sucesso, especialmente se o escopo de sua busca envolver uma cpia de
trabalho da raiz de seu repositrio.
Mas isto resulta em outra dificuldade. O Subversion no prov ainda uma mecanismo de modelos
para mensagens de log, que poderia ajudar bastante os usurios a manter consistentemente o
formato de seus metadados includos em suas mensagens de log.
Manipulando Propriedades
O comando svn oferece algumas poucas maneiras de se adicionar ou modificar propriedades de
arquivos e diretrios. Para propriedades com valores pequenos, legveis por humanos, talvez a forma
mais simples de se adicionar uma nova propriedade especificar o nome e o valor da propriedade na
linha de comando com o subcomando propset.
39
Tpicos Avanados
Mas sempre podemos contar com a flexibilidade que o Subversion oferece para seus valores de
propriedades. E se voc est planejando ter texto com mltiplas linhas, ou mesmo valores binrios
para o valor da propriedade, voc provavelmente no vai informar este valor pela linha de comando.
Ento, o subcomando propset leva uma opo --file (-F) para especificar o nome de um arquivo
que contm o valor para a nova propriedade.
H algumas restries sobre os nomes que voc pode usar para propriedades. Um nome de
propriedade deve comear com uma letra, dois-pontos (:), ou um caractere sublinha (_); e depois
1
disso, voc tambm pode usar dgitos, hifens (-), e pontos (.).
Alm do propset, o programa svn tambm oferece comando propedit. Este comando usa o editor de
texto configurado (veja Configurao) para adicionar ou modificar propriedades. Quando voc executa
este comando, o svn chama seu programa editor em um arquivo temporrio que contm o valor atual
da propriedade (ou o qual vazio, se voc estiver adicionando uma nova propriedade). Ento, voc
apenas modifica esse valor em seu editor at que ele represente o novo valor que voc quer armazenar
para a propriedade. Se o Subversion identificar que no momento voc est modificando o valor da
propriedade existente, ele ir aceit-lo como novo valor da propriedade. Se voc sair de seu editor sem
fazer qualquer alterao, nenhuma modificao ir ocorrer:
$ svn propedit copyright calc/button.c ### sai do editor sem fazer nada
No changes to property 'copyright' on 'calc/button.c'
$
Devemos notar que, como qualquer outro subcomando do svn, estes que so relacionados a
propriedades podem agir em diversos caminhos de uma s vez. Isto lhe permite modificar propriedades
em todo um conjunto de arquivos com um nico comando. Por exemplo, ns poderamos ter feito:
Toda esta adio e alterao de propriedades no realmente muito til se voc no puder obter
facilmente o valor armazenado da propriedade. Ento o programa svn dispe de dois subcomando para
exibio dos nomes e valores das propriedades armazenadas nos arquivos e diretrios. O comando
svn proplist vai listar os nomes das propriedades que existem naquele caminho. Uma vez que voc
saiba os nomes das propriedades do n, voc pode verificar seus valores individualmente usando
svn propget. Este comando mostrar, dado um nome de propriedade e um caminho (ou conjunto de
caminhos), o valor da propriedade para a sada padro.
40
Tpicos Avanados
copyright
license
$ svn propget copyright calc/button.c
(c) 2006 Red-Bean Software
H ainda uma variao do comando proplist que lista tanto o nome quanto o valor de todas as
propriedades. Apenas informe a opo --verbose (-v).
Voc precisa usar o subcomando propdel para remover propriedades completamente. A sintaxe
semelhante a dos outros comandos de propriedades:
Lembra das propriedades no-versionadas de revises? Voc pode modific-las, tambm, usando os
mesmo subcomandos do svn que acabamos de descrever. Apenas adicione o parmetro --revprop
na linha de comando, e especifique a reviso cujas propriedades voc quer modificar. Como as revises
so globais, voc no precisa especificar um caminho para para estes comandos relacionados a
propriedades enquanto estiver em uma cpia de trabalho do repositrio cuja propriedade de reviso
voc queira alterar. Por outro lado, voc pode apenas especificar a URL de qualquer caminho de seu
interesse no repositrio (incluindo a URL raiz do repositrio). Por exemplo, voc pode querer trocar
2
a mensagem de log de um registro de alterao de uma reviso existente. Se seu diretrio atual
2
Correo de erros de ortografia, gramaticais outros ajustes simples de texto nas mensagens de log de uma registro talvez
seja o uso mais comum da opo --revprop option.
41
Tpicos Avanados
for parte da cpia de trabalho de seu repositrio, voc pode simplesmente executar o comando svn
propset sem nenhum caminho:
$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop
property 'svn:log' set on repository revision '11'
$
Mas mesmo que voc no tenha criado uma cpia de trabalho a partir do repositrio, voc ainda assim
pode proceder com modificao de propriedades informando a URL raiz do repositrio:
$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop \
http://svn.example.com/repos/project
property 'svn:log' set on repository revision '11'
$
Perceba que a permisso para se alterar estas propriedades no-versionadas deve ser explicitamente
concedida pelo administrador do repositrio (veja Corrigindo Mensagens de Log Submetidas). Isto
porque as propriedades no so versionadas, ento voc corre o risco de perder informao se no
for cuidadoso com suas alteraes. O administrador do repositrio pode definir formas de proteo
contra perda de dados, e por padro, alm de que as modificaes de propriedades no-versionadas
so desabilitadas por padro.
Usurios poderia, quando possvel, usar svn propedit ao invs de svn propset. Ainda que
o resultado da execuo dos comandos seja o mesmo, o primeiro vai lhes permitir visualizar
o valor atual da propriedade que querem modificar, o que ajuda a conferir que esto, de
fato, fazer a alterao que acham que esto fazendo. Isto especialmente verdadeiro
ao modificar as propriedades no-versionadas de reviso. E ainda, significativamente
modificar valores de propriedades em mltiplas linhas em um editor de texto do que pela
linha de comando.
E como com contedos de arquivos, suas mudanas de propriedades so modificaes locais, que
so tornadas permanentes apenas quando submetidas ao repositrio com o comando svn commit.
Suas alteraes de propriedades tambm podem ser facilmente desfeitaso comando svn revert vai
restaurar seus arquivos e diretrios para seus estados inalteradoscontedos, propriedades, e tudo.
Tambm, voc pode obter informaes interessantes sobre o estado de suas propriedades de arquivos
e diretrios usando os comandos svn status e svn diff.
Note como o subcomando status exibe M na segunda coluna ao invs de na primeira. Isto porque
modificamos as propriedades de calc/button.c, mas no seu contedo textual. Se tivssemos
42
Tpicos Avanados
modificado ambos, deveramos ver um M na primeira coluna tambm (veja Obtendo uma viso geral
de suas alteraes).
Conflitos de Propriedades
Da mesma forma que para contedo de arquivos, modificaes de propriedades podem conflitar
com alteraes submetidas por outros. Se voc atualizar sua cpia de trabalho e receber
alteraes de propriedade em um objeto versionado que vo de encontro s suas, o Subversion
vai informar que o objeto est em um estado conflituoso.
O Subversion tambm vai criar, no mesmo diretrio que o objeto em conflito, um arquivo com a
extenso .prej contendo os detalhes do conflito. Voc deve examinar o contedo deste arquivo
para decidir como resolver o conflito. At que o conflito seja resolvido, voc ver um C na segunda
coluna da sada do svn status para o objeto em questo, e as tentativas de submeter suas
modificaes locais iro falhar.
Voc tambm deve ter notado a forma no-padro como o Subversion atualmente exibe diferenas
de propriedades. Voc ainda pode executar svn diff e redirecionar a sada para criar um arquivo de
patch usvel. O programa patch vai ignorar patches de propriedadescomo regra, ele ignora qualquer
coisa que no consiga entender. Isso significa, infelizmente, que para aplicar completamente um patch
gerado pelo svn diff, quaisquer alteraes em propriedades precisaro ser aplicadas manualmente.
Sempre que voc inclui um arquivo ao controle de verso usando os comando svn add ou svn import,
o Subversion tenta ajudar criando algumas propriedades de arquivo automaticamente. Primeiramente,
em sistema operacionais cujos sistemas de arquivo suportem bits de permisso de execuo,
43
Tpicos Avanados
Portabilidade de Arquivo
Felizmente, para os usurios do Subversion que rotineiramente se encontram em diferentes
computadores, com diferentes sistemas operacionais, o programa de linha de comando do Subversion
comporta-se quase que da mesma forma em todos os sistemas. Se voc sabe como usar o svn em
uma plataforma, voc saber como manuse-lo em qualquer outra.
Entretanto, o mesmo nem sempre verdade em outras classes de software em geral, ou nos atuais
arquivos que voc mantm no Subversion. Por exemplo, em uma mquina Windows, a definio de um
arquivo de texto seria similar usada em uma mquina Linux, porm com uma diferena chaveos
caracteres usados para marcar o fim das linhas destes arquivos. Existem outras diferenas tambm.
As plataformas Unix tm (e o Subversion suporta) links simblicos; Windows no. As plataformas
Unix usam as permisses do sistema de arquivos para determinar a executabilidade; Windows usa as
extenses no nome do arquivo.
Pela razo de que o Subversion no est em condio de unir o mundo inteiro em definies comuns
e implementaes de todas estas coisas, o melhor que podemos fazer tentar ajudar a tornar sua vida
mais simples quando voc precisar trabalhar com seus arquivos e diretrios versionados em mltiplos
computadores e sistemas operacionais. Esta seo descreve alguns dos meios de como o Subversion
faz isto.
44
Tpicos Avanados
Vrios programas nos sistemas operacionais mais modernos fazem suposies sobre o tipo e
formato do contedo de um arquivo pelo nome do arquivo, especificamente por sua extenso.
Por exemplo, arquivos cujos nomes terminam em .txt so, geralmente, supostos ser legveis
por humanos, passveis de serem compreendidos por simples leitura, em vez dos que requerem
processamento complexo para os decifrar. Por outro lado, arquivos cujos nomes terminam em
.png assume-se serem do tipo Portable Network Graphics que no so legveis por humanos,
sendo perceptveis apenas quando interpretados pelo software que entende o formato PNG, e
pode tornar a informao neste formato como uma imagem desenhada por linhas.
A popularidade das redes de computadores lanou ainda mais dvidas sobre o mapeamento
entre um nome de arquivo e seu contedo. Com informaes sendo servidas atravs das redes
e geradas dinamicamente por scripts no servidor, freqentemente, observava-se arquivos no
reais e, portanto, sem nome. Os servidores Web, por exemplo, precisavam de algum outro modo
para dizer aos navegadores que eles estavam baixando um arquivo, assim o navegador poderia
fazer algo inteligente com esta informao, quer seja para exibir os dados usando um programa
registrado para lidar com este tipo de dados, quer seja para solicitar ao usurio onde armazenar
os dados baixados.
Finalmente, um padro surgiu para, entre outras coisas, descrever o contedo de um fluxo de
dados. Em 1996, a RFC2045 foi publicada, a primeira de cinco RFC's descrevendo o MIME.
Esta RFC descreve o conceito de tipos e subtipos de mdia, e recomenda uma sintaxe para a
representao destes tipos. Hoje, os tipos de mdia MIMEou tipos MIMEso usados quase
que universalmente em todas as aplicaes de e-mail, servidores Web e outros softwares como
o mecanismo de fato para esclarecer a confuso do contedo de arquivo.
Por exemplo, um dos benefcios que o Subversion tipicamente fornece a fuso contextual, baseada
nas linhas, das mudanas recebidas do servidor durante uma atualizao em seu arquivo de trabalho.
Mas, para arquivos contendo dados no-textuais, muitas vezes no existe o conceito de linha. Assim,
para os arquivos versionados cuja propriedade svn:mime-type definida com um tipo MIME no-
textual (geralmente, algo que no inicie com text/, embora existam excees), o Subversion no tenta
executar fuses contextuais durante as atualizaes. Em vez disso, quando voc modifica localmente
um arquivo binrio em sua cpia de trabalho, na momento da atualizao, seu arquivo no mexido,
pois o Subversion cria dois novos arquivos. Um deles tem a extenso .oldrev e contm a reviso
BASE do arquivo. O outro arquivo tem uma extenso .newrev e contm o contedo da reviso
atualizada do arquivo. Este comportamento serve de proteo ao usurio contra falhas na tentativa de
executar fuses contextuais nos arquivos que simplesmente no podem ser contextualmente fundidos.
Alm disso, se a propriedade svn:mime-type estiver definida, ento o mdulo Apache do Subversion
usar seu valor para preencher o cabealho HTTP Content-type: quando responder a solicitaes
GET. Isto oferece ao navegador web uma dica crucial sobre como exibir um arquivo quando voc o
utiliza para examinar o contedo de seu repositrio Subversion.
3
Voc acha que foi complicado? Durante este mesmo perodo, o WordPerfect tambm usou .DOC como extenso para seu
formato de arquivo proprietrio!
45
Tpicos Avanados
Executabilidade de Arquivo
Em muitos sistemas operacionais, a capacidade de executar um arquivo como um comando
comandada pela presena de um bit de permisso para execuo. Este bit, usualmente, vem
desabilitado por padro, e deve ser explicitamente habilitado pelo usurio em cada arquivo que seja
necessrio. Mas seria um grande incmodo ter que lembrar, exatamente, quais arquivos de uma cpia
de trabalho verificada recentemente estavam com seus bits de execuo habilitados, e, ento, ter que
troc-los. Por esta razo, o Subversion oferece a propriedade svn:executable, que um modo
de especificar que o bit de execuo para o arquivo no qual esta propriedade est definida deve ser
habilitado, e o Subversion honra esta solicitao ao popular cpias de trabalho com tais arquivos.
Esta propriedade no tem efeito em sistemas de arquivo que no possuem o conceito de bit de
4
permisso para executvel, como, por exemplo, FAT32 e NTFS. Alm disso, quando no houver valor
definido, o Subversion forar o valor * ao definir esta propriedade. Por fim, esta propriedade s
vlido em arquivos, no em diretrios.
Isto significa que, por padro, o Subversion no presta qualquer ateno para o tipo de marcadores
de fim-de-linha, ou end-of-line (EOL) usados em seus arquivos. Infelizmente, diferentes sistemas
operacionais possuem diferentes convenes sobre qual seqncia de caracteres representa o fim de
uma linha de texto em um arquivo. Por exemplo, a marca usual de trmino de linha usada por softwares
na plataforma Windows um par de caracteres de controle ASCIIum retorno de carro (CR) seguido
por um avano de linha (LF). Os softwares em Unix, entretanto, utilizam apenas o caracter LF para
definir o trmino de uma linha.
Nem todas as ferramentas nestes sistemas operacionais compreendem arquivos que contm
terminaes de linha em um formato que difere do estilo nativo de terminao de linha do sistema
operacional no qual esto executando. Assim, normalmente, programas Unix tratam o caracter CR,
presente em arquivos Windows, como um caracter normal (usualmente representado como ^M), e
programas Windows juntam todas as linhas de um arquivo Unix dentro de uma linha enorme, porque
nenhuma combinao dos caracteres de retorno de carro e avano de linha (ou CRLF) foi encontrada
para determinar os trminos das linhas.
Esta sensibilidade quanto aos marcadores EOL pode ser frustrante para pessoas que compartilham
um arquivo em diferentes sistemas operacionais. Por exemplo, considere um arquivo de cdigo-fonte,
onde desenvolvedores que editam este arquivo em ambos os sistemas, Windows e Unix. Se todos os
desenvolvedores sempre usarem ferramentas que preservem o estilo de trmino de linha do arquivo,
nenhum problema ocorrer.
Mas na prtica, muitas ferramentas comuns, ou falham ao ler um arquivo com marcadores EOL
externos, ou convertem as terminaes de linha do arquivo para o estilo nativo quando o arquivo
salvo. Se o precedente verdadeiro para um desenvolvedor, ele deve usar um utilitrio de converso
externo (tal como dos2unix ou seu similar, unix2dos) para preparar o arquivo para edio. O caso
posterior no requer nenhuma preparao extra. Mas ambos os casos resultam em um arquivo que
difere do original literalmente em cada uma das linhas! Antes de submeter suas alteraes, o usurio
tem duas opes. Ou ele pode utilizar um utilitrio de converso para restaurar o arquivo modificado
para o mesmo estilo de trmino de linha utilizado antes de suas edies serem feitas. Ou ele pode
simplesmente submeter o arquivoas novas marcas EOL e tudo mais.
O resultado de cenrios como estes incluem perda de tempo e modificaes desnecessrias aos
arquivos submetidos. A perda de tempo suficientemente dolorosa. Mas quando submisses mudam
4
Os sistemas de arquivos do Windows usam extenses de arquivo (tais como .EXE, .BAT, e .COM) para indicar arquivos
executveis.
46
Tpicos Avanados
cada uma das linhas em um arquivo, isso dificulta o trabalho de determinar quais dessas linhas foram
modificadas de uma forma no trivial. Onde o bug foi realmente corrigido? Em qual linha estava o erro
de sintaxe introduzido?
A soluo para este problema a propriedade svn:eol-style. Quando esta propriedade definida
com um valor vlido, o Subversion a utiliza para determinar que tratamento especial realizar sobre o
arquivo de modo que o estilo de trmino de linha do arquivo no fique alternando a cada submisso
vinda de um sistema operacional diferente. Os valores vlidos so:
native
Isso faz com que o arquivo contenha as marcas EOL que so nativas ao sistema operacional
no qual o Subversion foi executado. Em outras palavras, se um usurio em um computador
Windows adquire uma cpia de trabalho que contm um arquivo com a propriedade svn:eol-
style atribuda para native, este arquivo conter CRLF como marcador EOL. Um usurio Unix
adquirindo uma cpia de trabalho que contm o mesmo arquivo ver LF como marcador EOL em
sua cpia do arquivo.
CRLF
Isso faz com que o arquivo contenha seqncias CRLF como marcadores EOL, independentemente
do sistema operacional em uso.
LF
Isso faz com que o arquivo contenha caracteres LF como marcadores EOL, independentemente
do sistema operacional em uso.
CR
Isso faz com que o arquivo contenha caracteres CR como marcadores EOL, independentemente
do sistema operacional em uso. Este estilo de trmino de linha no muito comum. Ele foi utilizado
em antigas plataformas Macintosh (nas quais o Subversion no executa regularmente).
ridculo esperar que cpias de trabalho do Subversion sejam de algum modo impenetrveis a
este tipo de resduo e impureza. De fato, o Subversion os considera como um recurso que suas
cpias de trabalho esto apenas com diretrios normais, como rvores no-versionadas. Mas estes
arquivos e diretrios que no deveriam ser versionados podem causar algum incmodo aos usurios
do Subversion. Por exemplo, pelo fato dos comandos svn add e svn import agirem recursivamente
por padro, e no saberem quais arquivos em uma dada rvore voc deseja ou no versionar,
acidentalmente fcil adicionar coisas ao controle de verso que voc no pretendia. E pelo fato do
comando svn status reportar, por padro, cada item de interesse em uma cpia de trabalhoincluindo
arquivos e diretrios no versionadossua sada pode ficar muito poluda, onde grande nmero destas
coisas aparecem.
Portanto, o Subversion oferece dois meios para dizer quais arquivos voc preferiria que ele
simplesmente desconsiderasse. Um dos meios envolve o uso do sistema de configurao do
ambiente de execuo do Subversion (veja rea de Configurao do Tempo de Execuo), e
conseqentemente aplica-se a todas operaes do Subversion que fazem uso desta configurao do
ambiente de execuo, geralmente aquelas executadas em um computador especfico, ou por um
47
Tpicos Avanados
usurio especfico de um computador. O outro meio faz uso do suporte de propriedade de diretrio do
Subversion, mais fortemente vinculado prpria rvore versionada e, conseqentemente, afeta todos
aqueles que tm uma cpia de trabalho desta rvore. Os dois mecanismos usam filtros de arquivo.
O sistema de configurao runtime do Subversion oferece uma opo, global-ignores, cujo valor
uma coleo de filtros de arquivo delimitados por espaos em branco (tambm conhecida com globs).
O cliente do Subversion verifica esses filtros em comparao com os nomes dos arquivos que so
candidatos para adio ao controle de verso, bem como os arquivos no versionados os quais o
comando svn status notifica. Se algum nome de arquivo coincidir com um dos filtros, basicamente,
o Subversion atuar como se o arquivo no existisse. Isto realmente til para os tipos de arquivos
que voc raramente precisar controlar verso, tal como cpias de arquivos feitas por editores como
os arquivos *~ e .*~ do Emacs.
Quando encontrada em um diretrio versionado, a propriedade svn:ignore espera que contenha uma
lista de filtros de arquivo delimitadas por quebras de linha que o Subversion deve usar para determinar
objetos ignorveis neste mesmo diretrio. Estes filtros no anulam os encontrados na opo global-
ignores da configurao runtime, porm, so apenas anexados a esta lista. E importante notar
mais uma vez que, ao contrrio da opo global-ignores, os filtros encontrados na propriedade
svn:ignore aplicam-se somente ao diretrio no qual esta propriedade est definida, e em nenhum de
seus subdiretrios. A propriedade svn:ignore uma boa maneira para dizer ao Subversion ignorar
arquivos que esto susceptveis a estarem presentes em todas as cpias de trabalho de usurio deste
diretrio, assim como as sadas de compilador oupara usar um exemplo mais apropriado para este
livroos arquivos HTML, PDF, ou PostScript produzidos como o resultado de uma converso de alguns
arquivos XML do fonte DocBook para um formato de sada mais legvel.
Existem, entretanto, algumas diferenas nos meios que CVS e Subversion manipulam filtros
de rejeio. Os dois sistemas usam os filtros de rejeio em tempos um pouco diferentes, e
existem ligeiras discrepncias na aplicao dos filtros de rejeio. Alm disso, o Subversion
no reconhece o uso do filtro ! como uma redefinio que torna os filtros seguintes como no-
ignorados.
A lista global de filtros de rejeio tende ser mais uma questo de gosto pessoal, e vinculada mais
estreitamente a uma srie de ferramentas especficas do usurio do que aos detalhes de qualquer
cpia de trabalho particular necessita. Assim, o resto desta seo focar na propriedade svn:ignore
e seus usos.
48
Tpicos Avanados
Neste exemplo, voc realizou algumas modificaes no arquivo button.c, mas em sua cpia de
trabalho voc tambm possui alguns arquivos no-versionados: o mais recente programa calculator
que voc compilou a partir do seu cdigo fonte, um arquivo fonte nomeado data.c, e uma srie
de arquivos de registro da sada de depurao. Agora, voc sabe que seu sistema de construo
5
sempre resulta no programa calculator como produto. E voc sabe que sua ferramenta de
testes sempre deixa aqueles arquivos de registro de depurao alojando ao redor. Estes fatos so
verdadeiros para todas cpias de trabalho deste projeto, no para apenas sua prpria. E voc tambm
no est interessado em ver aquelas coisas toda vez que voc executa svn status, e bastante seguro
que ningum mais est interessado em nenhuma delas. Sendo assim, voc executa svn propedit
svn:ignore calc para adicionar alguns filtros de rejeio para o diretrio calc. Por exemplo, voc pode
adicionar os filtros abaixo como o novo valor da propriedade svn:ignore:
calculator
debug_log*
Depois de voc adicionar esta propriedade, voc ter agora uma modificao de propriedade local no
diretrio calc. Mas note que o restante da sada diferente para o comando svn status:
$ svn status
M calc
M calc/button.c
? calc/data.c
Agora, todas aqueles resduos no so apresentados nos resultados! Certamente, seu programa
compilado calculator e todos aqueles arquivos de registro esto ainda em sua cpia de trabalho.
O Subversion est simplesmente no lembrando voc que eles esto presentes e no-versionados.
E agora com todos os arquivos desinteressantes removidos dos resultados, voc visualizar somente
os itens mais interessantesassim como o arquivo de cdigo fonte data.c que voc provavelmente
esqueceu de adicionar ao controle de verso.
Evidentemente, este relatrio menos prolixo da situao de sua cpia de trabalho no a nica
disponvel. Se voc realmente quiser ver os arquivos ignorados como parte do relatrio de situao,
voc pode passar a opo --no-ignore para o Subversion:
Como mencionado anteriormente, a lista de filtros de arquivos a ignorar tambm usada pelos
comandos svn add e svn import. Estas duas operaes implicam solicitar ao Subversion iniciar o
5
No isso o resultado completo de um sistema de construo?
49
Tpicos Avanados
gerenciamento de algum conjunto de arquivos e diretrios. Ao invs de forar o usurio a escolher quais
arquivos em uma rvore ele deseja iniciar o versionamento, o Subversion usa os filtros de rejeio
tanto a lista global quanto a por diretrio (svn-ignore)para determinar quais arquivos no devem
ser varridos para o sistema de controle de verso como parte de uma operao recursiva de adio
ou importao. E da mesma forma, voc pode usar a opo --no-ignore para indicar ao Subversion
desconsiderar suas listas de rejeio e operar em todos os arquivos e diretrios presentes.
Substituio de Palavra-Chave
O Subversion possui a capacidade de substituir palavras-chavepedaos de informao teis e
dinmicos sobre um arquivo versionadodentro do contedo do prprio arquivo. As palavras-chave
geralmente fornece informao sobre a ltima modificao realizada no arquivo. Pelo fato desta
informao modificar toda vez que o arquivo modificado, e mais importante, apenas depois que
o arquivo modificado, isto um aborrecimento para qualquer processo a no ser que o sistema
de controle de verso mantenha os dados completamente atualizados. Se deixada para os autores
humanos, a informao se tornaria inevitavelmente obsoleta.
Por exemplo, digamos que voc tem um documento no qual gostaria de mostrar a ltima data em
que ele foi modificado. Voc poderia obrigar que cada autor deste documento que, pouco antes de
submeter suas alteraes, tambm ajustasse a parte do documento que descreve quando ele fez a
ltima alterao. Porm, mais cedo ou mais tarde, algum esqueceria de fazer isto. Em vez disso,
basta solicitar ao Subversion que efetue a substituio da palavra-chave LastChangedDate pelo valor
adequado. Voc controla onde a palavra-chave inserida em seu documento colocando uma ncora
de palavra-chave no local desejado dentro do arquivo. Esta ncora apenas uma sequncia de texto
formatada como $NomeDaPalavraChave$.
O Subversion define a lista de palavras-chave disponveis para substituio. Esta lista contm as
seguintes cinco palavras-chave, algumas das quais possuem apelidos que voc pode tambm utilizar:
Date
Esta palavra-chave descreve a ltima vez conhecida em que o arquivo foi modificado no repositrio,
e est na forma $Date: 2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006) $. Ela tambm
pode ser especificada como LastChangedDate.
Revision
Esta palavra-chave descreve a ltima reviso conhecida em que este arquivo foi modificado no
repositrio, e apresentada na forma $Revision: 144 $. Ela tambm pode ser especificada
como LastChangedRevision ou Rev.
Author
Esta palavra-chave descreve o ltimo usurio conhecido que modificou este arquivo no repositrio,
e apresentada na forma $Author: harry $. Ela tambm pode ser especificada como
LastChangedBy.
HeadURL
Esta palavra-chave descreve a URL completa para a verso mais recente do arquivo no repositrio,
e apresentada na forma $HeadURL: http://svn.collab.net/repos/trunk/README $.
Ela tambm pode ser abreviada como URL.
Id
Esta palavra-chave uma combinao comprimida das outras palavras-chave. Sua substituio
apresenta-se como $Id: calc.c 148 2006-07-28 21:30:43Z sally $, e interpretada
50
Tpicos Avanados
no sentido de que o arquivo calc.c foi modificado pela ltima vez na reviso 148 na noite de 28
de julho de 2006 pelo usurio sally.
Muitas das descries anteriores usam a frase ltimo valor conhecido ou algo parecido. Tenha em
mente que a expanso da palavra-chave uma operao no lado do cliente, e seu cliente somente
conhece sobre mudanas que tenham ocorrido no repositrio quando voc atualiza sua cpia de
trabalho para incluir essas mudanas. Se voc nunca atualizar sua cpia de trabalho, suas palavras-
chave nunca expandiro para valores diferentes, mesmo que esses arquivos versionados estejam
sendo modificados regularmente no repositrio.
Simplesmente adicionar texto da ncora de uma palavra-chave em seu arquivo faz nada de especial.
O Subversion nunca tentar executar substituies textuais no contedo de seu arquivo a no ser
6
que seja explicitamente solicitado. Afinal, voc pode estar escrevendo um documento sobre como
usar palavras-chave, e voc no quer que o Subversion substitua seus belos exemplos de ncoras de
palavra-chave, permanecendo no-substitudas!
Por exemplo, digamos que voc tenha um arquivo versionado nomeado weather.txt que possui
esta aparncia:
Sem definir a propriedade svn:keywords neste arquivo, o Subversion far nada especial. Agora,
vamos permitir a substituio da palavra-chave LastChangedDate.
Agora voc fez uma modificao local da propriedade no arquivo weather.txt. Voc ver nenhuma
mudana no contedo do arquivo (ao menos que voc tenha feito alguma definio na propriedade
anteriormente). Note que o arquivo continha uma ncora de palavra-chave para a palavra-chave Rev,
no entanto, no inclumos esta palavra-chave no valor da propriedade que definimos. Felizmente, o
Subversion ignorar pedidos para substituir palavras-chave que no esto presentes no arquivo, e no
substituir palavras-chave que no esto presentes no valor da propriedade svn:keywords.
Imediatamente depois de voc submeter esta mudana de propriedade, o Subversion atualizar seu
arquivo de trabalho com o novo texto substituto. Em vez de ver a sua ncora da palavra-chave
$LastChangedDate$, voc ver como resultado seu valor substitudo. Este resultado tambm contm
o nome da palavra-chave, que continua sendo limitada pelos caracteres de sinal de moeda ($). E como
prevamos, a palavra-chave Rev no foi substituda porque no solicitamos que isto fosse realizado.
Note tambm, que definimos a propriedade svn:keywords para Date Author e, no entanto, a ncora
da palavra-chave usou o apelido $LastChangedDate$ e ainda sim expandiu corretamente.
51
Tpicos Avanados
Se agora algum submeter uma mudana para weather.txt, sua cpia deste arquivo continuar a
mostrar o mesmo valor para a palavra-chave substituda como antesat que voc atualize sua cpia
de trabalho. Neste momento as palavras-chave em seu arquivo weather.txt sero re-substitudas
com a informao que reflete a mais recente submisso conhecida para este arquivo.
Novos usurios so freqentemente confundidos pela forma que a palavra-chave $Rev$ trabalha.
Como o repositrio possui um nmero de reviso nico, globalmente incrementado, muitas
pessoas assumem que este nmero est refletido no valor da palavra-chave $Rev$. Porm,
$Rev$ reflete a ltima reviso na qual o arquivo foi modificado, no a ltima reviso para
qual ele foi atualizado. Compreender isto esclarece a confuso, mas a frustrao muitas vezes
permanecesem o suporte de uma palavra-chave do Subversion para isso, como podemos obter
automaticamente o nmero de reviso global em seus arquivos?
Para fazer isto, voc precisa de processamento externo. O Subversion vem com uma ferramenta
chamada svnversion que foi projetada apenas para este propsito. O comando svnversion
rastreia sua cpia de trabalho e produz como sada as revises que encontra. Voc pode usar
este programa, mais algumas outras ferramentas, para embutir esta informao sobre as revises
globais em seus arquivos. Para mais informaes sobre svnversion, veja svnversion.
O Subversion 1.2 introduziu uma nova variante da sintaxe de palavra-chave que trouxe funcionalidade
adicional e tilembora talvez atpica. Agora voc pode dizer ao Subversion para manter um tamanho
fixo (em termos do nmero de bytes consumidos) para a palavra-chave substituda. Pelo uso de um
duplo dois pontos (::) aps o nome da palavra-chave, seguido por um nmero de caracteres de
espao, voc define esta largura fixa. Quando o Subversion for substituir sua palavra-chave para
a palavra-chave e seu valor, ele substituir essencialmente apenas aqueles caracteres de espao,
deixando a largura total do campo da palavra-chave inalterada. Se o valor substitudo for menor que a
largura definida para o campo, haver caracteres de enchimento extras (espaos) no final do campo
substitudo; se for mais longo, ser truncado com um caractere de conteno especial (#) logo antes
do sinal de moeda delimitador de fim.
Por exemplo, digamos que voc possui um documento em que temos alguma seo com dados
tabulares refletindo as palavras-chave do Subversion sobre o documento. Usando a sintaxe de
substituio de palavra-chave original do Subversion, seu arquivo pode parecer com alguma coisa
como:
Neste momento, vemos tudo de forma agradvel e tabular. Mas quando voc em seguida submete este
arquivo (com a substituio de palavra-chave habilitada, certamente), vemos:
O resultado no to elegante. E voc pode ser tentado a ento ajustar o arquivo depois da substituio
para que parea tabular novamente. Mas isto apenas funciona quando os valores da palavra-chave
so da mesma largura. Se a ltima reviso submetida aumentar em uma casa decimal (ou seja, de 99
52
Tpicos Avanados
para 100), ou se uma outra pessoa com um nome de usurio maior submete o arquivo, teremos tudo
bagunado novamente. No entanto, se voc est usando o Subversion 1.2 ou superior, voc pode usar
a nova sintaxe para palavra-chave com tamanho fixo, definir algumas larguras de campo que sejam
razoveis, e agora seu arquivo pode ter esta aparncia:
Voc submete esta mudana ao seu arquivo. Desta vez, o Subversion nota a nova sintaxe para palavra-
chave com tamanho fixo, e mantm a largura dos campos como definida pelo espaamento que voc
colocou entre o duplo dois pontos e o sinal de moeda final. Depois da substituio, a largura dos campos
est completamente inalteradaos curtos valores de Rev e Author so preenchidos com espaos, e
o longo campo Date truncado com um caractere de conteno:
Esteja ciente que pelo fato da largura do campo de uma palavra-chave medida em
bytes, o potencial de corrupo de valores de multi-byte existe. Por exemplo, um nome de
usurio que contm alguns caracteres multi-byte em UTF-8 pode sofrer truncamento no
meio da seqncia de bytes que compem um desses caracteres. O resultado ser um
mero truncamento quando visualizado nvel de byte, mas provavelmente aparecer como
uma cadeia com um caractere adicional incorreto ou ilegvel quando exibido como texto
em UTF-8. concebvel que certas aplicaes, quando solicitadas a carregar o arquivo,
notariam o texto em UTF-8 quebrado e ainda considerem todo o arquivo como corrompido,
recusando-se a operar sobre o arquivo de um modo geral. Portanto, ao limitar palavras-
chave para um tamanho fixo, escolha um tamanho que permita este tipo de expanso
ciente dos bytes.
Travamento
O modelo de controle de verso copiar-modificar-fundir do Subversion ganha e perde sua utilidade
em seus algoritmos de fuso de dados, especificamente sobre quo bem esses algoritmos
executam ao tentar resolver conflitos causados por mltiplos usurios modificando o mesmo arquivo
simultaneamente. O prprio Subversion oferece somente um algoritmo, um algoritmo de diferenciao
de trs meios, que inteligente o suficiente para manipular dados at uma granularidade de uma nica
linha de texto. O Subversion tambm permite que voc complemente o processamento de fuso de
contedo com utilitrios de diferenciao externos (como descrito em Ferramentas diff3 Externas),
alguns dos quais podem fazer um trabalho ainda melhor, talvez oferecendo granularidade em nvel de
palavra ou em nvel de caractere de texto. Mas o comum entre esses algoritmos que eles geralmente
trabalham apenas sobre arquivos de texto. O cenrio comea a parecer consideravelmente rgido
quando voc comea a discursar sobre fuses de contedo em formatos de arquivo no-textual. E
quando voc no pode encontrar uma ferramenta que possa manipular este tipo de fuso, voc comea
a verificar os problemas com o modelo copiar-modificar-fundir.
Vejamos um exemplo da vida real onde este modelo no trabalha adequadamente. Harry e Sally so
ambos desenhistas grficos trabalhando no mesmo projeto, que faz parte do marketing paralelo para
um automvel mecnico. O ncleo da concepo de um determinado cartaz uma imagem de um
carro que necessita de alguns reparos, armazenada em um arquivo usando o formato de imagem PNG.
53
Tpicos Avanados
O leiaute do cartaz est quase pronto, e tanto Harry quanto Sally esto satisfeitos com a foto que eles
escolheram para o carro danificadoum Ford Mustang 1967 azul beb com uma parte infelizmente
amassada no pra-lama dianteiro esquerdo.
Agora, como comum em trabalhos de desenho grfico, existe uma mudana de planos que faz da cor
do carro uma preocupao. Ento, Sally atualiza sua cpia de trabalho para a reviso HEAD, inicializa
seu software de edio de fotos, e realiza alguns ajustes na imagem de modo que o carro est agora
vermelho cereja. Enquanto isso, Harry, sentindo-se particularmente inspirado neste dia, decide que a
imagem teria mais impacto se o carro tambm apresentasse ter sofrido um maior impacto. Ele, tambm,
atualiza para a reviso HEAD, e ento, desenha algumas rachaduras no pra-brisa do veculo. Ele
conduz de forma a concluir seu trabalho antes de Sally terminar o dela, e depois, admirando o fruto
de seu inegvel talento, submete a imagem modificada. Pouco tempo depois, Sally finaliza sua nova
verso do carro, e tenta submeter suas mudanas. Porm, como esperado, o Subversion falha na
submisso, informando Sally que agora sua verso da imagem est desatualizada.
Vejamos onde a dificuldade ocorre. Se Harry e Sally estivessem realizando mudanas em um arquivo
de texto, Sally iria simplesmente atualizar sua cpia de trabalho, recebendo as mudanas que Harry
realizou. No pior caso possvel, eles teriam modificado a mesma regio do arquivo, e Sally teria que
realizar uma adequada resoluo do conflito. Mas estes no so arquivos de textoso imagens
binrias. E enquanto seja uma simples questo de descrever o que seria esperado como resultado
desta fuso de contedos, existe uma pequena chance preciosa de que qualquer software existente
seja inteligente o suficiente para examinar a imagem que cada um dos artistas grficos se basearam
para realizarem seu trabalho, as mudanas que Harry fez e as mudanas que Sally faz, e produzir uma
imagem de um Mustang vermelho degradado com um pra-brisa trincado!
Obviamente, as coias teriam sido mais simples se Harry e Sally tivessem seqenciado suas
modificaes na imagemse, digamos, Harry aguardasse para desenhar seus trincados no pra-brisa
no novo carro vermelho de Sally, ou se Sally trocasse a cor de um carro cujo pra-brisa j estivesse
trincado. Como discutido em A Soluo Copy-Modify-Merge, a maioria destes tipos de problemas
7
desaparecero totalmente quando existir uma perfeita comunicao entre Harry e Sally. Porm,
como um sistema de controle de verso de fato uma forma de comunicao, ter um software que
facilita a a serializao de esforos no passveis de paralelamento no ruim. neste cenrio que
a implementao do Subversion do modelo travar-modificar-destravar ganha maior destaque. Este
o momento que falamos sobre a caracterstica de travamento do Subversion, a qual similar aos
mecanismos de obter cpias reservadas de outros sistemas de controle de verso.
Ajudar a comunicao. Ao alertar outros usurios que a serializao est em vigor para um
determinado objeto versionado, estes outros usurios podem razoavelmente esperar que o objeto
est prestes de ser modificado por outra pessoa, e eles, tambm, podem evitar o desperdcio de
seu tempo e energia em mudanas no-mesclveis que no sero submetidas adequadamente e
ocasionando possvel perda de dados.
54
Tpicos Avanados
Nesta seo, e em quase todas neste livro, as palavras trava e travamento representam
um mecanismo para excluso mtua entre os usurios para evitar submisses conflitantes.
Infelizmente, existem dois outros tipos de trava com os quais o Subversion, e portanto este livro,
algumas vezes precisam se preocupar.
O primeiro tipo so as travas da cpia de trabalho, usadas internamente pelo Subversion para
prevenir conflitos entre mltiplos clientes Subversion operando na mesma cpia de trabalho. Este
o tipo de trava indicada por um L na terceira coluna da sada produzida por svn status, e
removida pelo comando svn cleanup, como especificado em s Vezes Voc S Precisa Limpar.
Em segundo lugar, existem as travas do banco de dados, usadas internamente pelo sistema
Berkeley DB para prevenir conflitos entre mltiplos programas tentando acessar o banco de
dados. Este o tipo de trava cuja indesejvel persistncia aps um erro pode fazer com que um
repositrio seja corrompido, como descrito em Recuperao do Berkeley DB.
Voc pode geralmente esquecer destes outros tipos de travas at que algo de errado ocorra e
requeira seus cuidados sobre eles. Neste livro, trava possui o significado do primeiro tipo ao
menos que o contrrio esteja claro pelo contexto ou explicitamente indicado.
Criando travas
No repositrio Subversion, uma trava um pedao de metadados que concede acesso exclusivo
para um usurio modificar um arquivo. Este usurio chamado de proprietrio da trava. Cada trava
tambm tem um identificador nico, tipicamente uma longa cadeia de caracteres, conhecida como o
sinal de trava. O repositrio gerencia as travas, basicamente manipulando sua criao, aplicao e
remoo. Se qualquer transao de submisso tenta modificar ou excluir um arquivo travado (ou excluir
um dos diretrios pais do arquivo), o repositrio exigir dois pedaos de informaoque o cliente
executante da submisso esteja autenticado como o proprietrio da trava, e que o sinal de trava tenha
sido fornecido como parte do processo de submisso como um tipo de prova que o cliente conhece
qual trava ele est usando.
Para demonstrar a criao de uma trava, vamos voltar ao nosso exemplo de mltiplos desenhistas
grficos trabalhando sobre os mesmos arquivos binrios de imagem. Harry decidiu modificar uma
imagem JPEG. Para prevenir que outras pessoas submetessem mudanas no arquivo enquanto ele
est modificando-o (bem como alertando-os que ele est prestes a mud-lo), ele trava o arquivo no
repositrio usando o comando svn lock.
Existe uma srie de novas coisas demonstradas no exemplo anterior. Primeiro, note que Harry passou
a opo --message (-m) para o comando svn lock. Similar ao svn commit, o comando svn
lock pode receber comentrios (seja via --message (-m) ou --file (-F)) para descrever a
razo do travamento do arquivo. Ao contrrio do svn commit, entretanto, o svn lock no exigir uma
mensagem executando seu editor de texto preferido. Os comentrios de trava so opcionais, mas ainda
recomendados para ajudar na comunicao.
Em segundo lugar, a trava foi bem sucedida. Isto significa que o arquivo no estava travado, e que
Harry tinha a mais recente verso do arquivo. Se o arquivo da cpia de trabalho de Harry estivesse
desatualizado, o repositrio teria rejeitado a requisio, forando Harry a executar svn update e tentar
o comando de travamento novamente. O comando de travamento tambm teria falhado se o arquivo
j estivesse travado por outro usurio.
Como voc pode ver, o comando svn lock imprime a confirmao do sucesso no travamento. A
partir deste ponto, o fato de que o arquivo est travado torna-se aparente na sada dos relatrios dos
subcomandos svn status e svn info.
55
Tpicos Avanados
$ svn status
K banana.jpg
O comando svn info, o qual no consulta o repositrio quando executa sobre caminhos de uma cpia
de trabalho, pode mostrar o sinal de trava e revela um importante fato sobre o sinal de travaque eles
so colocados em cache na cpia de trabalho. A presena do sinal de trava crtica. Ele d cpia de
trabalho a autorizao para fazer uso da trava mais tarde. Alm disso, o comando svn status mostra
um K prximo ao arquivo (abreviao para locKed), indicando que o sinal de trava est presente.
Por exemplo, suponha que voc travou um arquivo usando um computador em seu escritrio, mas
deixou o trabalho antes de concluir suas modificaes para esse arquivo. No deveria ser possvel
acidentalmente submeter mudanas para esse mesmo arquivo do seu computador de casa mais
tarde da noite, simplesmente porque voc est autenticado como o proprietrio da trava. Em
outras palavras, o sinal de trava previne uma parte do software relacionado ao Subversion de
invadir o trabalho do outro. (Em nosso exemplo, se voc realmente precisa modificar o arquivo
de uma cpia de trabalho alternativa, voc precisaria parar a trava e retravar o arquivo.)
Agora que Harry tem o arquivo banana.jpg travado, Sally no poder modificar ou excluir esse
arquivo:
56
Tpicos Avanados
svn: DELETE of
'/repos/project/!svn/wrk/64bad3a9-96f9-0310-818a-df4224ddc35d/banana.jpg':
423 Locked (http://svn.example.com)
$
Porm Harry, aps retocar a tonalidade amarela da banana, capaz de submeter suas mudanas no
arquivo. Isso porque ele se autenticou como o proprietrio da trava, e tambm porque sua cpia de
trabalho possui o sinal de trava correto:
$ svn status
M K banana.jpg
$ svn commit -m "Torna a banana mais amarela"
Sending banana.jpg
Transmitting file data .
Committed revision 2201.
$ svn status
$
Note que aps a submisso ser concluda, svn status mostra que o sinal de trava no est mais
presente na cpia de trabalho. Este o comportamento padro de svn commitele procura na cpia
de trabalho (ou lista de alvos, se voc fornecer uma lista desse tipo) por modificaes locais, e envia
todos os sinalizadores de trava encontrados durante esta caminhada para o servidor como parte da
transao de submisso. Aps a submisso concluir com sucesso, todas as travas do repositrio que
forem mencionadas so liberadasat mesmo em arquivos que no foram submetidos. Isto utilizado
para que os usurios no sejam desleixados com os travamentos, ou segurem travas por muito tempo.
Se Harry trava de forma desorganizada trinta arquivos em um diretrio nomeado images porque no
tem certeza de quais arquivos ele precisa modificar, por ora apenas modifica quatro destes arquivos,
quando ele executar svn commit images, o processo mesmo assim liberar todas as trinta travas.
Este comportamento de liberar as travas automaticamente pode ser evitado com a passagem da
opo --no-unlock ao comando svn commit. Isso tem melhor uso para aqueles casos quando voc
quer submeter mudanas, mas ainda planeja fazer mais mudanas e, portanto, precisa conservar as
travas existentes. Voc tambm pode fazer este seu comportamento padro configurando a opo no-
unlock do seu ambiente de execuo (veja rea de Configurao do Tempo de Execuo).
Evidentemente, travar um arquivo no o obriga a submeter uma mudana para ele. A trava pode ser
liberada a qualquer tempo com um simples comando svn unlock:
Descobrindo as travas
Quando uma submisso falha devido a um trava que outra pessoa criou, bastante fcil ver os detalhes
sobre ela. A forma mais fcil delas svn status --show-updates:
$ svn status -u
M 23 bar.c
M O 32 raisin.jpg
* 72 foo.h
Status against revision: 105
$
Neste exemplo, Sally pode ver no somente que sua cpia de foo.h est desatualizada, mas que
um dos dois arquivos modificados que ela planeja submeter est travado no repositrio. O smbolo
57
Tpicos Avanados
O corresponde a Other, significando que existe uma trava sobre o arquivo, e foi criada por outra
pessoa. Se ela vier a tentar uma submisso, a trava sobre raisin.jpg a impediria. Sally deve estar
imaginando quem fez a trava, quando, e porqu. Mais uma vez, svn info tem as respostas:
Assim como svn info pode ser usado para examinar objetos na cpia de trabalho, ele tambm pode ser
usado para examinar objetos no repositrio. Se o argumento principal para svn info um caminho de
uma cpia de trabalho, ento todas informaes em cache da cpia de trabalho so exibidas; qualquer
meno a uma trava significa que a cpia de trabalho est mantendo um sinal de trava (se um arquivo
travado por outro usurio ou em outra cpia de trabalho, svn info em um caminho de cpia de trabalho
no mostrar qualquer informao da trava). Se o argumento principal para svn info uma URL, ento
as informaes refletem a mais recente verso de um objeto no repositrio, e qualquer meno a uma
trava descreve a atual trava sobre o objeto.
Portanto, neste exemplo particular, Sally pode ver que Harry travou o arquivo em 16 de Fevereiro
para fazer um ajuste rpido. J estando em Junho, ela suspeita que ele provavelmente se esqueceu
totalmente da trava. Ela poderia ligar para Harry para reclamar e lhe pedir que libere a trava. Se ele
estiver indisponvel, ela poder tentar quebrar a trava a fora ou solicitar um administrador para o fazer.
Path: /project/raisin.jpg
UUID Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
58
Tpicos Avanados
Owner: harry
Created: 2006-02-16 13:29:18 -0500 (Thu, 16 Feb 2006)
Expires:
Comment (1 line):
Necessidade de fazer um ajuste rpido nesta imagem.
Uma opo mais interessante permitir que usurios quebrem as travas de outros atravs da rede. Para
fazer isto, Sally simplesmente precisa passar a opo --force para o comando de destravamento:
$ svn status -u
M 23 bar.c
M O 32 raisin.jpg
* 72 foo.h
Status against revision: 105
$ svn unlock raisin.jpg
svn: 'raisin.jpg' is not locked in this working copy
$ svn info raisin.jpg | grep URL
URL: http://svn.example.com/repos/project/raisin.jpg
$ svn unlock http://svn.example.com/repos/project/raisin.jpg
svn: Unlock request failed: 403 Forbidden (http://svn.example.com)
$ svn unlock --force http://svn.example.com/repos/project/raisin.jpg
'raisin.jpg' unlocked.
$
Agora, a tentativa inicial de Sally para destravar falhou porque ela executou svn unlock diretamente
em sua cpia de trabalho do arquivo, e nenhum sinal de trava estava presente. Para remover a trava
diretamente do repositrio, ela precisa passar uma URL para svn unlock. Sua primeira tentativa para
destravar a URL falhou, porque ela no pode autenticar como a proprietria da trava (nem ela possui
o sinal de trava). Mas quando ela passa --force, os requisitos de autenticao e autorizao so
ignorados, e a trava remota agora est quebrada.
Simplesmente quebrar uma trava pode no ser suficiente. No exemplo atual, Sally pode no somente
querer quebrar a trava esquecida a longo prazo por Harry, mas tambm retravar o arquivo para seu
prprio uso. Ela pode realizar isto executando svn unlock --force e ento svn lock logo em seguida,
mas existe uma pequena chance de que outra pessoa possa travar o arquivo entre os dois comandos.
Uma coisa mais simples roubar a trava, que envolve quebrar e retravar o arquivo em um passo
atmico. Para fazer isto, Sally passa a opo --force para svn lock:
Em qualquer caso, se a trava quebrada ou roubada, Harry ter uma surpresa. A cpia de trabalho de
Harry ainda contm o sinal original da trava, mas esta trava no existe mais. O sinal da trava est agora
extinto. A trava representada pelo sinal de trava, ou ter sido quebrada (no est mais no repositrio),
ou roubada (substituda por uma trava diferente). De qualquer forma, Harry pode ver isto pedindo para
svn status verificar o repositrio:
$ svn status
K raisin.jpg
59
Tpicos Avanados
$ svn status -u
B 32 raisin.jpg
$ svn update
B raisin.jpg
$ svn status
$
Se a trava foi quebrada no repositrio, ento svn status --show-updates exibe um smbolo B (Broken)
prximo ao arquivo. Se uma nova trava existe no lugar da anterior, ento um smbolo T (sTolen)
mostrado. Finalmente, svn update relata os sinais de trava existentes e os remove da cpia de trabalho.
Polticas de Travamento
Diferentes sistemas possuem diferentes noes de como rigorosa uma trava deve ser. Algumas
pessoas afirmam que travas devem ser estritamente aplicadas a todo custo, liberveis somente
pelo criador original ou administrador. Eles argumentam que se qualquer um pode quebrar uma
trava, ento o caos corre galopante e toda circunstncia de travamento derrotada. O outro lado
afirma que travas so, antes de mais nada, uma ferramenta de comunicao. Se usurios esto
constantemente quebrando as travas de outros, ento ele representa um fracasso cultural dentro
da equipe e o problema sai fora do escopo da aplicao de software.
Por padro o Subversion possui uma abordagem branda, mas ainda permite que
administradores criem polticas de aplicao mais rigorosas atravs da utilizao de scripts de
gancho. Em particular, os ganchos pre-lock e pre-unlock permitem aos administradores
decidir quando a criao e liberao de travas so autorizadas a acontecer. Dependendo se uma
trava j existe ou no, estes dois ganchos podem decidir se permitem ou no que um certo usurio
pode quebrar ou roubar uma trava. Os ganchos post-lock e post-unlock tambm esto
disponveis, e podem ser usados para enviar e-mail aps aes de travamento. Para aprender
mais sobre ganhos de repositrio, veja Implementando Ganchos de Repositrio.
Comunicao de Travas
Vimos como svn lock e svn unlock podem ser usados para criar, liberar, quebrar, e roubar travas.
Isso satisfaz o objetivo de serializar o acesso a submisses de um arquivo. Mas o que aconteceu com
o maior problema da preveno de perda de tempo?
Por exemplo, suponha que Harry trave um arquivo de imagem e, em seguida, inicie sua edio.
Entretanto, a milhas de distncia, Sally deseja fazer a mesma coisa. Ela no pensa em executar svn
status --show-updates, portanto ele no tem idia de que Harry j tenha travado o arquivo. Ela gasta
horas editando o arquivo, e quando ela tenta submeter sua mudana, ela descobre que ou o arquivo
est travado ou que ela est desatualizada. Indiferente disso, suas alteraes no so mesclveis com
as de Harry. Uma destas duas pessoas tem que jogar fora seu trabalho, e um monte de tempo foi
perdido.
A soluo do Subversion para este problema oferecer um mecanismo para avisar aos usurios que
um arquivo deve ser travado antes de iniciar sua edio. O mecanismo uma propriedade especial,
svn:needs-lock. Se esta propriedade est anexada a um arquivo (indiferente de seu valor, o qual
irrelevante), ento o Subversion tentar utilizar permisses a nvel de sistema de arquivo para tornar
o arquivo somente leituraexceto, claro, o usurio tiver explicitamente travado o arquivo. Quando um
sinal de trava est presente (como resultado de executar svn lock), o arquivo fica como leitura e escrita.
Quando a trava liberada, o arquivo fica como somente leitura novamente.
A teoria, ento, que se o arquivo de imagem tem esta propriedade anexada, ento Sally iria
verificar imediatamente que alguma coisa est estranho quando ela abrir o arquivo para edio: muitas
aplicaes avisam os usurios imediatamente quando um arquivo somente leitura aberto para edio,
e quase todos impedem que alteraes sejam salvas no arquivo. Isto lembra ela para travar o arquivo
antes de edit-lo, e ento ela descobre a trava j existente:
60
Tpicos Avanados
$ /usr/local/bin/gimp raisin.jpg
gimp: error: file is read-only!
$ ls -l raisin.jpg
-r--r--r-- 1 sally sally 215589 Jun 8 19:23 raisin.jpg
$ svn lock raisin.jpg
svn: Lock request failed: 423 Locked (http://svn.example.com)
$ svn info http://svn.example.com/repos/project/raisin.jpg | grep Lock
Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
Lock Owner: harry
Lock Created: 2006-06-08 07:29:18 -0500 (Thu, 08 June 2006)
Lock Comment (1 line):
Fazendo alguns ajustes. Travando para as prximas duas horas.
$
Infelizmente, o sistema no perfeito. possvel que mesmo quando um arquivo possua a propriedade,
a advertncia de somente leitura nem sempre funcione. Algumas vezes as aplicaes comportam-se
mal e adulteram o arquivo somente leitura, silenciosamente permitindo aos usurios editar e salvar o
arquivo de qualquer forma. No h muito que o Subversion possa fazer nesta situaode qualquer
9
maneira, simplesmente no h substituio para uma boa comunicao entre as pessoas.
Definies Externas
s vezes, til construir uma cpia de trabalho que composta por diferentes checkouts. Por exemplo,
talvez voc queira que diferentes subdiretrios venham de diferentes locais em um repositrio, ou at
mesmo de diferentes repositrios. Voc poderia configurar tal cenrio manualmente usando svn
checkout para criar o tipo de estrutura aninhada de cpia de trabalho que voc est tentando construir.
Mas, se essa estrutura importante para todos os que usam seu repositrio, todos os outros usurios
precisaro realizar as mesmas operaes de checkout que voc fez.
Felizmente, o Subversion prov suporte para definies externas. Uma definio externa um
mapeamento de um diretrio local para a URLe, idealmente, uma determinada revisode um
diretrio sob controle de verso. No Subversion, voc declara definies externas em conjunto usando a
propriedade svn:externals. Voc pode criar ou modificar essa propriedade usando svn propset ou
svn propedit (veja Manipulando Propriedades). Essa propriedade pode ser configurada em qualquer
diretrio sob controle de verso, e seu valor uma tabela multilinha de subdiretrios (relativos ao
diretrio sob controle de verso no qual a propriedade est configurada), opes de reviso, e URLs
absolutas (totalmente qualificadas) de repositrios Subversion.
61
Tpicos Avanados
beneficiada pelas definies externas. Em outras palavras, uma vez que algum investiu tempo e
esforo para definir essa cpia de trabalho feita de checkouts aninhados, ningum mais precisa se
incomodaro Subversion, atravs do checkout da cpia de trabalho original, tambm obter as cpias
de trabalho externas.
Os subdiretrios alvos relativos das definies externas no podem existir no seu sistema
de arquivos nem no de outros usurioso Subversion ir cri-los quando obter a cpia
de trabalho externa.
Note o exemplo anterior de definies externas. Quando algum obtm uma cpia de trabalho do
diretrio calc, o Subversion tambm obtm os itens encontrados nas suas definies externas.
A calc/third-party/sounds/bang.ogg
A calc/third-party/sounds/twang.ogg
Checked out revision 14.
Se voc precisar mudar as definies externas, voc pode fazer isso usando os subcomandos para
modificao de propriedades normalmente. Quando voc submeter uma alterao na propriedade
svn:externals, o Subversion ir sincronizar os itens submetidos com as definies externas
na prxima vez que voc executar um svn update. A mesma coisa ir acontecer quando outros
atualizarem suas cpias de trabalho e recebam as suas modificaes nas definies externas.
O comando svn status tambm reconhece definies externas, exibindo um cdigo de status X para
subdiretrios desmembrados nos quais as externas foram obtidas, e ento varrer recursivamente
dentro destes subdiretrios para mostrar o status dos prprios itens externos.
62
Tpicos Avanados
O suporte que existe para definies externas no Subversion ainda est abaixo do ideal. Primeiro,
uma definio externa pode apenas apontar para diretrios, no para arquivos. Segundo, as definies
externas no podem apontar para caminhos relativos (tais como ../../skins/myskin). Terceiro,
o suporte a cpias de trabalho criadas por meio de definies externas ainda est desconectado da
cpia de trabalho primria (na qual a propriedade svn:externals dos diretrios versionados foi
atualmente definida). E o Subversion ainda s pode operar verdadeiramente em cpias de trabalho no-
desmembradas. Ento, por exemplo, se voc quiser submeter as alteraes que voc tenha feito em um
ou mais destas cpias de trabalho externas, voc deve executar um svn commit explicitamente nessas
cpias de trabalhosubmeter alteraes numa cpia de trabalho no ir implicar numa recurso dentro
de nenhuma das externas.
Agora voc executa svn move para renomear o diretrio my-project directory. Neste ponto, sua
definio externa ainda vai se referir ao caminho relacionado ao diretrio my-project, muito embora
esse diretrio no exista mais.
E tambm, as URLs absolutas que as definies externas usam podem causar problemas com
repositrios que estejam disponveis a partir de mltiplos esquemas de URL. Por exemplo, se
seu servidor Subversion estiver configurado para permitir que qualquer um obtenha o contedo do
repositrio por meio de http:// ou https://, mas que apenas possam submeter alteraes atravs
de https://, voc tem um interessante problema em mos. Se suas definies externas usam o
formato http:// para URLs do repositrio, voc no ser capaz de submeter nada a partir das cpias
de trabalho criadas por definies externas. Por outro lado, se elas usam o formato https:// para
URLs, qualquer pessoa que tenha obtido a cpia atravs de http:// por no ter um cliente com
63
Tpicos Avanados
suporte a https:// estar impossibilitado de buscar itens externos. Atente tambm que se voc
precisar realocar sua cpia de trabalho (usando svn switch --relocate), suas definies externas no
sero realocadas.
Finalmente, pode ser que algumas vezes voc prefira que os subcomandos no reconheam svn, ou
mesmo no operem sobre cpias de trabalhos externas. Nesses casos, voc pode passar a opo --
ignore-externals para o subcomando.
O Subversion muito esperto ao perceber quando uma verso do histrico do objeto inclui tais
mudanas de endereo. Por exemplo, se voc pedir pelo registro do histrico de reviso de um arquivo
especfico que foi renomeado na ltima semana, o Subversion felizmente oferece todos estes registros
a reviso na qual a renomeao aconteceu, mais os registros de revises relevantes tanto antes
como depois que foi renomeado. Assim, a maioria das vezes, voc no ter que pensar sobre estas
coisas. Mas ocasionalmente, o Subversion precisar de sua ajuda para esclarecer ambigidades.
O exemplo mais simples disto ocorre quando um diretrio ou arquivo excludo do controle de verso,
e ento um novo diretrio ou arquivo criado com o mesmo nome e adicionado ao controle de
verso. Obviamente o que voc exclui e o que voc depois adicionou no so a mesma coisa. Estas
coisas meramente possuram o mesmo caminho, /trunk/object por exemplo. Ento, o que significa
solicitar ao Subversion o histrico de /trunk/object? Voc est pedindo sobre o objeto atualmente
neste local, ou o antigo objeto que voc excluiu deste local? Voc est pedindo sobre as operaes que
aconteceram em todos os objetos que alguma vez existiu neste caminho? Obviamente, o Subversion
precisa de uma dica do que voc realmente quer.
Devido a mudanas regulares, o histrico de um objeto versionado pode ser mais misturado do que
isto. Por exemplo, voc pode ter um diretrio nomeado concept, contendo algum projeto de software
pessoal em que voc esteja brincando. Eventualmente, porm, este projeto amadurece a tal ponto que
a idia parece realmente poder decolar, assim voc faz o impensvel e decide dar um nome ao projeto.
10
Vamos dizer que voc chamou seu software de Frabnaggilywort. Neste ponto, faz sentido renomear
o diretrio para refletir o novo nome do projeto, assim concept renomeado para frabnaggilywort.
A vida continua, Frabnaggilywort lana uma verso 1.0, e est sendo baixado e usado diariamente por
uma multido de pessoas que pretendem melhorar suas vidas.
uma bela histria, realmente, mas no termina aqui. Como empreendedor que voc , voc j est
com novas idias em mente. Ento voc cria um novo diretrio, concept, e o ciclo comea outra vez.
De fato, o ciclo recomea muitas vezes ao longo dos anos, cada vez comeando com o antigo diretrio
concept, ento algumas vezes vendo esse diretrio ser renomeado como voc bem o quiser, algumas
vezes vendo esse diretrio ser excludo quando voc descarta a idia. Ou, para complicar de vez,
algumas vezes talvez voc concept para qualquer outra coisa por algum tempo, mas depois renomei-
o de volta para concept por alguma razo.
Em cenrios como este, tentar instruir o Subversion para trabalhar com estes caminhos reutilizados
pode ser um pouco como instruir um motorista dos subrbios da Chicago ocidental a dirigir sempre a
leste na estrada Roosevelt Road e ento virar esquerda na Main Street. Em meros vinte minutos,
voc pode cruzar com a tal Main Street ao andar pela Wheaton, Glen Ellyn ou Lombard. E no, elas
10
Voc no pretendia dar um nome a ele. Depois que voc d um nome, voc comea a ficar ligado a ele.Mike Wazowski
64
Tpicos Avanados
Na verso 1.1, o Subversion introduziu uma maneira para voc dizer exatamente que Main Street voc
se refere. chamada de reviso marcadora, e uma reviso disponibilizada pelo Subversion apenas
com propsito de identificar uma linha nica de histrico. Como no mximo um objeto versionado
pode ocupar um caminho em um dado instanteou, mais precisamente, em uma dada revisoa
combinao de um caminho e uma reviso marcadora tudo o que necessrio para se referenciar
a uma linha especfica de histrico. Revises marcadoras so especificadas pelo cliente de linha de
11
comando do Subversion usando sintaxe de arroba , assim chamada porque envolve anexar-se um
sinal de arroba (@) e a reviso marcadora ao final do caminho com o qual a reviso est associada.
Mas e sobre as revises dadas por --revision (-r), as quais falamos tanto neste livro? Essas
revises (ou conjuntos de revises) so chamadas de revises operativas (ou intervalos de revises
operativas). Uma vez que uma linha em particular do histrico tenha sido identificada usando-se
um caminho e uma reviso marcadora, o Subversion executa a operao requisitada usando a(s)
reviso(es) operativa(s). Para relacionar isto com nossa analogia s ruas de Chicago, se nos disserem
12
para irmos para at a Main Street em Wheaton 606 N., poderamos pensar na Main Street como
nosso caminho e em Wheaton como nossa reviso marcadora. Estes dois pedaos de informao
identificam um nico caminho que pode ser percorrido (em sentido sul ou sentido norte na Main Street),
e que nos permitir andar para cima e para baixo na Main Street ao acaso na busca pelo nosso destino.
Agora temos 606 N. como nossa reviso operativa, de sorte que sabemos exatamente aonde temos
que ir.
11
N.T.: Em ingls, o smbolo de arroba lido como at, que tem o sentido de em ou naquele lugar.
12
Main Street, Wheaton, 606 N., Illinois, o endereo do Wheaton History Center. SacouHistory Center? Parece apropriado.
65
Tpicos Avanados
Se OPERATIVE-REV for mais antiga que PEG-REV, ento o algoritmo ser o seguinte:
Localize o item na reviso identificada por PEG-REV. Deve ser encontrado apenas um nico
objeto.
Execute a ao requisitada naquele ancestral, onde quer que ele se encontre, ou qualquer que
seja o nome que ele tenha ou que tenha tido ao longo do tempo.
Mas e se OPERATIVE-REV for mais recente que PEG-REV? Bem, isso adiciona alguma
complexidade ao problema terico de localizao do caminho em OPERATIVE-REV, pois o
histrico do caminho pode ter sido ramificado vrias vezes (graas a operaes de cpia)
entre PEG-REV e OPERATIVE-REV. E isso no tudode qualquer maneira, o Subversion no
armazena informao o suficiente para traar eficientemente o histrico das revises frente para
um objeto. Assim, o algoritmo neste caso um pouco diferente:
Localize o item na reviso identificada por OPERATIVE-REV. Deve ser encontrado apenas
um nico objeto.
Note que mesmo quando voc no informa uma reviso marcadora ou uma reviso operativa, elas
ainda estaro presentes. Para sua convenincia, BASE tida como reviso marcadora padro
para itens em sua cpia de trabalho e HEAD o para URLs do repositrio. E quando nenhuma
reviso operativa for informada, por padro ser usada a mesma que a da reviso marcadora.
Digamos que tenhamos criado nosso repositrio muito tempo atrs, e que na reviso 1 adicionamos
nosso primeiro diretrio concept, alm de um arquivo IDEA nesse diretrio contendo as idias
relacionadas ao conceito. Depois de algumas revises nas quais cdigos reais foram adicionados e
manipulados, ns, na reviso 20, renomeamos este diretrio para frabnaggilywort. L pela reviso
27, temos um novo conceito, e criamos um novo diretrio concept para armazen-lo, e um novo
arquivo IDEA para descrev-lo. E assim, cinco anos e vinte mil revises se passaram, tal como seria
em qualquer histria de romance que se preze.
Agora, anos depois, nos questionamos como seria ter de volta o arquivo IDEA tal como na reviso
1. Mas o Subversion precisa saber se ns estamos querendo saber sobre como o atual arquivo se
pareceria na reviso 1, ou se estamos solicitando o contedo de qualquer que fosse o arquivo que
estivava como concepts/IDEA na reviso 1. Certamente estas questes tm respostas diferentes, e
devido as revises marcadoras, possvel obter ambas as respostas. Para ver como o arquivo IDEA
atual era naquela reviso antiga, voc executa:
66
Tpicos Avanados
claro, neste exemplo, o atual arquivo IDEA no existia ainda na reviso 1, ento o Subversion lhe
exibe um erro. O comando acima uma verso resumida para uma notao mais longa que relaciona
explicitamente uma reviso marcadora. A notao expandida :
Neste ponto, provavelmente o leitor mais atento est se perguntando se a sintaxe de revises
marcadoras causa problemas em caminhos na c[opia de trabalho ou em URLs que atualmente tenham
sinais em si mesmas. Depois de tudo, como o svn sabe se news@11 o nome de um diretrio em
minha rvore, ou se apenas uma sintaxe para a reviso 11 de news? Felizmente, ainda que o
svn considere sempre esta ltima opo, existe uma regra trivial. Voc s precisa adicionar um sinal
de arroba ao final do caminho, como em news@11@. O svn s ir se importar com o ltimo sinal de
arroba no argumento, e que no seja considerado ilegal omitir um especificador do nmero da reviso
marcadora depois desse arroba. Esta regra tambm se aplica a caminhos que terminal com um sinal
de arrobavoc poderia usar filename@@ para se referir a um arquivo chamado filename@.
Vamos considerar a outra questo, entona reviso 1, como era estava o contedo de qualquer que
seja o arquivo que estava ocupando o endereo concepts/IDEA naquele momento? Vamos usar
explicitamente uma reviso marcadora para nos ajudar.
Perceba que ns no informamos uma reviso operativa neste momento. Isso se deve porque quando
uma reviso operativa no especificada, o Subversion assume como padro uma reviso operativa
que a mesma da reviso marcadora.
Como voc pode ver, a sada da execuo de nosso comando parece estar correta. O texto ainda
menciona frabbing naggily worts, ento isto certamente o arquivo que descreve o software agora
chamado de Frabnaggilywort. De fato, podemos verificar isto usando a combinao de uma reviso
marcadora e uma reviso operativa. Ns sabemos que em HEAD, o projeto Frabnaggilywort est
localizado no diretrio frabnaggilywort. Ento ns especificamos que queremos ver como a linha
de histrico identificada em HEAD como o caminho frabnaggilywort/IDEA se parecia na reviso 1.
E as revises marcadora e operativa nem precisam ser to triviais. Por exemplo, digamos que
frabnaggilywort esteja removido na reviso HEAD, mas ns sabemos que esse diretrio existia
na reviso 20, e ns queremos ver as diferenas de seu arquivo IDEA entre as revises 4 e 10. Ns
podemos usar a reviso marcadora 20 em conjunto com a URL que deveria conter o diretrio IDEA
67
Tpicos Avanados
do diretrio Frabnaggilywort na reviso 20, e ento usar 4 e 10 como nosso intervalo de revises
operativas.
Felizmente, a maioria das pessoas no se deparam com situaes to complexas desse tipo. Mas se
um dia voc se deparar, lembre-se que revises marcadoras so um recurso extra de que o Subversion
precisa para reslver ambiguidades.
Modelo de Rede
Em algum momento, ser necessrio compreender como seu cliente Subversion comunica com
seu servidor. A camada de rede do Subversion abstrata, significando que os clientes Subversion
apresentam o mesmo comportamento geral no importando com que tipo de servidor eles esto
operando. Seja comunicando no protocolo HTTP (http://) com o Servidor HTTP Apache ou
comunicando no protocolo personalizado do Subversion (svn://) com svnserve, o modelo de rede
bsico o mesmo. Nesta seo, vamos explicar os princpios bsicos deste modelo de rede, incluindo
como o Subversion gerencia as questes de autenticao e autorizao.
Solicitaes e Respostas
O cliente Subversion passa a maior parte de seu tempo gerenciando cpias de trabalho. Quando ele
precisa de informaes de um repositrio remoto, entretanto, ele efetua uma solicitao de rede, e o
servidor responde com uma resposta apropriada. Os detalhes do protocolo de rede esto escondidos do
usurioo cliente tenta acessar uma URL, e dependendo do esquema na URL, um protocolo especfico
usado para comunicar com o servidor (veja URLs do Repositrio).
Execute svn --version para ver quais esquemas de URL e protocolos que o cliente sabe
como usar.
Quando o processo servidor recebe uma requisio do cliente, ele quase sempre solicita que o cliente
se identifique. Ele lana um desafio de autenticao para o cliente, e o cliente responde enviando de
volta suas credenciais ao servidor. Quando a autenticao for concluda, o servidor responde com
a informao original a qual o cliente requisitou. Perceba que este sistema diferente de sistemas
como o CVS em que o cliente oferece credenciais preemptivamente (efetua um login) ao servidor
antes de fazer uma requisio. No Subversion, o servidor que pega as credenciais desafiando o
cliente no momento adequado, ao invs de o cliente ter de inser-las. Isto torna certas operaes mais
elegantes. Por exemplo, se um servidor estiver configurado para permitir globalmente que qualquer
um leia o repositrio, ento o servidor nunca vai emitir um desafio de autenticao quando o cliente
executar um svn checkout.
68
Tpicos Avanados
Se uma dada requisio de rede feita pelo cliente resultar em uma nova reviso sendo criada no
repositrio (p.ex. svn commit), ento o Subversion usa o nome de usurio autenticado associado a
essas requisies como autor da reviso. Isto , o nome do usurio autenticado armazenado como o
valor da propriedade svn:author na nova reviso (veja Propriedades do Subversion). Se o cliente
no estava autenticado (em outras palavras, se o servidor nunca lanara um desafio de autenticao),
ento a propriedade svn:author ser vazia.
Quando o cliente recebe um desafio de autenticao, ele primeiro procura pelas credenciais
apropriadas na cache em disco do usurio. Se aparentemente nenhuma credencial apta est presente,
ou se em ltimo caso a credencial armazenada falhar ao autenticar, ento o cliente, por padro, voltar
a solicitar ao usurio pela informao necessria.
O leitor consciente de segurana suspeitar imediatamente que h motivo para preocupao aqui.
Armazenar senhas em disco? Isto terrvel! Voc nunca deve fazer isto!
Para outros sistemas operacionais baseado em Unix, nenhum servio de keychain existe. No
entanto, a rea de armazenamento auth/ ainda protegida por permisso para que somente o
usurio (proprietrio) possa ler dados dela, no todos em geral. As permisses de arquivo do prprio
sistema operacional protege as senhas.
Claro que, para o paranico de verdade, nenhum destes mecanismos satisfaz o teste de perfeio.
Ento, para aqueles dispostos a sacrificar a convenincia pela segurana extrema, o Subversion
oferece vrios meios de desabilitar seu sistema de armazenamento de credenciais completamente.
69
Tpicos Avanados
Username: joe
Password for 'joe':
Adding newfile
Transmitting file data .
Committed revision 2324.
Ou, se voc quiser desabilitar o armazenamento de credencial permanentemente, voc pode editar o
arquivo config em sua rea de configurao do ambiente de execuo, e defina a opo store-
auth-creds para no. Isso evitar o armazenamento de credenciais usadas em qualquer interao que
voc efetuar com o Subversion no computador afetado. Isso pode ser estendido a todos os usurios
no computador, tambm, ao modificar a rea de configurao do sistema como um todo (descrito em
Estrutura da rea de Configurao).
[auth]
store-auth-creds = no
Algumas vezes os usurios podero querer remover credenciais especficas da cache em disco. Para
fazer isso, voc precisa ir at a rea auth/ e excluir manualmente o arquivo de cache apropriado. As
credenciais so armazenadas em arquivos individuais; se voc olhar dentro de cada arquivo, voc ver
chaves e valores. A chave svn:realmstring descreve o domnio do servidor especfico ao qual o
arquivo est associado:
$ ls ~/.subversion/auth/svn.simple/
5671adf2865e267db74f09ba6f872c28
3893ed123b39500bca8a0b382839198e
5c3c22968347b390f349ff340196ed39
$ cat ~/.subversion/auth/svn.simple/5671adf2865e267db74f09ba6f872c28
K 8
username
V 3
joe
K 8
password
V 4
blah
K 15
svn:realmstring
V 45
<https://svn.domain.com:443> Joe's repository
END
70
Tpicos Avanados
Conforme discutido anteriormente, o servidor puxa as credenciais do cliente quando julgar necessrio;
o cliente no pode empurr-las vontade. Se um nome de usurio e/ou senha so passados como
13
opes, elas somente sero apresentadas ao servidor se o servidor solicitar elas. Estas opes
so normalmente utilizadas para autenticar como um usurio diferente daquele que o Subversion teria
optado por padro (como seu nome de usurio no sistema), ou quando tenta-se evitar as perguntas
interativas (como nas chamadas ao comando svn a partir de um script).
Aqui est um resumo final que descreve como um cliente Subversion se comporta quando ele recebe
um desafio de autenticao.
1. Primeiro, o cliente verifica se o usurio especificou alguma credencial na linda de comando com as
opes (--username e/ou --password). Se no, ou se essas opes no conseguem autenticar
com sucesso, ento
2. o cliente procura pelo nome, porta e domnio do servidor na rea auth/ do ambiente de execuo,
para ver se o usurio j possui as credenciais em cache. Se no, ou se as credenciais em cache
no conseguem autenticar, ento
3. finalmente, o cliente solicita as credenciais ao usurio (a menos que seja instrudo a no fazer isso
atravs da opo --non-interactive ou suas equivalentes especficas do cliente).
Se o cliente autentica-se com sucesso por qualquer dos mtodos listados acima, ele tentar armazenar
as credenciais em disco (a menos que o usurio tenha desabilitado este comportamento, como
mencionado anteriormente).
13
Novamente, um erro comum deixar um servidor mal configurado de forma que ele nunca exija a autenticao do usurio.
Quando os usurios passam as opes --username e --password para o cliente, eles ficam surpresos ao ver que elas nunca
foram usadas, ou seja, novas revises parecem ter sido submetidas anonimamente!
71
Captulo 4. Fundir e Ramificar
( sobre o 'Tronco' que trabalha um cavalheiro.)
Confucio
Criar Ramos, Rtulos, e Fundir so conceitos comuns a quase todos os sistemas de controle de Verso.
Caso voc no esteja familiarizado com estes conceitos, ns oferecemos uma boa introduo a estes
nesse captulo. Se voc j conhece estes conceitos, ento voc vai achar interessante conhecer a
maneira como o Subversion os implementa.
Criar Ramos um item fundamental para Controle de Verso. Se voc vai usar o Subversion para
gerenciar seus dados, ento essa uma funcionalidade da qual voc vai acaber dependendo. Este
captulo assume que voc j esteja familiarizado com os conceitos bsicos do Subversion(Captulo 1,
Conceitos Fundamentais).
O que um Ramo?
Suponha que o seu trabalho seja manter um documento de uma diviso de sua empresa, um livro
de anotaes por exemplo. Um dia, uma outra diviso lhe pede este mesmo livro, mas com alguns
ajustes para eles, uma vez que eles trabalham de uma forma um pouco diferente.
O que voc faz nessa situao? Voc faz o bvio: faz uma segunda cpia do seu documento, e comea
a controlar as duas cpias separadamente. Quando cada departamento lhe requisitar alteraes, voc
as realizar em um cpia, ou na outra.
Em raros casos voc vai precisar fazer alteraes nos dois documentos. Um exemplo, se voc
encontrar um erro em um dos arquivos, muito provvel que este erro exista na segunda cpia. A final,
os dois documentos so quase idnticos, eles tm apenas pequenas diferenas, em locais especficos.
Este o conceito bsico de Ramoisto , uma linha de desenvolvimento que existe independente de
outra linha, e ainda, partilham um histrico em comum, se voc olhar para trs na linha tempo. Um
Ramo sempre se inicia como cpia de outra coisa, e segue rumo prprio a partir desse ponto, gerando
seu prprio histrico. (veja Figura 4.1, Ramos de desenvolvimento).
O Subversion tem comandos para ajudar a controlar Ramos paralelos de um arquivo ou diretrio. Ele
permite voc criar ramos copiando seus dados, e ainda lembra que as cpias tm relao entre si.
Ainda possvel duplicar cpias de um ramo para outro. Finalmente, ele pode fazer com que partes
de sua cpia de trabalho reflitam ramos diferentes, assim voc pode misturar e combinar diferentes
linhas de desenvolvimento no seu trabalho de dia-a-dia.
Usando Ramos
At aqui, voc j deve saber como cada commit cria uma nova rvore de arquivos (chamada de
reviso) no repositrio. Caso no saiba, volte e leia sobre revises em Revises.
72
Fundir e Ramificar
Neste captulo, vamos usar o mesmo exemplo de antes: Captulo 1, Conceitos Fundamentais. Lembre-
se que voc e Sally esto compartilhando um repositrio que contm dois projetos, paint e calc.
Note que em Figura 4.2, Layout Inicial do Repositrio, entretanto, cada diretrio de projeto contm
subdiretrios chamados trunk e branches. O motivo para isso logo ficar mais claro.
Como antes, assuma que voc e Sally possuem cpias de trabalho do projeto calc. Especificamente,
cada um de vocs tem uma cpia de trabalho de /calc/trunk. Todos os arquivos deste projeto esto
nesse diretrio ao invs de estarem no /calc, porque a sua equipe decidiu que /calc/trunk onde
a Linha Principal de desenvolvimento vai ficar.
Digamos que voc recebeu a tarefa de implementar uma grande funcionalidade nova no projeto. Isso
vai requerer muito tempo para escrever, e vai afetar todos os arquivos do projeto. O problema aqui que
voc no quer interferir no trabalho de Sally, que est corrigindo pequenos bugs aqui e ali. Ela depende
de que a ltima verso do projeto (em /calc/trunk) esteja sempre disponvel. Se voc comear a
fazer commits de suas modificaes pouco a pouco, com certeza voc vai dificultar o trabalho de Sally.
Um estratgia "se isolar": voc e Sally podem parar de compartilhar informaes por uma semana ou
duas. Isto , comear cortar e reorganizar todos os arquivos da sua cpia de trabalho, mas no realizar
commit ou update antes de ter terminado todo o trabalho. Existem alguns problemas aqui. Primeiro, no
seguro. A maioria das pessoas gostam de salvar seu trabalho no repositrio com frequncia, caso
algo ruim acontea por acidente cpia de trabalho. Segundo, no nada flexvel. Se voc faz seu
trabalho em computadores diferentes (talvez voc tenha uma cpia de trabalho de /calc/trunk em
duas mquinas diferentes), voc ter que, manualmente, copiar suas alteraes de uma mquina para
outra, ou simplesmente, realizar todo o trabalho em um nico computador. Por esse mesmo mtodo,
difcil compartilhar suas constantes modificaes com qualquer pessoa. Uma boa prtica comum em
desenvolvimento de software permitir que outros envolvidos revisem seu trabalho enquanto sendo
realizado. Se ningum verificar seus commits intermedirios, voc perde um potencial feedback. E por
fim, quando voc terminar todas as modificaes, voc pode achar muito difcil fundir seu trabalho
com o resto da linha principal de desenvolvimento da empresa. Sally (ou outros) podem ter realizado
muitas outras mudanas no repositrio que podem ser difceis de incorporar na sua cpia de trabalho
especialmente se voc rodar um svn update depois de semanas trabalhando sozinho.
73
Fundir e Ramificar
A melhor soluo criar seu prprio ramo, ou linha de desenvolvimento, no repositrio. Isso lhe permite
salvar seu trabalho ainda incompleto, sem interferir com outros, e ainda voc pode escolher que
informaes compartilhar com seus colaboradores. Voc ver exatamente como isso funciona mais
frente.
Criando um Ramo
Criar um ramo realmente simples voc faz uma cpia do projeto no repositrio usando o comando
svn copy. O Subversion copia no somente arquivos mas tambm diretrios completos. Neste caso,
voc quer fazer a cpia do diretrio /calc/trunk. Onde deve ficar a nova cpia? Onde voc quiser
isso depende da "poltica" do projeto. Digamos que sua equipe tem a poltica de criar novos ramos na
rea /calc/branches do repositrio, e voc quer chamar o seu ramo de my-calc-branch. Voc
vai querer criar um novo diretrio, /calc/branches/my-calc-branch, que inicia sua vida como
cpia de /calc/trunk.
H duas maneiras diferentes de fazer uma cpia. Vamos mostrar primeiro a maneira complicada,
apenas para deixar claro o conceito. Para comear, faa um checkout do diretrio raiz do projeto, /
calc:
Agora para fazer uma cpia basta passar dois caminhos de cpia de trabalho ao comando svn copy:
$ cd bigwc
$ svn copy trunk branches/my-calc-branch
$ svn status
A + branches/my-calc-branch
Neste caso, o comando svn copy faz uma cpia recursiva do diretrio trunk para um novo diretrio
de trabalho, branches/my-calc-branch. Como voc pode ver pelo comando svn status, o novo
diretrio est agendado para ser adicionado ao repositrio. Note tambm o sinal + prximo letra
A. Isso indica o item adicionado uma cpia de algo e no um item novo. Quando voc realizar o
Commit das modificaes, o Subversion vai criar o diretrio /calc/branches/my-calc-branch no
repositrio copiando /calc/trunk, ao invs de reenviar todos os dados da cpia de trabalho pela
rede:
E aqui est o mtodo mais fcil de criar um ramo, o qual ns deveramos ter lhe mostrado desde o
incio: o comando svn copy capaz de copiar diretamente duas URLs.
74
Fundir e Ramificar
Do ponto de vista do diretrio, no h diferena entre estes dois mtodos. Ambos os processos criam
um novo diretrio na reviso 341, e o novo diretrio uma cpia de /calc/trunk. Isso mostrado em
Figura 4.3, Repositrio com uma nova cpia. Note que o segundo mtodo, entretanto, faz um commit
1
imediato em tempo constante. Este um procedimento mais fcil, uma vez que voc no precisa
fazer o checkout de uma grande parte do repositrio. Na verdade, para usar esta tcnica voc no
precisa se quer ter uma cpia de trabalho. Esta a maneira que a maioria dos usurios criam ramos.
1
O Subversion no suporta a cpia entre repositrios distintos. Quando usando URLs com os comandos svn copy ou svn move,
voc pode apenas copiar itens dentro de um mesmo repositrio.
75
Fundir e Ramificar
Cpias Leves
O repositrio do Subversion tem um design especial. Quando voc copia um diretrio, voc no
precisa se preocupar com o repositrio ficando giganteO Subversion, na realidade, no duplica
dados. Ao invs disso, ele cria uma nova entrada de diretrio que aponta para uma outra rvore
de diretrio j existente. Caso voc seja um usurio Unix, esse o mesmo conceito do hard-link.
Enquanto as modificaes so feitas em pastas e arquivos no diretrio copiado, o Subversion
continua aplicando esse conceito de hard-link enquanto for possvel. Os dados somente sero
duplicados quando for necessrio desambiguizar diferentes verses de um objeto.
por isso que voc quase no vai ouvir os usurios do Subversion reclamando de Cpias
Leves (cheap copies). No importa o quo grande o diretrio a cpia sempre ser feita
em um pequeno e constante espao de tempo. Na verdade, essa funcionalidade a base do
funcionamento do commit no Subversion: cada reviso uma cpia leve da reviso anterior,
com algumas ligeiras modificaes em alguns itens.(para ler mais sobre esse assunto, visite o
website do Subversion e leia o mtodo bubble up nos documentos de design do Subversion.)
Claro que estes mecanismos internos de copiar e compartilhar dados esto escondidos do
usurio, que v apenas cpias das rvores de arquivos. O ponto principal aqui que as cpias so
leves, tanto em tempo quanto em tamanho. Se voc criar um ramo inteiro dentro do repositrio
(usando o comando svn copy URL1 URL2), ser uma operao rpida, e de tempo constante.
Crie ramos sempre que quiser.
No tem nada de especial nessa cpia de trabalho; ela simplesmente aponta para um diretrio diferente
no repositrio. Entretanto, quando voc faz o commit de modificaes, essas no ficaro visveis para
Sally quando ela fizer Update, porque a cpia de trabalho dela aponta para /calc/trunk. (Leia
Atravessando Ramos logo frente neste captulo: o comando svn switch uma forma alternativa
de se criar uma cpia de trabalho de um ramo.)
Vamos imaginar que tenha se passado uma semana, e o seguinte commit realizado:
Exitem agora duas linhas independentes de desenvolvimento, mostrando em Figura 4.4, Ramificao
do histrico de um arquivo, afetando integer.c.
76
Fundir e Ramificar
As coisas ficam interessantes quando voc olha o histrico das alteraes feitas na sua cpia de
integer.c:
$ pwd
/home/user/my-calc-branch
------------------------------------------------------------------------
r341 | user | 2002-11-03 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
A /calc/branches/my-calc-branch (from /calc/trunk:340)
------------------------------------------------------------------------
r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines
Changed paths:
M /calc/trunk/integer.c
------------------------------------------------------------------------
r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines
Changed paths:
M /calc/trunk/integer.c
------------------------------------------------------------------------
Note que o Subversion est traando o histrico do seu ramo de integer.c pelo tempo, at o momento
em que ele foi copiado. Isso mostra o momento em que o ramo foi criado como um evento no histrico,
j que integer.c foi copiado implicitamente quando /calc/trunk/ foi copiado. Agora veja o que
ocorre quando Sally executa o mesmo comando em sua cpia do arquivo:
77
Fundir e Ramificar
$ pwd
/home/sally/calc
------------------------------------------------------------------------
r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines
Changed paths:
M /calc/trunk/integer.c
------------------------------------------------------------------------
r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines
Changed paths:
M /calc/trunk/integer.c
------------------------------------------------------------------------
Sally v suas prprias modificaes na reviso 344, e no as modificaes que voc fez na reviso
343. At onde o Subversion sabe, esses dois commits afetaram arquivos diferentes em locais distintos
no repositrio. Entretanto o Subversion mostra que os dois arquivos tm um histrico em comum. Antes
de ser feita a cpia/ramo na reviso 341, eles eram o mesmo arquivo. por isso que voc e Sally
podem ver as alteraes feitas nas revises 303 e 98.
Para projetos que tenham um grande numero de colaboradores, comum que cada um tenha sua cpia
de trabalho do tronco. Sempre que alguem precise fazer uma longa modificao que possa corromper
o tronco, o procedimento padro criar um ramo privado e fazer os commits neste ramo at que todo
o trabalho esteja concluido.
Ento, a boa notcia que voc no est interferindo no trabalho de Sally, e vice-versa. A m notcia,
que muito fcil se distanciar do projeto. Lembre-se que um dos problemas com a estratgia do se
isolar que quando voc terminar de trabalhar no seu ramo, pode ser bem perto de impossvel de
fundir suas modificaes novamente com o tronco do projeto sem um grande numero de conflitos.
78
Fundir e Ramificar
Ao invs disso, voc e Sally devem continuamente compartilhar as modificaes ao longo do seu
trabalho. Depende de voc para decidir quais modificaes devem ser compartilhadas; O Subversion
lhe da a capacidade para selecionar o que copiar entre os ramos. E quando voc terminar de trabalhar
no seu ramo, todas as modificaes realizadas no seu ramo podem ser copiadas novamente para o
tronco.
hora de usar o comando svn merge. Esse comando um primo muito prximo do comando svn diff
(que voc viu em Captulo 2, Uso Bsico). Os dois comando comparam dois objetos no repositrio e
mostram as diferenas. Por exemplo, voc pode pedir com o comando svn diff para ver com exatido
as mudanas feitas por Sally na reviso 344:
Index: integer.c
===================================================================
--- integer.c (revision 343)
+++ integer.c (revision 344)
@@ -147,7 +147,7 @@
case 6: sprintf(info->operating_system, "HPFS (OS/2 or NT)"); break;
case 7: sprintf(info->operating_system, "Macintosh"); break;
case 8: sprintf(info->operating_system, "Z-System"); break;
- case 9: sprintf(info->operating_system, "CPM"); break;
+ case 9: sprintf(info->operating_system, "CP/M"); break;
case 10: sprintf(info->operating_system, "TOPS-20"); break;
case 11: sprintf(info->operating_system, "NTFS (Windows NT)"); break;
case 12: sprintf(info->operating_system, "QDOS"); break;
@@ -164,7 +164,7 @@
low = (unsigned short) read_byte(gzfile); /* read LSB */
high = (unsigned short) read_byte(gzfile); /* read MSB */
high = high << 8; /* interpret MSB correctly */
- total = low + high; /* add them togethe for correct total */
+ total = low + high; /* add them together for correct total */
@@ -249,7 +249,7 @@
printf("I believe start of compressed data is %u\n", info->data_offset);
#endif
79
Fundir e Ramificar
O comando svn merge quase que o mesmo. Ao invs de imprimir as diferenas no terminal, ele as
aplica diretamente cpia de trabalho classificando como local modifications:
$ svn status
M integer.c
A sada do comando svn merge mostra a sua cpia de integer.c sofreu uma correo. Agora ele
contm as modificaes feitas por Sally essas modificaes foram copiadas do tronco do repositrio
para a cpia de trabalho do seu ramo privado, e agora existe como uma modificao local. A esta altura,
depende de voc revisar essa modificao local e ter certeza de funciona.
Em outra simulao, possvel que as coisas no tenham ocorrido to bem assim, e o arquivo
integer.c tenha entrado em estado de conflito. Pode ser que voc precise resolver o conflito usando
procedimentos padro (veja Captulo 2, Uso Bsico), ou se voc decidir que fazer a fuso dos arquivos
tenha sido uma m idia, desista e rode o comando svn revert para retirar as modificaes locais.
Partindo do pressuposto que voc revisou as modificaes do processo de fuso , ento voc pode
fazer o svn commit como de costume. A este ponto, a mudana foi fusionada ao seu ramo no
repositrio. Em tecnologias de controle de verso, esse ato de copiar mudanas entre ramos recebe
o nome de portar mudanas.
Quando voc fizer o commit das modificaes locais, no esquea de colocar na mensagem de log
que voc est portando uma modificao especifica de um ramo para outro.Por exemplo:
Como voc ver nas prximas sees, essa uma boa pratica importantssima a ser seguida.
80
Fundir e Ramificar
Essa questo pode estar em sua mente, especialmente se voc for um usurio de Unix: porque
usar o comando svn merge? Porque no simplesmente usar o comando do sistema patch para
realizar esta tarefa? Por exemplo:
Neste caso em particular, sim, realmente no h diferena. Mas o comando svn merge tem
habilidades especiais que superam o comando patch. O formato do arquivo usado pelo patch
bem limitado; apenas capaz de mexer o contedo dos arquivos. No h forma de representar
mudanas em arvores, como o criar, remover e renomear arquivos e diretrios. To pouco pode
o comando patch ver mudanas de propriedades. Se nas modificaes de Sally, um diretrio
tivesse sido criado, a sada do comando svn diff no iria fazer meno disso. svn diff somente
mostra forma limitada do patch, ento existem coisa que ele simplesmente no ir mostrar.
O comando svn merge, por sua vez, pode mostrar modificaes em estrutura de rvores e
propriedades aplicando estes diretamente em sua cpia de trabalho.
Um aviso: ainda que o comando svn diff e o svn merge tem conceitos similares, eles apresentam
sintaxe diferente em vrios casos. Leia sobre isso em Captulo 9, Referncia Completa do Subversion
para mais detalhes, ou pea ajuda ao comando svn help. Por exemplo, o comando svn merge precisa
de uma cpia de trabalho com destino, isto , um local onde aplicar as modificaes. Se um destino
no for especificado, ele assume que voc est tentando uma dessas operaes:
2. Voc quer fundir as modificaes de um arquivo em especfico, em outro arquivo de mesmo nome
que existe no seu diretrio atual de trabalho.
Se voc esta fundindo um diretrio e no especificou um destino, svn merge assume o primeiro caso
acima e tenta aplicar as modificaes no seu diretrio atual. Se voc est fundindo um arquivo, e este
arquivo (ou arquivo de mesmo nome) existe no diretrio atual, o svn merge assume o segundo caso,
e tenta aplicar as modificaes no arquivo local de mesmo nome.
Se voc quer que as modificaes seja aplicadas em outro local, voc vai precisar avisar. Por exemplo,
se voc est no diretrio pai de sua cpia de trabalho, voc vai precisar especificar o diretrio de destino
a receber as modificaes:
81
Fundir e Ramificar
O principal motivo de confuso o nome do comando. O termo fundir de alguma forma denota que
se junta ramos, ou que existe uma mistura misteriosa de cdigo ocorrendo. Este no o caso. O nome
mais apropriado para o comando deveria ter sido svn diff-and-apply , porque isso o que acontece:
duas rvores de repositrio so comparadas, e a diferena aplicada a uma cpia de trabalho.
3. Uma cpia de trabalho para receber as diferenas como modificao local (geralmente chamada
de destino da fuso).
Uma vez especificados estes trs argumentos, as duas rvores so comparadas, e o resultado das
diferenas so aplicadas sobre a cpia de trabalho de destino, como modificaes locais. Uma vez
executado o comando, o resultado no diferente do que se voc tivesse editado manualmente os
arquivos, ou rodados vrios comandos svn add ou svn delete. Se voc gostar do resultado voc pode
fazer o commit dele. Se voc no gostar do resultado, voc pode simplesmente reverter as mudanas
com o comando svn revert.
A sintaxe do comando svn merge lhe permite especificar os trs argumentos necessrios de forma
flexvel. Veja aqui alguns exemplos:
A primeira sintaxe usa explicitamente os trs argumentos, nomeando cada rvore na forma URL@REV
e nomeando a cpia de trabalho de destino. A segunda sintaxe pode ser usada como um atalho em
situaes onde voc esteja comparando duas revises distintas de uma mesma URL. A ultima sintaxe
mostra como o argumento da cpia de trabalho de destino opcional; se omitido, assume como padro
o diretrio atual.
Infelizmente, o Subversion no esse sistema; ele ainda no grava informaes sobre as fuses
2
realizadas. Quando voc faz o commit das modificaes locais, o repositrio no faz a menor idia
se as alteraes vieram de um comando svn merge, ou de uma edio manual no arquivo.
2
Entretanto, neste exato momento, essa funcionalidade est sendo preparada!
82
Fundir e Ramificar
O que isso significa para voc, o usurio? Significa que at que o Subversion tenha essa funcionalidade,
voc ter que rastrear as informaes de Fuso pessoalmente. A melhor maneira de fazer isso com
as mensagens de log do commit. Como mostrado nos exemplos anteriores, recomendvel que sua
mensagem de log informe especificamente o nmero da reviso (ou nmeros das revises) que sero
fundidas ao ramo. Depois, voc pode rodar o comando svn log para verificar quais modificaes o
seu ramo j recebeu. Isso vai lhe ajudar a construir um prximo comando svn merge que no ser
redundante com as modificaes j aplicadas.
Visualizando Fuses
Primeiro, lembre-se de fundir seus arquivos para a cpia de trabalho quando esta no tiver alteraes
locais e tenha sido atualizada recentemente. Se a sua cpia de trabalho no estiver limpa, voc pode
ter alguns problemas.
Assumindo que a sua cpia de trabalho est no ponto, fazer a fuso no ser uma operao de alto
risco. Se voc no fizer a primeira fuso de forma correta, rode o comando svn revert nas modificaes
e tente novamente.
Se voc fez a fuso para uma cpia de trabalho que j possui modificaes locais, a mudanas
aplicadas pela fuso sero misturadas as pr existentes, e rodar o comando svn revert no mais
uma opo. Pode ser impossvel de separar os dois grupos de modificaes.
Em casos como este, as pessoas se tranquilizam em poder prever e examinar as fuses antes de
ocorrerem. Uma maneira simples de fazer isso rodar o comando svn diff com os mesmos argumentos
que voc quer passar para o comando svn merge, como mostramos no primeiro exemplo de fuso.
Outro mtodo de prever os impactos passar a opo --dry-run para o comando de fuso:
$ svn status
# nothing printed, working copy is still unchanged.
A opo --dry-run no aplica qualquer mudana para a copia de trabalho. Essa opo apenas exibe
os cdigos que seriam escritos em uma situao real de fuso. til poder ter uma previso de auto
nvel da potencial fuso, para aqueles momentos em que o comando svn diff d detalhes at demais.
Fundir conflitos
Assim como no comando svn update, o comando svn merge aplica modificaes sua cpia de
trabalho. E portanto tambm capaz de criar conflitos. Entretanto, os conflitos criados pelo comando
svn merge so um tanto diferentes, e essa seo explica essas diferenas.
Para comear, assuma que sua cpia de trabalho no teve modificaes locais. Quando voc faz a
atualizao com o comando svn update para um reviso especfica, as modificaes enviadas pelo
servidor vo ser sempre aplicadas sua cpia de trabalho sem erros. O servidor produz o delta a
partir da comparao de duas rvores: uma imagem virtual de sua cpia de trabalho, e a rvore da
reviso na qual est interessado. Como o lado esquerdo da comparao exatamente igual ao que
voc j possui, garantido que o delta converter corretamente sua cpia de trabalho, para a reviso
escolhida no lado direito da comprao.
Entretanto, o comando svn merge no possui essa garantia e pode ser bem mais catico: o usurio
pode pedir ao servidor para comparar qualquer rvore, at mesmo rvores que no tenham relao
com a sua cpia de trabalho! Isso significa que existem uma grande margem para erro humano. Usurio
vo acabar por compara duas rvores erradas, criando um delta que no se aplica sem conflitos. O
83
Fundir e Ramificar
comando svn merge vai fazer o melhor possvel para aplicar o delta o mximo possvel, mas em
algumas partes isso pode ser impossvel. Assim como no comando Unix patch que as vezes reclama
sobre failed hunks, o svn merge vai reclamar sobre alvos perdidos:
O exemplo anterior pode ser um caso no qual o arquivo baz.c existe nas duas imagens dos ramos que
esto sendo comparados, e o delta resultante quer modificar o contedo do arquivo, mas o arquivo no
existe na cpia de trabalho. Independente do caso, a mensagem de skipped significa que o usurio
est, muito provavelmente, comparando rvores incorretas; esse o sinal clssico de erro do usurio.
Quando isso acontece, fcil reverter recursivamente as modificaes criadas pela fuso (svn revert --
recursive), delete qualquer arquivo no versionado deixado pelo revert, e rode novamente o comando
svn merge usando outros argumentos.
Note tambm que o exemplo anterior mostra um conflito no arquivo glorb.h. Ns j mostramos que
a cpia local no possui modificaes:como um conflito pde acontecer? Novamente, uma vez que o
usurio pode usar o comando svn merge para definir e aplicar qualquer delta antigo para a cpia de
trabalho, o delta pode conter alteraes que no se aplicam sem erros ao arquivo local, mesmo que
o arquivo no tenha modificaes locais.
Outra pequena diferena entre os comandos svn update e svn merge o nome dos arquivos
de texto criados quando ocorre um conflito. Em Resolvendo Conflitos (Combinando Alteraes de
Outros), vimos que um update produz arquivos nomeados de filename.mine, filename.rOLDREV,
e filename.rNEWREV. Entretanto, quando o comando svn merge produz um conflito, ele cria trs
arquivos nomeados como filename.working, filename.left, e filename.right. Neste caso,
os termos left e right esto indicando de que lado da comparao vieram os arquivos. Em todo caso,
esses nomes vo ajuda-lo a diferenciar conflitos que so resultado de um update ou de uma fuso.
Por exemplo, suponha que voc submeta a reviso 100, a qual inclui uma mudana num arquivo foo.c.
Ento, foo.c@99 o ancestral de ancestral de foo.c@100. Por outro lado, suponha que voc
submeta a excluso do arquivo foo.c na reviso 101, e ento adicione um novo arquivo com o mesmo
nome na reviso 102. Neste caso, foo.c@99 e foo.c@102 podem parecer estar relacionados (afinal,
eles tm o mesmo caminho), mas de fato eles so objetos completamente diferentes no repositrio.
Eles no compartilham histrico ou ancestralidade.
A razo para abordar isto destacar uma importante diferena entre svn diff e svn merge. O primeiro
comando ignora a ancestralidade, enquanto que este ltimo bastante sensvel a ela. Por exemplo,
se voc solicitar que o svn diff compare as revises 99 e 102 do arquivo foo.c, voc deveria ver
diferenas em termos de linhas do arquivo em cada reviso; o comando diff cego ao comparar dois
caminhos. Mas se voc solicitar ao svn merge para comparar os mesmos dois objetos, o subcomando
deve perceber que estes dois objetos no esto relacionados e primeiro tentar excluir o arquivo antigo,
e ento adicionar o arquivo novo; a sada deveria indicar uma excluso seguida por uma adio:
D foo.c
84
Fundir e Ramificar
A foo.c
A maioria das fuses envolve comparao de rvores ancestralmente relacionadas umas s outras, e
assim o svn merge por padro possui este comportamento. Ocasionalmente, no entanto, voc pode
querer que o comando merge compare duas rvores no relacionadas. Por exemplo, voc pode ter
importado duas rvores de cdigo-fonte representando distribuies de diferentes fornecedores de um
projeto de software (veja Ramos de fornecedores). Se voc solicitar que o svn merge compare as
duas rvores, voc deveria ver a excluso da primeira rvore inteira, seguida da adio da segunda
rvore inteira! Nessas situaes, voc vai querer que o svn merge faa uma comparao baseada
apenas em caminhos, ignorando quaisquer relaes entre arquivos e diretrios. Adicione a opo --
ignore-ancestry a seu comando merge, e ele se comportar como o svn diff. (E reversalmente, a
opo --notice-ancestry far com que o svn diff se comporte como o comando merge.)
Fuses e Movimentaes
Um desejo comum refatorar cdigo-fonte, especialmente em projetos de software na linguagem Java.
Arquivos e diretrios so mexidos e renomeados, possivelmente provocando transtornos a todos que
estiverem trabalhando no projeto. Parece um caso perfeito para criar um ramo, no? Apenas crie um
ramo, modifique as coisas inteiramente, e ento mescle o ramo de volta ao tronco principal, certo?
Infelizmente, no momento este cenrio no funciona to bem, sendo algo considerado como um dos
pontos fracos do Subversion. O problema que o comando update do Subversion no to robusto
quanto poderia ser, especialmente ao lidar com operaes de cpia e movimentaes.
Quando voc usa o svn copy para duplicar um arquivo, o repositrio se lembra de onde o novo arquivo
veio, mas falha ao transmitir essa informao para o cliente que est executando um svn update ou
um svn merge. Ao invs de dizer para o cliente, Copie este arquivo que voc j possui para este novo
local, ele envia informao acerca de um arquivo completamente novo. Isto pode levar a problemas,
especialmente pelo fato de que a mesma coisa acontece com arquivos renomeados. Um fato pouco
conhecido pouco conhecido sobre o Subversion que ainda lhe falta um recurso para renomeao
efetivao comando svn move nada mais que uma combinao de svn copy e svn delete.
Por exemplo, suponha que ao trabalhar em seu ramo particular, voc renomeie integer.c para
whole.c. Efetivamente voc criou um novo arquivo em seu ramo que uma cpia do arquivo original
e excluiu o arquivo original. Enquanto isso, de volta ao trunk, Sally submeteu algumas melhorias em
integer.c. Agora voc decide mesclar seu ramo ao tronco:
$ cd calc/trunk
primeira vista, isto no parece to ruim, mas provavelmente tambm no era o que voc ou Sally
esperavam. A operao de mesclagem excluiu a ltima verso do arquivo integer.c (aquela que
continha as ltimas alteraes de Sally), e adicionou cegamente seu novo arquivo whole.cque
uma duplicata da verso mais antiga de integer.c. O efeito em cascata que mesclar sua
renomeao no ramo removeu as modificaes recentes de Sally para a ltima reviso!
Mas isto no uma perda de dados real; as modificaes de Sally ainda esto no histrico do
repositrio, mas o que de fato aconteceu pode no ser bvio de imediato. A moral dessa histria que
at que o Subversion evolua, tenha cuidado ao mesclar cpias e renomeaes a partir de um ramo
para outro.
85
Fundir e Ramificar
Ento como usamos o svn merge neste cenrio? Lembre-se de que este comando compara duas
rvores, e aplica as diferenas em uma cpia de trabalho. Ento para receber as modificaes, voc
precisa ter uma cpia de trabalho do tronco. Vamos assumir que voc ainda possua uma cpia original
(completamente atualizada), ou que voc recentemente tenha obtido uma nova cpia de trabalho de
/calc/trunk.
Mas quais duas rvores deveriam ser comparadas? primeira vista a resposta pode parecer bvia:
apenas compare a rvore mais recente do tronco com sua rvore mais recente de seu ramo. Mas
cuidadoesta suposio est errada, e isso costuma confundir muito os novos usurios! Como o svn
merge opera como o svn diff, comparar as ltimas verses das rvores do tronco e do ramo no
descreve apenas o conjunto de modificaes que voc fez em seu ramo. Tal comparao exibe muito
mais mudanas: ele no apenas exibe o efeito das modificaes de seu ramo, mas tambm todas as
alteraes de removao que nunca aconteceram em seu ramo.
Para expressar apenas as modificaes que aconteceram em seu ramo, voc precisa comparar o
estado inicial de seu ramo com seu estado final. Usando um svn log em seu ramo, voc pode ver que
seu ramo foi criado na reviso 341. E o estado final de seu ramo simplesmente uma dada forma de
uso da reviso HEAD. Isso significa que voc deve comparar as revises 341 e HEAD do seu diretrio
branch, e aplicar estas diferenas na cpia de trabalho de trunk.
Uma tima maneira de encontrar a reviso na qual um ramo foi criado (a base do ramo)
usar a opo --stop-on-copy do comando svn log. O subcomando log normalmente
ir mostrar cada modificao feita no ramo, incluindo o rastreamento de volta alm da
operao de cpia que criou o ramo. Ento, normalmente, voc ir ver o histrico do tronco
tambm. A opo --stop-on-copy ir parar a sada do log assim que o svn log detecte
que seu alvo foi copiado ou renomeado.
Como esperado, a ltima reviso exibida por este comando a reviso na qual o ramo
my-calc-branch foi criado por cpia.
$ cd calc/trunk
$ svn update
At revision 405.
86
Fundir e Ramificar
$ svn status
M integer.c
M button.c
M Makefile
Novamente, perceba que a mensagem de log do commit menciona bem especificamente o intervalo
de modificaes que foram mescladas para o tronco. Sempre se lembre de fazer isso, pois uma
informao crtica de que voc ir precisar depois.
Por exemplo, suponha que voc decida continuar trabalhando em seu ramo por mais uma semana,
para concluir uma melhoria em seu recurso original ou uma correo de bug. A reviso HEAD do
repositrio agora a 480, e voc est pronto para fazer outra mesclagem de seu ramo particular com o
tronco principal. Mas como j discutido em Melhores prticas sobre Fuso, voc no quer mesclar as
modificaes que voc j mesclou anteriormente; o que voc quer mesclar todas as coisas novas
em seu ramo desde a ltima mesclagem que voc fez. O truque conferir exatamente quais so as
coisas novas.
O primeiro passo executar svn log no tronco, e procurar por uma mensagem de log da ltima vez
que voc mesclou um ramo:
$ cd calc/trunk
$ svn log
------------------------------------------------------------------------
r406 | user | 2004-02-08 11:17:26 -0600 (Sun, 08 Feb 2004) | 1 line
Aha! Como todas as modificaes no ramo que aconteceram entre as revises 341 e 408 j foram
previamente mescladas para o tronco gerando a reviso 406, voc agora sabe que deve mesclar
apenas as alteraes feitas depois dissocomparando as revises HEAD.
$ cd calc/trunk
$ svn update
At revision 480.
# Percebemos que atualmente HEAD est em 480, ento usamos isso para fazer a mesclagem:
87
Fundir e Ramificar
U Makefile
Agora o tronco contm a segunda leva completa de modificaes feitas no ramo. Neste ponto, voc
pode tanto excluir o seu ramo (falaremos mais sobre isso posteriormente), ou continuar trabalhando
em seu ramo e repetir este procedimento para mesclagens subsequentes.
Desfazendo Alteraes
Outro uso comum do svn merge para desfazer uma modificao que j foi submetida ao repositrio.
Suponha que voc esteja trabalhando alegremente na cpia de trabalho de /calc/trunk, e voc
descobre que a modificao que havia sido feita na reviso 303, que modificou o arquivo integer.c,
est completamente errada. E que ela nunca deveria ter acontecido, nem tampouco submetida. Voc
pode usar o svn merge para desfazer a modificao em cpia de trabalho, e ento submeter a
modificao local para o repositrio. Tudo o que voc precisa fazer especificar uma diferena reversa.
(Voc pode fazer isto especificando --revision 303:302, ou tambm o equivalente --change
-303.)
$ svn status
M integer.c
$ svn diff
Uma maneira de pensar o repositrio como um grupo especfico de modificaes (alguns sistemas
de controle de verso chamam a isto de conjuntos de mudanas ou changesets). Usando a opo
-r, voc pode solicitar que o svn merge aplique um conjunto de mudanas, ou um intervalo inteiro
de conjuntos de mudanas, sua cpia de trabalho. Em nosso caso em questo, como queremos
desfazer uma mudana, estamos solicitando que o svn merge aplique o conjunto de mudanas #303
retrospectivamente de volta nossa cpia de trabalho.
88
Fundir e Ramificar
Cada um parece ter uma definio ligeiramente diferente do que seja um conjunto de mudanas,
ou ao menos diferentes expectativas sobre o que significa um sistema de controle de verso
possuir recursos para lidar com conjuntos de mudanas. Para nosso propsito, digamos que
um conjunto de mudana seja apenas uma poro de alteraes associadas a um nome nico.
As alteraes podem incluir modificaes textuais ao contedo de arquivos, mudanas em uma
estrutura de rvore, ou ajustes em metadados. Falando de uma forma mais geral, um conjunto
de mudanas apenas um patch com um nome a partir do qual voc pode se referir.
Tenha em mente que voltar uma mudana como neste caso uma operao de svn merge como
outra qualquer, ento voc deveria usar svn status e svn diff para confirmar que seu trabalho esteja
no estado em que voc quer que esteja, e ento usar svn commit para enviar a verso final para o
repositrio. Depois de submetido, este conjunto de mudanas em particular no estar mais refletido
na reviso HEAD.
Novamente, voc pode estar pensando: bem, isto no desfaz exatamente a submisso, no ? A
modificao ainda existe na reviso 303. Se algum obtiver uma verso do projeto calc entre as
revises 303 e 349, elas ainda contero a tal modificao incorreta, certo?
Sim, isto verdade. Quando ns falamos sobre remover uma modificao, estvamos realmente
falando sobre remov-la da reviso HEAD. A modificao original ainda existir no histrico do
repositrio. Na maioria das situaes, isto o suficiente. Afinal, a maioria das pessoas esto apenas
interessadas em rastrear a reviso HEAD de um projeto. Porm, h alguns casos especiais onde voc
realmente pode querer destruir todas as evidncias da submisso errnea. (Talvez algum submetido
acidentalmente um documento confidencial.) Isto no to fcil de se fazer, pois o Subversion foi
desenvolvido deliberadamente para nunca perder informao. As revises so rvores imutveis as
quais so construdas umas a partir das outras. Remover uma reviso do histrico deveria causar um
efeito domin, criando o caos em todas as revises subsequentes e possivelmente invalidando todas
3
as cpias de trabalho.
O primeiro passo definir exatamente qual tem voc est tentando ressucitar. Aqui h uma metfora
til: voc pode pensar como se cada objeto no repositrio existisse em uma espcie de sistema bi-
dimensional. A primeira coordenada uma determinada rvore de reviso, e a segunda coordenada
3
Entretanto, o projeto Subversion tem planos de, algum dia, implementar um comando que possa cumprir a tarefa de excluir
permanentemente alguma informao. Enquanto isso, veja svndumpfilter para uma possvel soluo.
89
Fundir e Ramificar
o caminho dentro daquela rvore. Assim cada verso de seu arquivo ou diretrio pode ser definida
por um dado par de coordenadas. (Lembre-se da sintaxe de revises marcadorasfoo.c@224
apresentada em Revises Marcadoras e Revises Operativas.)
Primeiramente, voc pode precisar usar um svn log para descobrir o par de coordenadas exato que
voc quer ressucitar. Uma boa estratgia executar svn log --verbose em um diretrio onde seu item
excludo costumava estar. A opo --verbose (-v) exibe uma lista de todos os itens que mudaram
em cada reviso; tudo que voc precisa fazer encontrar a reviso na qual voc excluir o arquivo ou
diretrio. Voc pode fazer isto visualmente, ou usando outra ferramenta para examinar a sada dos
registros de log (usando grep, ou talvez com uma busca incremental em um editor).
$ cd parent-dir
$ svn log -v
------------------------------------------------------------------------
r808 | joe | 2003-12-26 14:29:40 -0600 (Fri, 26 Dec 2003) | 3 lines
Changed paths:
D /calc/trunk/real.c
M /calc/trunk/integer.c
No exemplo, estamos assumindo que voc est procurando um arquivo excludo chamado real.c.
Olhando os logs de um diretrio-pai, voc percebeu que este arquivo foi excludo na reviso 808.
Portanto, a ltima verso do arquivo existia na reviso imediatamente anterior a essa. Concluso: voc
quer ressucitar o caminho /calc/trunk/real.c a partir da reviso 807.
Esta foi a parte difcila pesquisa. Agora que voc sabe o que voc quer restaurar, voc tem duas
diferentes escolhas.
Uma opo usar svn merge para aplicar a reviso 808 ao contrrio. (Ns j falamos sobre como
desfazer modificaes, veja Desfazendo Alteraes.) Isto teria o efeito de re-adicionar o arquivo
real.c como uma modificao local. O arquivo deveria ser agendado para adio, e aps ser
submetido, o arquivo deve estar novamente presente na reviso HEAD.
Uma segunda, e mais precisa estratgia envolve no usar o svn merge, mas o comando svn copy em
seu lugar. Simplesmente copie a reviso exata e o caminho como par de coordenadas do repositrio
para sua cpia de trabalho:
$ svn status
A + real.c
90
Fundir e Ramificar
O sinal de mais na sada do comando status indica que o item no est meramente agendado para
adio, mas agendado para adio com histrico. O Subversion lembra de onde ele foi copiado. No
futuro, executar svn log neste arquivo ir percorrer at o arquivo ressucitado e atravs do histrico
que ele tinha antes da reviso 807. Em outras palavras, este novo real.c no realmente novo;
um descendente direto do arquivo original que fora excludo.
Apesar de nosso exemplo nos mostrar uma ressurreio de arquivo, veja que estas mesmas tcnicas
funcionam muito bem tambm para ressucitar diretrios excludos.
aqui que o controle de verso pode ajudar. O procedimento tpico se parece com isto:
Desenvolvedores submetem todo o novo cdigo produzido para o tronco. As modificaes do dia-a-
dia so submetidas para /trunk: novos recursos, correes de bugs, e por a adiante.
O tronco copiado para um ramo de release. Quando a equipe achar que o software est pronto
para o lanamento de um novo release (digamos, uma verso 1.0), ento o /trunk pode ser copiado
para /branches/1.0.
As equipes continuam a trabalhar em paralelo. Uma equipe comea uma rigorosa etapa de testes no
ramo do release, enquanto outra equipe continua prosseguindo com o trabalho (digamos, para uma
futura verso 2.0) em /trunk. Se bugs forem descobertos em algum local, correes so portadas
adequadamente conforme o necessrio. Em algum ponto, porm, mesmo esse processo pra. O
ramo ento congelado para testes finais imediatamente antes do lanamento do release.
O ramo mantido ao longo do tempo. Como o trabalho continua em /trunk para uma verso 2.0,
as correes de bugs continuam a ser portadas de /trunk para /branches/1.0. Quando uma
suficiente quantidade de correes estiverem acumuladas, os gestores do software pode decidir
fazer uma verso 1.0.1: /branches/1.0 copiado para /tags/1.0.1, e o rtulo empacotado
e distribudo.
Este processo inteiro se repete enquanto o software amadurece: quando a verso 2.0 estiver pronta,
um novo ramo para o release 2.0 criado, testado, rotulado e eventualmente distribudo. Depois de
alguns anos, o repositrio acaba com uma poro de ramos distribudos em modo de manuteno, e
um conjunto de tags representando as ltimas verses entregues do software.
91
Fundir e Ramificar
Muitos projetos utilizam uma abordagem meio-termo. So projetos que insistem que o cdigo presente
em /trunk compile e passe em testes de regresso a cada momento. Um ramo de novos recursos
s necessrio quando uma modificao demanda um grande nmero de submisses que possam
desestabilizar o cdigo. Uma regra de ouro se perguntar: se o desenvolvedor trabalhou vrios dias
isoladamente e ento submeteu uma grande alterao toda de uma s vez (de forma que /trunk
nunca esteve desestabilizada), tal modificao seria muito grande para uma reviso? Se a resposta a
esta pergunta for sim, ento a modificao deveria ser desenvolvida em um ramo de novos recursos.
Se o desenvolvedor submeter modificaes incrementais ao ramo, elas podem ser facilmente revistas
por seus colegas.
Finalmente, h a questo sobre o quo sincronizado se deve manter um ramo de novos recursos
com o tronco conforme o trabalho no cdigo for avanando. Como j mencionado anteriormente, h
um grande risco de se permanecer trabalhando em um ramo por semanas ou meses; modificaes no
tronco podem continuar a acontecer, at o ponto em que as duas linhas de desenvolvimento possam
diferir tanto a ponto de que realizar a fuso do ramo de volta para o tronco possa se tornar um grande
pesadelo.
A melhor maneira de evitar essa situao regularmente mesclar as alteraes do tronco para o ramo
em desenvolvimento. Defina uma poltica: uma vez por semana, realize a fuso das alteraes da ltima
semana feitas no tronco para seu ramo. Tome cuidado ao fazer isto; ser necessrio controle manual
nas fuses visando evitar o problema de se realizar repetidas fuses (como descrito em Rastreando
Fuses manualmente). Voc precisar escrever cuidadosamente suas mensagens de log detalhando
quais intervalos de reviso j foram mesclados (como demonstrado em Mesclando um Ramo Inteiro
para Outro). Pode parecer assustador, mas atualmente algo muito fcil de se fazer.
Em algum ponto, voc estar pronto para fazer a fuso de seu ramo sincronizado de recursos de
volta para o tronco. Para fazer isto, comece fazendo uma ltima fuso das ltimas alteraes presentes
no tronco para seu ramo. Ao terminar, as ltimas verses do ramo e do tronco sero absolutamente
idnticas, exceto pelas suas prprias alteraes. Assim, particularmente neste caso, voc realizar a
fuso comparando seu ramo com o tronco:
$ cd trunk-working-copy
$ svn update
At revision 1910.
92
Fundir e Ramificar
U real.c
U integer.c
A newdirectory
A newdirectory/newfile
Comparando a reviso HEAD do tronco com a reviso revision HEAD do ramo, voc est definindo um
delta que descreve apenas as alteraes que voc fez no ramo; ambas as linhas de desenvolvimento
j possuem todas as alteraes do tronco.
Outra forma de pensar sobre este padro que sua sincronizao semanal do tronco para o ramo
anloga execuo de um svn update na cpia de trabalho, ao passo que o passo da fuso final
anlogo a executar um svn commit a partir de sua cpia de trabalho. E no fim das contas, o que de fato
uma cpia de trabalho seno um rasteiro ramo particular? um ramo que s capaz de armazenar
s uma modificao por vez.
Atravessando Ramos
O comando svn switch transforma uma cpia de trabalho existente para refletir um ramo diferente.
Enquanto este comando no estritamente necessrio para trabalhar com ramos, ele oferece um
bom atalho. Em nosso exemplo anterior, depois de criar seu ramo pessoal, voc obteve uma cpia de
trabalho atualizada do novo diretrio do repositrio. Em vez disso, voc pode simplesmente pedir ao
Subversion que mude sua cpia de trabalho de /calc/trunk para espelhar o local do novo ramo:
$ cd calc
Depois da comutao para o ramo, sua cpia de trabalho no diferente daquilo que voc obteria
fazendo uma cpia atualizada do diretrio. E ainda usualmente mais eficiente usar este comando,
porque muitas vezes os ramos diferem somente em poucos detalhes. O servidor envia somente o
conjunto mnimo de mudanas necessrias para fazer sua cpia de trabalho refletir o diretrio do ramo.
O comando svn switch tambm possui uma opo --revision (-r), assim voc no precisa sempre
mover sua cpia de trabalho para a reviso HEAD do ramo.
Certamente, a maioria dos projetos so mais complicados que nosso exemplo calc, contendo mltiplos
subdiretrios. Os usurios do Subversion muitas vezes seguem um algoritmo especfico ao usar ramos:
Em outras palavras, se um usurio sabe que o trabalho no ramo s deve acontecer sobre um
subdiretrio especfico, eles usam svn switch para mover somente este subdiretrio para o ramo.
(Ou algumas vezes os usurios comutaro apenas um nico arquivo de trabalho para o ramo!) Dessa
forma, eles podem continuar a receber normalmente as atualizaes do trunk para a maior parte de
sua cpia de trabalho, mas as pores comutadas ficaro imunes (a no ser que algum submeta uma
93
Fundir e Ramificar
mudana em seu ramo). Esta funcionalidade adiciona uma completa nova dimenso ao conceito de
uma cpia de trabalho mistapodemos ter no apenas cpias de trabalho que possuem uma mistura
de revises de trabalho, mas tambm uma mistura de locais de repositrio.
Note que enquanto est tudo certo para sua cpia de trabalho refletir uma mistura de locais do
repositrio, estes locais devem estar todos dentro do mesmo repositrio. Os repositrios do Subversion
4
ainda no so capazes de comunicarem entre si; esta uma funcionalidade planejada para o futuro.
Comutaes e Atualizaes
Voc reparou que a sada dos comandos svn switch e svn update possuem a mesma aparncia?
O comando switch na verdade um super-comando do comando update.
Quando voc executa svn update, voc est pedindo ao repositrio para comparar duas rvores.
O repositrio assim faz, e ento envia uma descrio das diferenas de volta para o cliente. A
nica diferena entre svn switch e svn update que o comando update sempre compara dois
caminhos idnticos.
Isto , se sua cpia de trabalho um espelho de /calc/trunk, ento svn update comparar
automaticamente sua cpia de trabalho de /calc/trunk com /calc/trunk na reviso HEAD.
Se voc est comutando sua cpia de trabalho para um ramo, ento svn switch comparar sua
cpia de trabalho de /calc/trunk com algum outro diretrio de ramo na reviso HEAD.
Em outras palavras, uma atualizao move sua cpia de trabalho atravs do tempo. Uma
comutao move sua cpia de trabalho atravs do tempo e do espao.
Porque svn switch essencialmente uma variante de svn update, ele compartilha os mesmos
comportamentos; qualquer modificao local em sua cpia de trabalho preservada quando novos
dados chegam do repositrio. Isso lhe permite executar todos os tipos de truques engenhosos.
Por exemplo, suponha que voc tem uma cpia de trabalho de /calc/trunk e realizou um certo
nmero de mudanas nele. Ento voc rapidamente constata que voc pretendia fazer as mudanas
em um ramo. No tem problema! Quando voc executa svn switch para um ramo de sua cpia de
trabalho, as mudanas locais permanecero. Voc pode ento testar e submeter elas para o ramo.
Rtulos
Outro conceito comum do controle de verso ramo. Um ramo apenas uma foto do projeto
no momento. No Subversion, essa idia parece estar em todo lugar. Cada reviso do repositrio
exatamente issouma foto da estrutura depois de cada commit.
Entretanto, pessoas normalmente querem dar rtulos mais amigveis como nomes de tags, como
verso-1.0. E querem fazer fotos de pequenos sub-diretrios da estrutura. Alm do mais, no
fcil lembrar que verso-1.0 de um pedao do software um particular sub-diretrio da reviso 4822.
94
Fundir e Ramificar
Este exemplo assume que o diretrio /calc/tags j existe. (Se ele no existir, voc pode cri-lo
usando svn mkdir.) Depois da copia completar, o novo diretrio verso-1.0 ser para sempre uma
foto de como o projeto estava na reviso HEAD no momento que a copia foi feita. Claro que voc pode
querer mais preciso em saber qual reviso a copia foi feita, em caso de algum ter feito commit no
projeto quando voc no estava vendo. Ento se voc sabe que a reviso 350 do /calc/trunk
exatamente a foto que voc quer, voc pode especificar isso passando -r 350 para o comando svn
copy.
Mas espere um pouco: no essa criao do rtulo o mesmo procedimento para criar um ramo? Sim,
de fato, . No Subversion, no h diferena entre um rtulo e um ramo. Assim como com ramos, a
nica razo uma cpia um rtulo porque humanos decidiram tratar isso desse jeito: desde que
ningum nunca faa commit para esse diretrio, ele permanecer para sempre uma foto. Se as pessoas
comearem a fazer commit para ele, ele se transoforma num ramo.
Se voc est administrando um repositrio, existe duas maneiras para gerenciar rtulos. A primeira
no toque: como uma poltica do projeto, decida onde os rtulos vo morar, e garanta que todos os
usurios saibam como tratar os diretrios que eles vo copiar para l. (Isso quer dizer, garanta que
eles saibam que no devem fazer neles.) A segunda mais paranica: voc pode usar um dos scripts
de controle de acesso providos com o Subversion para previnir que algum faa algo alm de apenas
criar novas copias na rea de rtulos (Veja Captulo 6, Configurao do Servidor.) A maneira paranoica,
entrentanto, no necessria. Se algum usurio acidentalmente fizer commit de alguam mudana para
o diretrio de rtulo, voc pode simplesmente desfazer a mudana como discutido na reviso anterior.
um controle de verso apesar de tudo.
Por exemplo, pense que seu projeto muito maior que nosso exemplo calc: suponha que contm um
nmero de sub-diretrios e muitos outros arquivos. No curso do seu trabalho, voc pode decidir que
voc precisa criar um cpia de trabalho que destinado para novos recursos e correes de erros.
Voc pode conseguir isso selecionando arquivos e diretrios com datas anteriores em uma reviso
particular (usando svn update -r livremente), ou mudando arquivos e diretrios para um ramo em
particular (fazendo uso do svn switch). Quando estiver pronto, sua cpia de trabalho ser uma mistura
de diferentes revises. Mas depois de testes, voc saber que exatamente a combinao que voc
precisa.
Hora de fazer a foto. Copiar uma URL para outra no vai funcionar aqui. Nesse caso, voc quer fazer
uma foto exata da cpia de trabalho que voc organizou e armazenar no repositrio. Felizmente, svn
copy na verdade tem quatro diferentes maneiras de ser usado (voc pode ler sobre em Captulo 9,
Referncia Completa do Subversion), incluindo a habilidade de copiar uma rvore de cpia de trablho
para o respositrio:
$ ls
my-working-copy/
95
Fundir e Ramificar
Agora existe um novo diretrio no respositrio /calc/tags/mytag, que uma foto exata da sua cpia
de trabalhocombinado revises, URLs, e tudo mais.
Outros usurios tem encontrado usos interessantes para esse recurso. Algumas vezes existe situaes
onde voc tem um monte de mudanas locais na sua cpia de trabalho, e voc gostaria que um colega
de trabalho as visse. Ao invs de usar svn diff e enviar o arquivo patch (que no ir ter as informaes
de mudana na rvore de diretrios, em symlink e mudanas nas propriedades), voc pode usar svn
copy para subir sua cpia local para uma rea privada no repositrio. Seu colega pode verificar o
nome de cpia da sua cpia de trabalho, ou usar svn merge para receber as exatas mudanas.
Sendo isso um mtodo legal para subir uma rpida foto do seu trabalho local, note que isso no
uma boa maneira de iniciar um ramo. A criao de um ramo deve ser um evento solitrio, e esse
mtodo exige a criao de um ramo com mudanas extras em arquivos, tudo em uma nica reviso.
Isso dificulta muito (mais tarde) a identificar um nmero de uma reviso como um ponto de um ramo.
O comando svn switch, como svn update, preserva suas edies locais. Nesse ponto,
sua cpia de trabablho um reflexo do novo ramo criado, e seu prximo svn commit ira
enviar suas mudanas para l.
Manuteno de Ramos
Voc pode ter notado por agora que o Subversion extremamente flexvel. Como ele implementa
ramos e rtulos usando o mesmo mecanismo de suporte (cpias de diretrio), e como ramos e rtulos
aparecem normalmente no espao do sistema de arquivos, muitas pessoas vem o Subversion como
algo intimidador. Ele realmente muito flexvel. Nesta sei, vamos lhe dar algumas sugestes sobre
como arrajar e gerenciar seus dados ao longo do tempo.
Estrutura de Repositrio
H algumas formas padronizadas e recomendadas de se organizar um repositrio. A maioria das
pessoas criam um diretrio trunk para conter a linha principal do desenvolvimento, um diretrio
branches para conter cpias ramificadas, e um diretrio tags para conter cpias rotuladas. Se
um repositrio for armazenar apenas um projeto, ento quase sempre as pessoas criam esses trs
diretrios de alto nvel:
/trunk
/branches
/tags
/paint/trunk
/paint/branches
96
Fundir e Ramificar
/paint/tags
/calc/trunk
/calc/branches
/calc/tags
Mas claro, voc livre para ignorar estes layouts comuns. Voc pode criar qualquer tipo de variao,
que atenda melhor s suas necessidades e de sua equipe. Lembre que qualquer que seja a estrutura
que voc escolha, no uma definio permanente. Voc pode reorganizar seu repositrio a qualquer
momento. Como branches e tags so diretrios comuns, o comando svn move pode mov-los ou
renome-los como voc queira. Mudar de um layout para outro apenas uma questo de executar
algumas movimentaes no lado do servidor; se voc no gostar da forma como as coisas estiverem
organizadas no repositrio, apenas manipule os diretrios com achar melhor.
Lembre-se, porm, que por mais que mover diretrios possa ser algo fcil de se fazer, voc precisa
ter considerao com seus usurios tambm. Suas modificaes no repositrio podem confundir os
usurios que j tenham cpias de trabalho. Se um usurio j tem uma cpia de trabalho de um dado
diretrio do repositrio, executar svn move pode remover o caminho na prxima reviso. Da prxima
vez que o usurio executar svn update, ele ser informado que sua cpia de trabalho representa um
caminho que no existe mais, e o usurio ser forado a executar um svn switch para o novo local.
E agora seu ramo se foi. claro que ele no se foi realmente: o diretrio foi simplesmente removido
da reviso HEAD para no distrair mais ningum. Se voc executar svn checkout, svn switch, ou svn
list para verificar uma reviso anterior, voc ainda poder ver seu antigo ramo.
Se navegar em seu diretrio excludo no for o bastante, voc sempre poder traz-lo de volta.
Ressuscitar dados algo muito fcil no Subversion. Se houver um diretrio (ou arquivo) excludo que
voc gostaria de trazer de volta para a reviso HEAD, simplesmente use svn copy -r para copi-lo a
partir de sua reviso antiga:
Em nosso exemplo, seu ramo pessoal tinha um ciclo de vida relativamente curto: voc pode t-lo criado
para corrigir um bug ou implementar um novo recurso. Quando sua tarefa estiver terminada, ento
o ramo tambm estar. No desenvolvimento de software, porm, tambm comum ter dois ramos
principais executando lado-a-lado por longos perodos. Por exemplo, suponha que seja o momento de
lanar uma verso estvel do projeto calc para o pblico, e voc sabe que ir levar mais alguns meses
para remover todos os bugs do software. Voc no quer que as pessoas adicionem novos recursos
ao projeto, mas voc tambm no quer dizer para que todos os desenvolvedores parem de trabalhar.
Assim, voc cria um ramo estvel do software, o qual voc no ir modificar muito:
97
Fundir e Ramificar
http://svn.example.com/repos/calc/branches/stable-1.0 \
-m "Creating stable branch of calc project."
Ramos de fornecedores
Como especialmente o caso quando se trata de desenvolvimento de software, os dados que
voc mantm sob controle de verso freqentemente so intimamente relacionados a, ou talvez
dependentes de, dados alheios. Geralmente, as necessidades do seu projeto determinaro que voc
fique to atualizado quanto possvel em relao aos dados fornecidos por essa entidade externa sem
sacrificar a estabilidade do seu prprio projeto. Este cenrio se repete o tempo todoem qualquer
lugar onde a informao gerada por um grupo de pessoas tem um efeito direto sobre o que gerado
por outro grupo.
Por exemplo, desenvolvedores de software podem estar trabalhando em um aplicativo que faz
uso de uma biblioteca de terceiros. O Subversion tem tal relacionamento com a biblioteca Apache
Portable Runtime (ver A Biblioteca Apache Portable Runtime). O cdigo fonte do Subversion
depende da biblioteca APR para todas as suas necessidades de portabilidade. Em fases anteriores
do desenvolvimento do Subversion, o projeto seguiu de perto as mudanas na API da APR, aderindo
sempre ao estado da arte das agitaes no cdigo da biblioteca. Agora que tanto a APR quanto o
Subversion amadureceram, o Subversion tenta sincronizar com a API da biblioteca APR somente em
liberaes estveis e bem testadas.
Agora, se seu projeto depende de informaes de algum, existem vrias maneiras pelas quais voc
poderia tentar sincronizar essas informaes com as suas prprias. Mais dolorosamente, voc poderia
emitir oral instrues orais ou por escrito a todos os contribuintes do seu projeto, dizendo-lhes para se
certificar de que tm as verses especficas dessa informao de terceiros de que seu projeto precisa.
Se a informao de terceiros mantida em um repositrio Subversion, voc tambm pode utilizar as
definies externas do Subversion para efetivamente imobilizar verses especficas dessa informao
em algum lugar no prprio diretrio da sua cpia de trabalho (ver Definies Externas).
Mas s vezes voc quer manter modificaes personalizadas de dados de terceiros em seu
prprio sistema de controle de verses. Retornando ao exemplo do desenvolvimento de software,
programadores poderiam precisar fazer modificaes naquela biblioteca de terceiros para seus prprios
propsitos. Estas alteraes poderiam incluir novas funcionalidades ou correes de bugs, mantidas
apenas internamente at se tornarem parte de uma liberao oficial da biblioteca de terceiros. Ou as
mudanas poderiam nunca ser transmitidas de volta para os mantenedores da biblioteca, existindo
apenas como ajustes personalizados para fazer com que a biblioteca atenda melhor as necessidades
dos desenvolvedores de software.
Agora voc enfrenta uma situao interessante. Seu projeto poderia abrigar suas prprias modificao
aos dados de terceiros de algum modo desarticulado, tal como a utilizao de patches ou verses
alternativas completas dos arquivos e diretrios. Mas estas rapidamente tornam-se dores de cabea
para a manuteno, exigindo algum mecanismo para aplicar suas alteraes personalizadas aos dados
de terceiros, e necessitando de regenerao dessas mudanas a cada sucessiva verso dos dados
de terceiros que voc acompanha.
A soluo para este problema usar ramos de fornecedores (vendor branches). Um ramo de fornecedor
uma rvore de diretrios no nosso prprio sistema de controle de verses que contm informaes
98
Fundir e Ramificar
fornecidas por uma entidade de terceiros, ou fornecedor. Cada verso dos dados do fornecedor que
voc decidir absorver em seu projeto chamada pingo de fornecedor (vendor drop).
Os ramos de fornecedor proporcionam dois benefcios. Primeiro, por armazenar o pingo de fornecedor
atualmente suportado em seu prprio sistema de controle de verso, os membros do seu projeto nunca
precisam perguntar se tm a verso correta dos dados do fornecedor. Eles simplesmente recebem essa
verso correta como parte de suas atualizaes regulares da cpia de trabalho. Em segundo lugar,
como os dados residem em seu prprio repositrio Subversion, voc pode armazenar as alteraes
personalizadas feitas nele no prprio localvoc no precisa mais de um mtodo automatizado (ou
pior, manual) para incluir no projeto suas personalizaes.
Talvez um exemplo ajudar a esclarecer este algoritmo. Usaremos um cenrio onde a sua equipe de
desenvolvimento est criando um software de calculadora que referencia uma complexa biblioteca de
aritmtica de terceiros, libcomplex. Comearemos com a criao inicial do ramo de fornecedor, e a
importao do primeiro pingo de fornecedor. Iremos chamar o nosso diretrio do ramo de fornecedor
de libcomplex, e nossos pingos de cdigo iro para um subdiretrio do nosso ramo de fornecedor
chamado current. E como svn import cria todos os diretrios pais intermedirios de que precisa,
ns podemos de fato realizar ambos os os passos com um nico comando.
Ns obtemos uma cpia do ramo principal do nosso projetoque agora inclui uma cpia do primeiro
pingo de fornecedore comeamos a trabalhar personalizando o cdigo de libcomplex. Antes que
saibamos, nossa verso modificada de libcomplex agora est completamente integrada ao nosso
5
programa da calculadora.
5
E inteiramente livre de bugs, claro!
99
Fundir e Ramificar
Algumas semanas depois, os desenvolvedores da libcomplex lanam uma nova verso da sua
bibliotecaverso 1.1que contm algumas caractersticas e funcionalidades que ns queremos
muito. Ns gostaramos de atualizar para esta nova verso, mas sem perder as personalizaes que
fizemos na verso existente. O que ns essencialmente gostaramos de fazer substituir nossa atual
verso base da libcomplex 1.0 por uma cpia da libcomplex 1.1 e, em seguida, voltar a aplicar as
modificaes que fizemos anteriormente na biblioteca, desta vez para a nova verso. Mas na prtica
ns abordamos o problema na outra direo, aplicando as alteraes feitas em libcomplex entre as
verses 1.0 e 1.1 diretamente na nossa cpia personalizada dela.
Para executar esta atualizao, ns obtemos uma cpia do nosso ramo de fornecedor, e substitumos o
cdigo no diretrio current pelo novo cdigo fonte da libcomplex 1.1. Ns literalmente copiamos novos
arquivos sobre os arquivos existentes, talvez descompactando a verso compactada da libcomplex
1.1 sobre nossos arquivos e diretrios existentes. A meta aqui fazer nosso diretrio current conter
apenas o cdigo da libcomplex 1.1, e garantir que todo esse cdigo esteja sob controle de verso. Ah,
e ns queremos fazer isto com o mnimo possvel de perturbao no histrico do controle de verso.
Aps substituir o cdigo 1.0 pelo cdigo 1.1, svn status vai mostrar arquivos com modificaes locais
assim como, talvez, alguns arquivos fora do controle de verso ou faltantes. Se ns fizemos o que
deveramos ter feito, os arquivos fora do controle de verso so apenas os novos arquivos introduzidos
na verso 1.1 da libcomplexns executamos svn add sobre eles para coloc-los sob controle verso.
Os arquivos faltantes so arquivos que estavam em 1.0, mas no em 1.1, e sobre esses caminhos ns
executamos svn delete. Por fim, uma vez que nossa cpia de trabalho current contm apenas o
cdigo da libcomplex 1.1, ns submetemos as alteraes que fizemos para que ela ficasse desse jeito.
Nosso ramo current agora contm o novo pingo de fornecedor. Ns rotulamos a nova verso (da
mesma maneira que anteriormente rotulamos o pingo de fornecedor da verso 1.0), e em seguida
fundimos as diferenas entre o rtulo da verso anterior e a nova verso atual em nosso ramo principal
de desenvolvimento.
$ cd working-copies/calc
$ svn merge http://svn.exemplo.com/repos/vendor/libcomplex/1.0 \
http://svn.exemplo.com/repos/vendor/libcomplex/current \
libcomplex
# resolva todos os conflitos entre as alteraes deles e as nossas
$ svn commit -m 'fundindo libcomplex-1.1 com o ramo principal'
No caso de uso trivial, a nova verso da nossa ferramenta de terceiros pareceria com a verso anterior,
de um ponto de vista de arquivos e diretrios. Nenhum dos arquivos fonte de libcomplex teria sido
excludo, renomeado ou movido para locais diferentesa nova verso conteria apenas alteraes
textuais em relao anterior. Em um mundo perfeito, nossas alteraes seriam facilmente aplicadas
nova verso da biblioteca, sem absolutamente nenhuma complicao ou conflito.
Mas as coisas nem sempre so assim to simples, e na verdade bastante comum que arquivos
fonte sejam movidos de lugar entre liberaes de software. Isto dificulta o processo de garantir que as
nossas alteraes ainda so vlidas para a nova verso do cdigo, e pode degradar rapidamente em
uma situao onde teremos de recriar manualmente as nossas customizaes na nova verso. Uma
vez que o Subversion conhece a histria de um determinado arquivo fonteincluindo todas as suas
localizaes anterioreso processo de fuso da nova verso da biblioteca bem simples. Mas ns
somos responsveis por dizer ao Subversion como a posio do arquivo fonte mudou entre um pingo
de fornecedor e outro.
svn_load_dirs.pl
Vendor drops that contain more than a few deletes, additions and moves complicate the process
of upgrading to each successive version of the third-party data. So Subversion supplies the
svn_load_dirs.pl script to assist with this process. This script automates the importing steps we
100
Fundir e Ramificar
mentioned in the general vendor branch management procedure to make sure that mistakes are
minimized. You will still be responsible for using the merge commands to merge the new versions of the
third-party data into your main development branch, but svn_load_dirs.pl can help you more quickly
and easily arrive at that stage.
In short, svn_load_dirs.pl is an enhancement to svn import that has several important characteristics:
It can be run at any point in time to bring an existing directory in the repository to exactly match an
external directory, performing all the necessary adds and deletes, and optionally performing moves,
too.
It takes care of complicated series of operations between which Subversion requires an intermediate
commitsuch as before renaming a file or directory twice.
It will optionally add arbitrary properties to files and directories that match a regular expression.
svn_load_dirs.pl takes three mandatory arguments. The first argument is the URL to the base
Subversion directory to work in. This argument is followed by the URLrelative to the first argument
into which the current vendor drop will be imported. Finally, the third argument is the local directory to
import. Using our previous example, a typical run of svn_load_dirs.pl might look like:
$ svn_load_dirs.pl http://svn.example.com/repos/vendor/libcomplex \
current \
/path/to/libcomplex-1.1
You can indicate that you'd like svn_load_dirs.pl to tag the new vendor drop by passing the -t
command-line option and specifying a tag name. This tag is another URL relative to the first program
argument.
$ svn_load_dirs.pl -t libcomplex-1.1 \
http://svn.example.com/repos/vendor/libcomplex \
current \
/path/to/libcomplex-1.1
When you run svn_load_dirs.pl, it examines the contents of your existing current vendor drop, and
compares them with the proposed new vendor drop. In the trivial case, there will be no files that are in
one version and not the other, and the script will perform the new import without incident. If, however,
there are discrepancies in the file layouts between versions, svn_load_dirs.pl will ask you how to
resolve those differences. For example, you will have the opportunity to tell the script that you know that
the file math.c in version 1.0 of libcomplex was renamed to arithmetic.c in libcomplex 1.1. Any
discrepancies not explained by moves are treated as regular additions and deletions.
The script also accepts a separate configuration file for setting properties on files and directories
matching a regular expression that are added to the repository. This configuration file is specified to
svn_load_dirs.pl using the -p command-line option. Each line of the configuration file is a whitespace-
delimited set of two or four values: a Perl-style regular expression to match the added path against, a
control keyword (either break or cont), and then optionally a property name and value.
101
Fundir e Ramificar
For each added path, the configured property changes whose regular expression matches the path are
applied in order, unless the control specification is break (which means that no more property changes
should be applied to that path). If the control specification is contan abbreviation for continue
then matching will continue with the next line of the configuration file.
Any whitespace in the regular expression, property name, or property value must be surrounded by
either single or double quote characters. You can escape quote characters that are not used for wrapping
whitespace by preceding them with a backslash (\) character. The backslash escapes only quotes when
parsing the configuration file, so do not protect any other characters beyond what is necessary for the
regular expression.
Sumrio
Ns cobrimos muito cho nesse captulo. Ns discutimos conceitos de rtulotags e ramos branches,
e demonstramos como Subversion implementa estes conceitos atravs da cpia de diretrios com o
comando svn copy. Ns mostramos como usar svn merge para copiar mudanas de um ramo branch
para outro, ou reverter mudanas indesejadas. Ns passamos pelo uso do svn switch para criar locais
mistos de copias de trabalho. E ns falamos sobre como eles podem gerenciar a organizao e vida
dos ramos branches em um respositrio.
Lembre-se do mantra do Subversion: ramos branches e rtulos tags so baratos. Ento use-os
livremente! Ao mesmo tempo, no esquea de usar bons hbitos de fuso merge. Cpias baratas so
teis apenas quando voc cuidadoso ao rastrear suas fuses merges.
102
Captulo 5. Administrao do
Repositrio
O repositrio Subversion a central de todos os dados que esto sendo versionados. Assim, ele
se transforma num candidato bvio para receber todo amor e ateno que um administrador pode
oferecer. Embora o repositrio seja geralmente um item de baixa manuteno, importante entender
como configurar e cuidar apropriadamente para que problemas potenciais sejam evitados, e problemas
eventuais sejam resolvidos de maneira segura.
Neste captulo, vamos discutir sobre como criar e configurar um repositrio Subversion. Vamos falar
tambm sobre manuteno, dando exemplos de como e quando usar as ferramentas svnlook e
svnadmin providas pelo Subversion. Vamos apontar alguns questionamentos e erros, e dar algumas
sugestes sobre como organizar seus dados em um repositrio.
Se voc planeja acessar um repositrio Subversion apenas como um usurio cujos dados esto sendo
versionados (isto , por meio de um cliente Subversion), voc pode pular esse captulo todo. Entretanto,
1
se voc , ou deseja se tornar, um administrador de um repositrio Subversion, este captulo para
voc.
Vendo pelos olhos de um tpico navegador de arquivos (como o Windows Explorer) ou de ferramentas
de navegao em sistemas de arquivos baseadas em linha de comando, o repositrio Subversion
apenas outro diretrio cheio de coisas. Existem alguns subdiretrios que possuem arquivos de
configurao que podem ser lidos por humanos, e outros que no so to fceis de serem lidos, e assim
por diante. Como em outras reas do projeto do Subversion, modularidade tem grande importncia,
e a organizao hierrquica usada pra controlar o caos. Assim, uma olhada superficial nas partes
essenciais suficiente para revelar os componentes bsicos do repositrio:
$ ls repos
conf/ dav/ db/ format hooks/ locks/ README.txt
Aqui est uma pequena pincelada do que exatamente voc est vendo nessa lista do diretrio.
(No fique assustado com a terminologiauma explicao mais detalhada desses componentes est
disponvel em algum lugar nesse e em outros captulos.)
conf
Um diretrio contendo arquivos de configurao do repositrio.
dav
Um diretrio onde ficam os arquivos usados pelo mod_dav_svn.
db
Local onde so armazenados todos os seus dados versionados.
1
Isto pode soar bem metido ou arrogante, mas ns estamos apenas falando de algum que tenha interesse no misterioso local
por trs das cpias de trabalho onde os dados de todos ficam.
103
Administrao do Repositrio
format
Um arquivo que contm um simples inteiro que indica o nmero da verso do repositrio.
hooks
Um diretrio cheio de modelos de scripts (e scripts, uma vez que voc tenha instalado algum).
locks
Um diretrio para arquivos travados do Subversion, usado para rastrear acessos ao repositrio.
README.txt
Arquivo que meramente informa a seus leitores que eles esto olhando para um repositrio
Subversion.
claro que, quando acessado por meio das bibliotecas do Subversion, esse estranho conjunto de
arquivos e diretrios de repente torna-se uma implementao de um sistema de arquivos virtual,
versionvel e completo, com gatilhos hook de eventos personalizveis. Este sistema de arquivos tem
o seu prprio entendimento sobre diretrios e arquivos, muito semelhante aos conceitos usados em
sistemas de arquivos reais (como NTFS, FAT32, ext3, e assim por diante). Mas este um sistema
de arquivos especialele controla os diretrios e arquivos a partir das revises, mantendo todas as
mudanas que voc fez neles armazenadas com segurana e sempre acessveis. aqui onde todos
os seus dados versionados vivem.
Que dados voc espera armazenar no seu repositrio (ou repositrios), e como eles sero
organizados?
Vamos assumir que como administrador de repositrio voc ser responsvel pelo suporte do sistema
de controle de verses para vrios projetos. Sua primeira deciso se usar um nico repositrio para
104
Administrao do Repositrio
mltiplos projetos, ou fornecer para cada projeto o seu prprio repositrio, ou ainda alguma combinao
disso.
Existem vantagens em se utilizar um nico repositrio para mltiplos projetos e a mais bvia a
ausncia de manuteno duplicada. Um nico repositrio significa que haver um nico conjunto
de programas de ganchos, uma nica coisa para fazer cpias de segurana peridicas, uma nica
coisa para descarregar e carregar se o Subversion lana um nova verso incompatvel, e por a vai.
Alm disso, voc pode mover dados entre projetos facilmente, e sem perder qualquer informao de
versionamento.
A desvantagem de usar um nico repositrio que diferentes projetos podem ter diferentes requisitos
em termos de ganchos de eventos, como por exemplo a necessidade de enviar notificaes de
submisso para diferentes listas de e-mail, ou ter diferentes definies sobre o que constitui uma
submisso correta. claro que eles no so problemas insuperveissomente significa que todos
os seus scripts de ganchos devem ser sensveis ao leiaute do seu repositrio ao invs de assumir
que todo o repositrio est associado com um nico grupo de pessoas. Alm disso, lembre-se que o
Subversion usa nmeros de reviso globais com relao ao repositrio. Muito embora esses nmeros
no tenham particularmente nenhum poder mgico, algumas pessoas continuam no gostando do fato
de que mesmo que no hajam modificaes no seu projeto recentemente o nmero de reviso continua
2
sendo incrementado porque outros projetos continuam adicionando novas revises.
Uma abordagem meio termo pode ser utilizada tambm. Por exemplo, projetos podem ser agrupados
pela forma como eles se relacionam entre si. Voc pode ter alguns poucos repositrios com um punhado
de projetos em cada um deles. Dessa forma, projetos nos quais desejvel o compartilhamento
de dados podem faz-lo facilmente, e quando novas revises so adicionadas ao repositrio, os
desenvolvedores sabero que essas revises so no mnimo remotamente relacionadas com todos
que usam esse repositrio.
Depois de decidir como organizar seus projetos com relao aos repositrios voc ir provavelmente
pensar sobre a hierarquia de diretrios l dentro. Como o Subversion utiliza cpias comuns de diretrios
para ramificaes (branches) e rtulos (tags) (veja Captulo 4, Fundir e Ramificar), a comunidade
recomenda que voc escolha uma localizao para cada raiz de projetoo mais alto diretrio que ir
conter dados relacionados com o projetoe ento criar trs subdiretrios abaixo desse raiz: trunk,
o diretrio no qual o desenvolvimento principal do projeto ocorre; branches, diretrio no podem ser
criados vrios ramos da linha principal de desenvolvimento; tags, diretrio que poder conter uma
coleo de instantneos de rvores de diretrio que so criados, e possivelmente destrudos, mas
3
nunca alterados.
/
calc/
trunk/
tags/
branches/
calendar/
trunk/
tags/
branches/
spreadsheet/
trunk/
tags/
branches/
2
Quer seja baseado na ignorncia ou em fracos conceitos sobre como produzir mtricas de desenvolvimento corretamente,
nmeros de revises globais so uma coisa tola para temer, e no o tipo de coisa que voc deveria pesar na hora de decidir
como organizar seus projetos e repositrios.
3
O trio trunk, tags, e branches so muitas vezes chamados de diretrios TTB.
105
Administrao do Repositrio
Note que no importa onde est cada raiz de projeto no seu repositrio. Se voc possuir somente um
nico projeto por repositrio, o lugar mais lgico para colocar cada raiz de projeto na raiz do respectivo
repositrio do projeto. Se voc possui mltiplos projetos, voc pode querer organiz-los em grupos
dentro do repositrio, talvez colocando projetos com objetivos semelhantes ou cdigo compartilhado
no mesmo subdiretrio, ou talvez simplesmente agrup-los alfabeticamente. Tal organizao poderia
se parecer com o que segue:
/
utils/
calc/
trunk/
tags/
branches/
calendar/
trunk/
tags/
branches/
office/
spreadsheet/
trunk/
tags/
branches/
Organize seu repositrio da forma que voc preferir. O Subversion no espera ou fora uma
organizao particularna sua viso, um diretrio um diretrio. No final das contas voc deve
escolher a organizao de repositrio que atende as necessidades das pessoas que trabalham nos
projetos que iro viver l.
Em nome da revelao completa, no entanto, ns iremos mencionar outra forma muito comum de
organizao. Nesse leiaute os diretrios trunk, tags e branches residem no diretrio raiz do
repositrio e os projetos esto em subdiretrios abaixo deles, como:
/
trunk/
calc/
calendar/
spreadsheet/
tags/
calc/
calendar/
spreadsheet/
branches/
calc/
calendar/
spreadsheet/
No existe nada de incorreto nessa forma de organizao, mas ela pode ou no parecer intuitiva
para seus usurios. Especialmente em situaes de vrios e grandes projetos com muitos usurios,
esses usurios podem tender a se familiarizar com somente um ou dois projetos no repositrio. Utilizar
projetos como ramos irmos tende a desenfatizar a individualidade dos projetos e focar no conjunto
inteiro como uma nica entidade. De qualquer forma essa uma questo social. Ns gostamos
da organizao inicialmente proposta por razes puramente prticas fcil perguntar sobre (ou
106
Administrao do Repositrio
modificar, ou migrar para outro lugar) o histrico completo de um nico projeto quando existe um nico
caminho no repositrio que guarda tudopassado, presente, etiquetas, e ramosreferente ao projeto
sozinho.
Averiguar cada possvel maneira de implantao do Subversion tambm impossvel, e fora do escopo
deste livro. Simplesmente encorajamos voc a avaliar suas opes usando estas pginas e outras
fontes como seu material de referncia, e planejar a partir da.
Tabela 5.1, Comparativo dos Mecanismos de Armazenamento fornece um comparativo geral dos
repositrios Berkeley DB e FSFS.
107
Administrao do Repositrio
Felizmente, muitos programas que acessam os repositrios Subversion so abenoados por ignorarem
o mecanismo de armazenamento que est em uso. E voc nem mesmo precisa se preocupar com a sua
primeira escolha de mecanismo de armazenamentono caso de voc mudar de idia posteriormente,
o Subversion oferece formas de migrar os dados do seu repositrio para outro repositrio que usa um
mecanismo de armazenamento diferente. Ns iremos falar mais sobre isso nesse captulo.
As seguintes subsees oferecem uma viso mais detalhada sobre os tipos de mecanismos de
armazenamento disponveis.
Berkeley DB
Quando a fase de projeto inicial do Subversion estava em andamento, os desenvolvedores decidiram
usar o Berkeley DB por diversas razes, incluindo sua licena open-source, suporte a transaes,
108
Administrao do Repositrio
O Berkeley DB oferece suporte real para transaestalvez seu recurso mais poderoso. Mltiplos
processos que acessem seus repositrios Subversion no precisam se preocupar em sobrescrever
acidentalmente os dados uns dos outros. O isolamento oferecido pelo sistema de transaes age de
tal forma que, para cada operao realizada, o cdigo no repositrio do Subversion tenha uma viso
esttica da base de dadose no uma base de dados que esteja mudando constantemente nas mos
de alguns outros processose possa tomar decises baseadas no que v. Se uma deciso tomada
parecer conflitar com o que outro processo esteja fazendo, a operao inteira desfeita como se nunca
tivesse acontecido, e o Subversion graciosamente ir tentar executar a operao sobre uma nova,
atualizada (e ainda assim, esttica) viso da base de dados.
Outro grande recurso do Berkeley DB o backup a quentea habilidade de executar uma cpia de
segurana do ambiente da base de dados sem precisar deixar o sistema offline. Vamos discutir como
fazer cpias de segurana de seu repositrio em Backup de Repositrio, mas os benefcios de se
poder fazer cpias funcionais de seus repositrios sem desligar o sistema devem lhe ser bvios.
Berkeley DB tambm um sistema de base de dados muito confivel quando utilizado adequadamente.
O Subversion usa as facilidades de registros de log do Berkeley DB, o que quer dizer que a base
de dados primeiro escreve uma descrio de quaisquer modificaes que estiver para fazer em seus
arquivos de log em disco, e s ento realiza a modificao em si. Isto para garantir que se qualquer
coisa der errado, o sistema da base de dados pode se recuperar para um determinado ponto de
verificao (checkpoint) anteriorum local nos arquivos de log que se sabe no estarem corrompidos
e re-executa as transaes at que os dados sejam restaurados para um estado utilizvel. Veja
Gerenciando Espao em Disco para saber mais sobre os arquivos de log do Berkeley DB.
Mas cada rosa tem seus espinhos, e assim devemos destacar algumas conhecidas limitaes
do Berkeley DB. Em primeiro lugar, o ambiente do Berkeley DB no portvel. Voc no pode
simplesmente copiar um repositrio do Subversion que foi criado em um sistema Unix para dentro de
um sistema Windows e esperar que funcione. Ainda que muito do formato da base de dados do Berkeley
DB seja independente de plataforma, h alguns aspectos do ambiente que no o so. Em segundo
lugar, o Subversion utiliza o Berkeley DB de forma que no ir funcionar em sistemas Windows 95/98
se voc precisa hospedar um repositrio em formato Berkeley DB em uma mquina Windows, utilize-
o com sistemas Windows 2000 ou posteriores.
109
Administrao do Repositrio
Assim, por mais que que um repositrio Berkeley DB seja bastante rpido e escalvel, ele melhor
aproveitado se for utilizado por um nico processo servidor executando como um nico usuriocomo
o httpd do Apache ou o svnserve (veja Captulo 6, Configurao do Servidor)ao invs do que por
vrios usurios diferentes atravs de URLs file:// ou svn+ssh://. Se voc for usar um repositrio
em Berkeley DB diretamente para mltiplos usurios, certifique-se de ler Dando Suporte a Mltiplos
Mtodos de Acesso ao Repositrio.
FSFS
Em meados de 2004, um segundo tipo de sistema de armazenamento de repositriosum que no
usa um banco de dados nasceu. Um repositrio FSFS armazena as mudanas relacionadas com
uma reviso em um nica arquivo, e assim todas as revises do repositrio podem ser encontradas
num nico subdiretrio que contm arquivos numerados. Transaes so criadas em subdiretrios
diferentes como arquivos individuais. Quando completa, o arquivo de transao renomeado e movido
para o diretrio de revises, garantindo assim que a transao ser atmica. Em funo do arquivo
de reviso ser permanente e imodificvel, tambm possvel fazer uma cpia de segurana quente
assim como os repositrios baseados em BDB.
Os arquivos de reviso FSFS decrevem uma estrutura de diretrios de uma reviso, contedo dos
arquivos, e diferenas em relao aos arquivos em outras rvores de reviso. Ao contrrio das baseas
de dados Berkeley DB esse formato de armazenamento portvel em muitos sistemas operacionais
e no sensvel a arquitetura de CPU. Em funo de no haver journaling ou arquivos com memria
compartilhada o repositrio pode ser acessado com segurana a partir de um sistema de arquivos de
rede e examinado em um ambiente somente para leitura. A inexistncia da sobrecarga de um banco
de dados tambm significa que o tamanho total do repositrio tambm um pouco menor.
FSFS tem caracterstica de desempenho diferentes tambm. Quando se submete um diretrio com um
alto nmero de arquivos, o FSFS capaz de rapidamente atualizar as entradas de diretrio. Por outro
lado, FSF escreve a ltima verso de um arquivo como um delta em relao uma verso anterior,
o que significa que obtee a ltima rvore de diretrios um pouco mais lento do que obter os textos
completos armazenados em uma reviso HEAD no Berkeley DB. O FSFS tambm possui uma certa
demora na finalizao de uma submisso, o que em casos extremos pode causar timeout no cliente.
A diferena mais importante, entretanto, o formato inabalvel do FSFS quando alguma coisa errada
acontece. Se ocorre um problema qualquer com um processo que est usando um banco de dados
Berkeley DB, o banco de dados pode ficar em um estado que no permite o seu uso at que um
adminitrador recupere ele. Se os mesmo cenrios acontecerem com um processo que utiliza FSFS, o
repositrio no afetado. No pior caso, algumas informaes de transao so deixadas para trs.
110
Administrao do Repositrio
O nico argumento coerente contra o FSFS que ele relativamente imaturo quando comparado
ao Berkeley DB. Ao contrrio do Berkeley DB que tem anos de histria, sua prpria equipe de
6
desenvolvimento e, agora, o grande nome da Oracle ligado ele, FSFS muito mais novo em termos
de engenharia. Antes da verso 1.4 ele ainda era afetado por algumas falhas bem srias com relao a
integridade dos dados, muito embora essas falhas ocorressem raramente, elas nunca deveriam ocorrer.
Dito isso, o FSFS tem se tornado rapidamente a escolha de armazenamento de alguns dos maiores
repositrios Subversion pblicos e privados, e oferece poucos obstculos a ponto de ser um bom ponto
de entrada para o Subversion.
Criando o Repositrio
A criao de um repositrio Subversion uma tarefa inacreditavelmente simples. O utilitrio svnadmin,
que vem com Subversion, oferece um subcomando (create) para fazer isso.
Dentro do subdiretrio db/ do seu repositrio est a implementao do sistema de arquivos versionado.
Seu novo sistema de arquivos versionado do repositrio comea sua vida na reviso 0, que consiste
apenas do diretrio raiz de mais alto nvel (/). Inicialmente a reviso 0 tambm tem uma nica
propriedadede reviso svn:date, configurada com o dia/hora em que o repositrio foi criado.
111
Administrao do Repositrio
$ ls repos/hooks/
post-commit.tmpl post-unlock.tmpl pre-revprop-change.tmpl
post-lock.tmpl pre-commit.tmpl pre-unlock.tmpl
post-revprop-change.tmpl pre-lock.tmpl start-commit.tmpl
Existe um modelo para cada gancho que o repositrio Subversion suporta, e examinando o contedo
desses scripts voc pode observar o que dispara cada script e que inforames so passadas para o
script. Tambm so apresentados, em muitos desses modelos, exemplos de como algum pode usar o
script em conjunto com outros programas disponibilizados pelo Subversion para desempenhar tarefas
teis e rotineiras. Para instalar um gancho voc somente precisa colocar algum programa executvel
ou script no diretrio repos/hooks que pode ser executado pelo nome do gancho (como start-commit
ou post-commit)
Na plataforma Unix, isso significa fornecer um script ou programa (que pode ser um script shell, um
programa Python, um binrio C compilado, ou qualquer outra coisa semelhante) com o nome exato
do gancho. claro que os arquivos modelos so apresentados para serem terem uma funo maior
do que simplesmente serem informativosa forma mais fcil de instalar um gancho na plataforma
Unix simplesmente copiar o arquivo modelo apropriado para um novo arquivo que leva a extenso
tmpl, personalizar o seu contedo e se assegurar de que o script executvel. Entretanto, o Windos
utiliza extenses de arquivos para determinar se um arquivo executvel ou no. Assim, voc precisa
fornecer um programa cujo o nome seja o mesmo do gancho e cuja extenso seja uma das extenses
especiais reconhecidas pelo Windows como um programa executvel, como por exemplo .exe para
programas, e .bat para arquivos de lote.
O Subversion executa os scripts de hooks como o mesmo usurio que executa o processo que estiver
acessando o repositrio do Subversion. Na maioria dos casos, o repositrios estar sendo acessado
por um servidor Subersion, ento tal usurio o mesmo usurio com o qual o servidor executado
no sistema. Os scripts em si precisaro ser configurados em nvel de sistema operacional para
112
Administrao do Repositrio
permitir que esse usurio execute-os. Tambm, isto quer dizer que quaisquer arquivos ou programas
(incluindo o prprio repositrio do Subversion) que forem acessados direta ou indiretamente pelos
scripts sero executados como um mesmo usurio. Em outras palavras, esteja atento para potenciais
problemas relacionados a permisses e que podem acabar impedindo os scripts de hook de executar
adequadamente as devidas tarefas para as quais foram programados.
Existem nove scripts de hook j implementados pelo repositrio do Subversion, e voc pode ver mais
detalhes sobre cada um em Ganchos do Repositrio. Como um administrador de repositrio. voc
vai precisar decidir sobre quais scripts voc vai querer implementar e como. Quando voc tomar esta
deciso, tenha em mente a viso geral de como seu repositrio est implantado. Por exemplo, se
voc estiver usando uma configurao de servidor para determinar que usurios tm permisso para
submeter alteraes no repositrio, ento voc no precisa fazer fazer este tipo de controle de acesso
por meio do sistema de scripts de hook.
Ainda que muitos scripts de hook possam fazer muita coisa, h uma dimenso na qual os
autores de scripts devem se restringir: nunca modificar uma transao de commit utilizando
scripts de hook. Por mais que possa parecer tentador utilizar scripts para automatizar
correes de erros ou deficincias ou ainda violaes de polticas presentes nos arquivos
a serem submetidos, fazer isso resulta em problemas. O Subversion mantm caches
de certas pores de dados do repositrio no lado do cliente, e se voc modificar uma
transao de commit desta forma, estes caches ficaro inutilizveis de uma maneira
difcil de ser detectada. Essa inconsistncia pode levar a comportamentos errneos e
inesperados. Ao invs de modific-la, voc deveria simplesmente validar a transao em
um script pre-commit e rejeitar a submisso se os requisitos em questo desejados no
forem cumpridos. Como um bnus, seus usurios iro aprender o valor de hbitos de
trabalho cuidadosos e adequadamente.
Configurao do Berkeley DB
Um ambiente DB environment um encapsulamento de uma ou mais bases de dados, arquivos de log,
arquivos de regio e arquivos de configurao. O ambiente Berkeley DB possui seu prprio conjunto
de valores de configurao padro para coisas como o nmero de travas de base de dados possveis
a cada instante, ou o tamanho mximo de arquivos de log, etc. A lgica do sistema de arquivos
do Subversion adicionalmente escolhe valores padro para algumas das opes de configurao
do Berkeley DB. No entanto, algumas vezes seu repositrio especfico, o qual uma coleo nica
de dados e padres de acesso, pode requerer um conjunto diferente de valores para opes de
configurao.
113
Administrao do Repositrio
disso, modificar o arquivo DB_CONFIG no far efeito at que voc recupere o ambiente da base de
dados (usando svnadmin recover).
Manuteno do Repositrio
Manter um repositrio do Subversion pode ser algo intimidante, muito devido s complexidades
inerentes aos sistemas baseados em bases de dados. Fazer bem as tarefas tem a ver com conhecer
bem as ferramentaso que elas so, quando us-las, e como us-las. Esta seo vai apresentar a
voc as ferramentas de administrao do repositrio oferecidas pelo Subversion, e como utiliz-las
para executar tarefas como migrao de dados do repositrio, atualizaes, backups e limpezas.
svnadmin
O programa svnadmin o melhor amigo do administrador do repositrios do Subversion. Alm de
possibilitar a criao de repositrios, este programa permite a voc executar diversas operaes de
manuteno nesses repositrios. A subtaxe do svnadmin semelhante de outros programas de
linha de comando do Subversion:
$ svnadmin help
general usage: svnadmin SUBCOMMAND REPOS_PATH [ARGS & OPTIONS ...]
Type 'svnadmin help <subcommand>' for help on a specific subcommand.
Type 'svnadmin --version' to see the program version and FS modules.
Available subcommands:
crashtest
create
deltify
svnlook
O svnlook uma ferramenta oferecida pelo Subversion para se examinar vrias revises e transaes
(que so revises in-the-making) em um repositrio. Nenhuma parte deste programa tenta modificar
o repositrio. O svnlook tipicamente usado pelos scripts de hook do repositrio para informao
sobre as modificaes que esto para ser (no caso de um script pre-commit) ou que acabaram de
ser submetidas (no caso de scripts post-commit) ao repositrio. Um administador do repositrio pode
usar esta ferramenta para fins de diagnstico.
$ svnlook help
general usage: svnlook SUBCOMMAND REPOS_PATH [ARGS & OPTIONS ...]
Note: any subcommand which takes the '--revision' and '--transaction'
114
Administrao do Repositrio
Quase todos os subcomandos do svnlook podem operar tanto em uma reviso quanto em uma rvore
de transaes, exibindo informao sobre a rvore em si, ou sobre como ela difere da reviso anterior
do repositrio. Voc usa as opes --revision (-r) e --transaction (-t) para especificar,
respectivamente, a reviso ou transao a examinar. Na ausncia de ambas as opes --revision
(-r) e --transaction (-t), o svnlook ir examinar a reviso mais recente (ou HEAD) do
repositrio. Assim, os seguintes dois comandos fazem exatamente a mesma coisa quando a reviso
19 for a mais recente no repositrio localizado em /path/to/repos:
A nica exceo a essas regras o subcomando svnlook youngest, o qual no leva opes, e
simplesmente exibe o nmero da reviso mais recente do repositrio.
Tenha em mente que as nicas transaes que podem ser visualizadas so as que
ainda no foram submetidas. A maioria dos repositrios no tero tais transaes, j que
transaes normalmente so submetidas (neste caso, voc deveria acess-las por seu
nmero de reviso com a opo --revision (-r)) ou abortadas e removidas.
A sada do svnlook projetada para ser facilmente legvel tanto por humanos quanto analisvel por
computadores. Tome como um exemplo, a sada do subcomando info:
Esta sada legvel por humanos, o que quer dizer que itens como a data so exibidos usando uma
representao textual ao invs de algo mais obscuro (como o nmero de nanosegundos desde que
Judas perdeu as botas). Mas a sada tambm facilmente analisvel por um computadorj que a
mensagem de log pode conter mltiplas linhas e pode extrapolar no tamanho, o svnlook informa o
comprimento do texto da mensagem antes da mensagem em si. Isso permite que scripts que usem ou
encapsulem este comando possam tomar decises inteligentes sobre a mensagem de log, tais como
definir quanta memria alocar para a mensagem, ou ao menos quantos bytes desconsiderar no caso
de a sada no ser a ltima parte em um fluxo de dados.
115
Administrao do Repositrio
O svnlook pode executar uma poro de outras consultas: exibir subconjuntos de pedaos de
informao que j mencionamos anteriormente, listar rvores de diretrios versionados recursivamente,
informar que caminhos foram modificados em uma dada reviso ou transao, mostrar diferenas
textuais e de propriedades feitas em arquivos e diretrios, e assim por diante. Veja svnlook para uma
referncia completa dos recursos do svnlook.
svndumpfilter
Por mais que este no seja uma das ferramentas mais usadas disposio do administrador, o
svndumpfilter oferece uma funcionalidade nova e bastante tila capacidade de modificar rpida e
facilmente fluxos de dados do histrico do Subversion, agindo como um filtro baseado em caminhos.
$ svndumpfilter help
general usage: svndumpfilter SUBCOMMAND [ARGS & OPTIONS ...]
Type "svndumpfilter help <subcommand>" for help on a specific subcommand.
Type 'svndumpfilter --version' to see the program version.
Available subcommands:
exclude
include
help (?, h)
H apenas dois subcomandos interessantes. Eles lhe permitem fazer a escolha entre incluso de
caminhos explcita ou implcita no fluxo:
exclude
Exclui do filtro um conjunto de caminhos dos dados do fluxo de despejo.
include
Permite que apenas o conjunto de caminhos requisitados passem para os dados do fluxo de
despejo.
Voc pode aprender mais sobre esses subcomandos e o propsito nico do svndumpfilter em
Filtrando o Histrico do Repositrio.
svnsync
O programa svnsync, que uma das novidades da verso 1.4 so Subversion, oferece toda a
funcionalidade necessria para manter um espelho somente leitura de um repositrio do Subversion.
O programa realmente tem apenas um propsitotranferir o histrico versionado de um repositrio
para outro repositrio. E por mais que haja algumas poucas formas de fazer isso, seu principal ponto
7
forte poder operar remotamenteos repositrios de origem (source) e de destino (sink) podem
estar cada um em computadores diferentes entre si e mesmo longe da prpria mquina que executa
o svnsync.
Como voc pode supor, o svnsync tem uma sintaxe que parece muito com a de outros programas j
mencionados neste captulo:
$ svnsync help
general usage: svnsync SUBCOMMAND DEST_URL [ARGS & OPTIONS ...]
Type 'svnsync help <subcommand>' for help on a specific subcommand.
Type 'svnsync --version' to see the program version and RA modules.
7
Ou seria, sync?
116
Administrao do Repositrio
Available subcommands:
initialize (init)
synchronize (sync)
copy-revprops
help (?, h)
$
Utilitrios Berkeley DB
Se voc est usando um repositrio Berkeley DB, ento toda a estrutura de seu sistema de arquivos
e dados versionado reside em um conjunto de tabelas de base de dados dentro do subdiretrio db/
de seu repositrio. Este subdiretrio um diretrio do ambiente normal do Berkeley DB, e pode
dessa forma ser usado em conjunto com qualquer outras ferramentas de base de dados, tipicamente
disponveis como parte de uma distribuio do Berkeley DB.
Entretanto, h ainda alguns poucos utilitrios do Berkeley DB que voc pode achar teis. Os programas
db_dump e db_load escrevem e lem, respectivamente, um arquivo de formato especfico que
descreve as chaves e valores em uma base de dados Berkeley DB. Uma vez que as bases de dados
Berkeley DB no so portveis entre mquinas de arquiteturas diferentes, este formato tils para
transferir bases de dados de uma mquina a outra, independemente das arquiteturas ou sistemas
operacionais em questo. Como descrito depois neste captulo, voc sempre pode usar svnadmin
dump e svnadmin load para propsitos similares, mas db_dump e db_load podem fazer estas
tarefas adequadamente e de forma muito mais rpida. Esses comandos tambm podem ser teis
se um especialista em Berkeley DB precisar, por algum motivo, realizar otimizaes e ajustes de
dados diretamente em um repositrio baseado em BDB, coisa que alguns utilitrios do Subversion
no permitem. E ainda, o utilitrio db_stat pode oferecer informaes teis sobre o estado de seu
ambiente Berkeley DB environment, incluindo estatsticas detalhadas sobre os subsistemas de travas
e de armazenamento.
Para mais informaes sobre o conjunto de ferramentas do Berkeley DB, visite a rea de documentao
da seo Berkeley DB no site da Oracle, em http://www.oracle.com/technology/documentation/
berkeley-db/db/.
Se uma mensagem de log precisar ser modificada por um administrador, isto pode ser feito usando-
se svnadmin setlog. Este comando modifica a mensagem de log (a propriedade svn:log) em uma
dada reviso do repositrio, lendo o novo valor a partir de um arquivo informado.
117
Administrao do Repositrio
O comando svnadmin setlog, por padro, ainda est sujeito s mesmas protees contra modificao
de propriedades no versionadas que um cliente remotoos scripts pre- e post-revprop-change
ainda so disparados e devem estar definidos de forma a aceitar modificaes desta natureza. Mas
um administrador pode no se sujeitar a tais protees passando a opo --bypass-hooks para o
comando svnadmin setlog.
Lembre-se, porm, que ao ignorar os scripts de hook, voc est impedindo certas coisas,
como notificaes de alteraes por e-mail, backup de modificaes no versionadas do
sistema dentre outras, de acontecer. Em outras palavras, tenha muito cuidado com o que
voc est modificando, e como est fazendo tais modificaes.
Voc pode usar o comando lstxns do svnadmin para listar os nomes das transaes atualmente
pendentes.
118
Administrao do Repositrio
Cada item na sada resultante pode ento ser usada com o svnlook (e sua opo --transaction (-
t)) para determinar quem criou a transao, quando ela foi criada, ou que tipos de modificaes estava
contidas na transaoinformaes que so teis para determinar se se trata de uma transao que
pode ou no ser removida! Se voc pretende remover a transao, seu nome pode ser passado para o
svnadmin rmtxns, que ento far a limpeza da transao. De fato, o subcomando rmtxns pode obter
sua entrada diretamente a partir da sada do lstxns!
Se voc usar esses dois comandos desta forma, voc deveria considerar deixar seu repositrio
inacessvel temporariamente aos seus clientes. Dessa forma, ningum poder iniciar uma transao
legtima antes de voc comear a limpexa. Exemplo 5.1, txn-info.sh (Obtendo Informaes Sobre
Transaes Pendentes) contm um pouco de programao em shell script que pode facilmente gerar
informao sobre cada uma das transaes pendentes em seu repositrio.
#!/bin/sh
REPOS="${1}"
if [ "x$REPOS" = x ] ; then
echo "usage: $0 REPOS_PATH"
exit
fi
A sada do script basicamente uma concatenao de alguns trechos da sada do svnlook info (veja
svnlook), e ser algo parecido com isto:
$ txn-info.sh myrepos
---[ Transaction 19 ]-------------------------------------------
sally
2001-09-04 11:57:19 -0500 (Tue, 04 Sep 2001)
0
---[ Transaction 3a1 ]-------------------------------------------
harry
2001-09-10 16:50:30 -0500 (Mon, 10 Sep 2001)
39
Trying to commit over a faulty network.
---[ Transaction a45 ]-------------------------------------------
119
Administrao do Repositrio
sally
2001-09-12 11:09:28 -0500 (Wed, 12 Sep 2001)
0
$
Uma transao abandonada h muito tempo normalmente representa algum tipo de falha ou
interrupo na operao. A data de uma transao pode fornecer informao interessantepor
exemplo, como pode uma transao iniciada nove meses atrs ainda estar ativa?
Em suma, a deciso sobre operaes de limpeza no devem ser tomadas de qualquer jeito. Vrias
fontes de informaoincluindo logs de erro e de acesso do Apache, logs operacionais do Subversion,
o histrico de revises do Subversion e da em diantepodem ser empregadas no processo de tomada
de deciso. E, claro, um administrador pode muitas vezes, simplesmente falar com a pessoa (por
telefone ou e-mail, por exemplo) que parece ter iniciado a transao incompleta, para verificar se a
transao est, de fato, em um estado zumbi.
Felizmente, a partir da verso 4.2 do Berkeley DB, o ambiente de base de dados passou a ter a
capacidade de remover seus prprios arquivos de log no utilizados. Quaisquer repositrios criados
com o svnadmin compilado com suporte a Berkeley DB verso 4.2 ou posterior sero configurados
para fazer remoo automtica de arquivos de log. Se voc no quiser que este recurso esteja
disponvel, simplesmente passe a opo --bdb-log-keep para o comando svnadmin create. Se
voc se esquecer de fazer isto, ou se mudar de idia posteriormente, simplesmente modifique o arquivo
DB_CONFIG, encontrado no diretrio db de seu repositrio, descomentando a linha que contm a
diretiva set_flags DB_LOG_AUTOREMOVE, e ento execute svnadmin recover em seu repositrio
para forar que as modificaes de configurao tenham efeito. Veja Configurao do Berkeley DB
para mais informaes sobre configurao da base de dados.
Sem algum tipo de remoo automtica de arquivos de log disposio, os arquivos de log iro se
acumular conforme voc for usando seu repositrio. Atualmente isto um tipo de recurso do sistema
da base de dadosvoc deveria ser capaz de recriar sua base de dados inteira sem precisar de nada
alm dos arquivos de log, ento esses arquivos podem ser teis para recuperao da base de dados
aps algum desastre. Mas normalmente, voc vai querer arquivar os arquivos de log que no estiverem
mais sendo usados pelo Berkeley DB, e ento remov-los do disco para economizar espao. Use o
comando svnadmin list-unused-dblogs para listar os arquivos de log no utilizados:
Repositrios baseados em BDB e cujos arquivos de log forem usados como parte de um
plano de backup ou recuperao de desastres no deveria dispor do recurso de remoo
120
Administrao do Repositrio
Recuperao do Berkeley DB
Como mencionado em Berkeley DB, um repositrio Berkeley DB, algumas vezes pode ser deixado
em um estado congelado se no for fechado adequadamente. Quando isto acontece, um administrador
precisa retroceder a base de dados de volta a um estado consistente. Embora isso seja especfico
apenas para repositrios baseados em BDBassim, se voc estiver usando repositrios baseados em
FSFS, isto no se aplica a voc. E para aqueles que estiverem usando o Subversion 1.4 com Berkeley
DB 4.4 ou superior, vocs deveriam perceber que o Subversion se tornou muito mais resistente
nesses tipos de situaes. Mas, problemas com repositrios Berkeley DB ainda podem ocorrer, e um
administrador precisa saber como agir seguramente nessas circunstncias.
Para proteger os dados em seu repositrio, o Berkeley DB usa um mecanismo de travas. Este
mecanismo assegura que pores da base de dados no sejam modificadas simultaneamente por
mltiplos acessos base de dados, e que cada processo veja os dados no estado correto quando esses
dados estiverem sendo lidos da base de dados. Quando um processo precisar modificar algo na base
de dados, ele primeiro procura pela existncia de uma trava nos dados cuja modificao se destina. Se
os dados no estiverem travados, o processo trava os dados, faz as modificaes pretendidas, e ento
destrava os dados. Outros processos so forados a esperar at que uma trava seja removida antes
de conseguir permisso para acessar quela seo da base de dados. (Isto no tem nada a ver com
as travas que voc, como usurio, pode criar em arquivos versionados dentro do repositrio; tentamos
esclarecer a confuso causada por essa coliso de terminologias em Os trs significados de trava.)
Ao longo de sua utilizao do repositrio do Subversion, erros fatais ou interrupes podem evitar que
um processo tenha a oportunidade de remover travas que tenham criado na base de dados. O resultado
que o sistema da base de dados pode ficar encravado. Quando isto acontece, quaisquer tentativas
de se acessar o repositrio pode resultar em travamentos indefinidamente (como cada novo ancestral
esteja aguardando por uma trava para prosseguiro que no algo que estar para acontecer).
Ao invs disso, use a seguinte receita para tentar desencravar seu repositrio:
2. Torne-se o usurio que possui e gerencia o repositrio. Isto importante, j que realizar a
recuperao de um repositrio com o usurio errado pode detonar as permisses dos arquivos do
repositrio de tal forma que seu repositrio ficar inacessvel mesmo depois de desencravado.
3. Execute o comando svnadmin recover /path/to/repos. Voc deveria ver uma sada como esta:
8
P.ex.: disco rgido + grande eletromagnetismo = desastre.
121
Administrao do Repositrio
Recovery completed.
The latest repos revision is 19.
Este procedimento vai corrigir praticamente todos os casos de problemas dessa natureza do repositrio.
Certifique-se de executar este comando como o usurio que possui e gerencia a base de dados, no
apenas como usurio root. Parte do processo de recuperao pode envolver recriar do zero vrios
arquivos da base de dados do repositrio (regies de memria compartilhada, por exemplo). Fazer esta
recuperao como usurio root vai criar estes arquivos como se tivessem pertencido ao root, o que
quer dizer que mesmo depois de voc restaurar a conectividade de seu repositrio, usurios normais
estaro impossibilitados de acess-lo.
Se o procedimento anterior, por alguma razo, no tiver xito ao desencravar o repositrio, voc deveria
fazer duas coisas. Primeiro, deixe seu diretrio problemtico de lado (talvez renomeando-o para algo
como repos.BROKEN) e ento restaure o ltimo backup que voc tiver dele. Depois, envie um e-
mail lista de usurios do Subversion (em <users@subversion.tigris.org>) descrevendo seu
problema em detalhes. A integridade de dados uma caracterstica de altssima prioridade para os
desenvolvedores do Subversion.
O Subversion oferece alguma funcionalidade para lidar com fluxos de dados de despejo do repositrio.
Um fluxo de despejo do repositrio (frequentemente referenciado como um arquivo dumpfile quando
armazenado como um arquivo no disco) um formato de arquivo plano, portvel, que descreve as
vrias revises em seu repositrioo que foi modificado, por quem, quando, e por a vai. Este fluxo
de despejo o principal mecanismo usado para administrao do histrico versionadopor completo
ou em parte, com ou sem modificaesentre repositrios. E o Subversion fornece as ferramentas
necessrias para criar e carregar esses fluxos de despejoos subcomandos svnadmin dump e
svnadmin load subcommands, respectivamente.
Ainda que o formato do arquivo de despejo do Subversion contenha partes legveis por
humanos e que tenham uma estrutura de arquivo familiar (ele utiliza o formato da RFC-822,
o mesmo tipo de formato usado na maioria das mensagens de e-mail), ele no um
formato de arquivo de texto plano. Mas sim, um formato de arquivo binrio, altamente
sensvel a intromisses. Por exemplo, muitos editores de texto iro corromper o arquivo
automaticamente ao converter o formato das quebras de linha.
H muitas razes para realizar despejo e carga de dados do repositrio Subversion. Na vida pregressa
do Subversion, a razo mais comum para isso era a prpria evoluo do Subversion. Conforme o
Subversion foi se tornando mais maduro, houve vezes em que as modificaes feitas no esquema
da base de dados levou a problemas de compatibilidade com verses anteriores do repositrio, ento
os usurios tinham que despejar os dados de seus repositrios com a verso antiga do Subversion,
e carreg-los para dentro de um repositrio recm criado com a nova verso do Subversion. Agora,
estes tipos de modificaes de esquema no tm ocorrido desde a verso 1.0 do Subversion, e os
desenvolvedores do Subversion prometem no forar os usurios a ter de despejar seus repositrios
para fazer atualizaes para verses menores (como da verso 1.3 para a 1.4) do Subversion. Mas
ainda h outros motivos para realizar despejo e carga, incluindo re-implementao de um repositrio
Berkeley DB em um novo sistema operacional ou outra arquitatura de CPU, troca de repositrios
baseados em Berkeley DB para FSFS, ou (como veremos em Filtrando o Histrico do Repositrio)
remover completamente dados do histrico de repositrio.
122
Administrao do Repositrio
Qualquer que seja a razo para migrar o histrico do repositrio, usar os subcomandos svnadmin
dump e svnadmin load bem simples. O svnadmin dump vai gerar na sada um intervalo de revises
do repositrio no formato especfico de despejo do sistema de arquivos do Subversion. O formato de
despejo exibido no fluxo da sada padro, enquanto que mensagens informativas so exibidas na
sada de erro padro. Isto lhe permite redirecionar o fluxo de sada para um arquivo ao mesmo tempo
em que visualiza o estado da sada em sua janela de terminal. Por exemplo:
Ao final do processo, voc ter um nico arquivo (dumpfile, no exemplo anterior) que contm todos
os dados armazenados em seu repositrio no intervalo de revises requisitado. Note que o svnadmin
dump est lendo as rvores de revises do repositrio tal como qualquer outro processo leitor (como
o svn checkout, por exemplo), ento, seguro executar este comando a qualquer momento.
O outro subcomando do par, o svnadmin load, analisa o fluxo de entrada padro e toma como entrada
o arquivo no formato de despejo do Subversion, e efetivamente re-executa aquelas revises nele
presentes. O comando tambm prov informao de feedback, desta vez usando o fluxo de sada
padro:
------- Committed new rev 25 (loaded from original rev 25) >>>
------- Committed new rev 26 (loaded from original rev 26) >>>
O resultado de uma carga so novas revises adicionadas ao ao repositrioa mesma coisa que
se voc tivesse submetido as modificaes diretamente no repositrio com um cliente normal do
Subversion. E tal como em uma operao de commit, voc pode usar scripts de hook para executar
123
Administrao do Repositrio
aes antes e depois de cada uma das submisses realizadas durante o processo de carga. ] Passando
as opes --use-pre-commit-hook e --use-post-commit-hook para o svnadmin load, voc
pode instruir o Subversion a executar os scripts de hook pre-commit e post-commit, respectivamente,
para cada uma das revises carregadas. Voc pode usar essas opes para, por exemplo, para
assegurar que as revises carregadas passem pelos mesmos passos de validao que as submisses
normais tenham passado. claro, voc deveria usar estas opes com cuidadose seus scripts post-
commit enviam e-mails para uma lista de discusso a cada novo commit, voc no deveria querer
disparar centenas ou milhares de e-mails para cada commit em sequncia para essa lista! Voc pode
ler mais sobre o uso de scripts de hook no Subversion em Implementando Ganchos de Repositrio.
Note que como o svnadmin usa a entrada e a sada padro para os despejos e cargas do repositrio,
especialmente aquelas pessoas que se acharem um pouco mais danadas, podem tentar fazer coisas
como isto (quem sabe usando verses diferentes do svnadmin em cada um dos lados do duto):
Por padro, o arquivo de despejo ser um tanto grandemuito maior que o repositrio em si. Isto
porque, cada uma das verses de cada um dos arquivos est representada com seu contedo textual
completo no arquivo de despejo. Este um comportamente mais rpido e mais simples, e bom se voc
estiver canalizando os dados de despejo diretamente para outro processo (tal como um programa de
compactao, programa de filtragem, ou em um processo de carga). Mas se voc estiver criando um
arquivo de despejo para gravar numa mdia de armazenamento de longo perodo, voc pode querer
economizar espao em disco usando a opo --deltas. Com esta opo, revises sucessivas dos
arquivos sero geradas na sada como compactadas diferenas binrias dos arquivostal como as
revises dos arquivos so armazenadas no repositrio. Esta opo mais lenta, mas resulta em um
arquivo de despejo muito prximo do tamanho do repositrio original.
Ns mencionamos anteriormente que o svnadmin dump gera sadas com intervalos de revises. Use
a opo --revision (-r) para especificar uma nica reviso a ser despejada, ou um intervalo de
revises. Se voc omitir esta opo, todas as revises existentes no repositrio sero despejadas.
Como o Subversion despeja cada uma das novas revises, ele gera na sada apenas a informao
suficiente para permitir que um carregador futuro possa recriar uma dada reviso com base na reviso
anterior. Em outras palavras, para qualquer dada reviso no arquivo de despejo, apenas os tens que
tiverem sido modificados naquela reviso iro aparecer no arquivo de despejo. A nica exceo a esta
regra a primeira reviso que despejada com o atual comando svnadmin dump.
Por padro, o Subversion no ir expressar a primeira reviso despejada como meras diferenas
aplicadas reviso anterior. Por um lado, porque de fato no h reviso anterior no arquivo de despejo!
E tambm, porque o Subversion no sabe o estado do repositrio dentro do qual os dados sero
carregados (se que eles vo ser carregados). Para garantir que a sada de cada execuo do
svnadmin dump seja auto-suficiente, a primeira reviso despejada , por padro, uma representao
completa de cada diretrio, arquivo, e propriedades naquela reviso do repositrio.
Entretanto, voc pode modificar este comportamento padro. Se voc adicionar a opo --
incremental ao efetuar o despejo de seu repositrio, o svnadmin ir comparar a primeira reviso
despejada com a reviso anterior no repositrio, da mesma forma que trata de cada reviso que
despejada. Ele ento vai gerar a sada exatamente como faz com o resto das revises no intervalo de
despejomencionando apenas as modificaes que ocorreram naquela reviso. A vantagem disto
que voc pode criar diversos arquivos de despejo pequenos que podem ser carregados seguidamente,
ao invs de apenas um grande arquivo, como:
124
Administrao do Repositrio
Esses arquivos de despejo poderiam ser carregados para dentro de um novo repositrio com a seguinte
sequncia de comandos:
Outro truque efetivo que voc pode executar com esta opo --incremental envolve anexar um
novo intervalo de revises despejadas para um arquivo de despejo existente. Por exemplo, voc pode
ter um script de hook post-commit que simplesmente anexe o despejo do repositrio de uma nica
reviso que senha disparado o script. Ou voc pode ter um script que seja executado diariamente para
anexar dados de um arquivo de despejo para todas as revises que forem adicionadas ao repositrio
desde a ltimva ver que o script foi executado. Usado desta forma, o svnadmin dump pode ser uma
forma de realizar backups de modificaes de seu repositrio tempestivamente em caso de uma pane
no sistema ou de algum outro evento catastrfico.
O formato de despejo tambm pode ser usado para mesclar o contedo de diversos repositrios
diferentes para um nico repositrio. Usando a opo --parent-dir de svnadmin load, voc pode
especificar um novo diretrio virtual para o processo de carga. Isso significa que se voc tiver arquivos
de despejo para trs repositrios, digamos calc-dumpfile, cal-dumpfile, e ss-dumpfile, voc
pode primeiro criar um novo repositrio para armazenar a todos eles:
Ento, criar novos repositrios no repositrio que iro encapsular o contedo de cada um dos trs
repositrios anteriores:
Por fim, carregue os arquivos de despejo individuais para suas respectivas localizaes dentro do novo
repositrio:
125
Administrao do Repositrio
repositrio CVS de tal forma que seu contedo possa ser copiado para dentro de um repositrio do
Subversion.
Como descrevemos em Migrando Dados do Repositrio Para Outro Local, o repositrio do Subversion
uma representao legvel por humanos das alteraes que voc tem feito em seus dados
versionados ao longo do tempo. Voc usa o comando svnadmin dump para gerar dados de despejo,
e o svnadmin load para popular um novo repositrio com eles (veja Migrando Dados do Repositrio
Para Outro Local). A grande coisa sobre o aspecto da legibilidade do formato de despejo que, se
voc no tiver cuidado sobre isso, voc pode manualmente inspecion-lo e modific-lo. claro, o
lado negativo que se voc tiver trs anos de atividade no repositrio encapsulados no que pode ser
um arquivo de despejo muito grande, isso levaria muito, muito tempo para inspecion-lo e modific-
lo manualmente.
a que entra o comando svndumpfilter. Este programa atua como um filtro baseado em caminhos
para fluxos de despejo do repositrio. Simplesmhete lhe d ou uma lista de caminhos que voc quer
manter, ou uma lista de caminhos que voc no quer manter, e ento canalize seu fluxo de dados de
despejo do repositrio para este filtro. O resultado ser um fluxo de dados de despejo que contenha
apenas os caminhos versionados que voc requisitou (explicita ou implicitamente).
Vamos dar uma olhada em um exemplo realista de como voc poderia usar este programa. Discutimos
mais sobre o processo de decidir como escolher a estrutura para os dados de seu repositrio (veja
Planejando a Organizao do Repositrio)utilizando um repositrio por projeto ou combinando
eles, arranjando coisas dentro de seu repositrio, e da por diante. Mas algumas vezes depois que
novas revises comeam a ocorrer, voc reconsidera a estrutura de seu repositrio e gostaria de fazer
algumas modificaes. Uma modificao comum a deciso de mover mltiplos projetos que estejam
compartilhando um nico repositrio em repositrios separados para cada projeto.
Nosso repositrio imaginrio contm trs projetos: calc, calendar, e spreadsheet. Eles tm
convivido lado-a-lado em uma estrutura como esta:
/
calc/
trunk/
branches/
tags/
calendar/
trunk/
branches/
tags/
9
Que precisamente a razo para usar um sistema de controle de verso, certo?
10
Conscientemente, a remoo cuidadosa de certas pores de dados versionados necessria atualmente em alguns casos
de uso reais. Isso porque o recurso de obliterao tenha sido um dos recursos mais requisitados para o Subversion, e um
dos quais os desenvolvedores do Subversion esperam disponibilizar em breve.
126
Administrao do Repositrio
spreadsheet/
trunk/
branches/
tags/
Para pr estes trs projetos em seus prprios repositrios, primeiro despejamos todo o repositrio:
Depois, passamos o arquivo de despejo por um filtro, a cada vez incluindo apenas um de nossos
diretrios de alto nvel, e resultando em trs novos arquivos de despejo:
Neste ponto, ns tomamos uma deciso. Cada um de seus arquivos de despejo vai criar um repositrio
vlido, mas ainda preservando os caminhos exatamente como eram no repositrio original. Isto quer
dizer que mesmo que voc tivesse um repositrio apenas para seu projeto calc, este repositrio ainda
assim teria um diretrio de alto nvel chamado calc. Se voc quiser que seus diretrios trunk, tags,
e branches fiquem na raiz de seu repositrio, voc poderia querer editar seus arquivos de despejo,
ajustando os cabealhos Node-path e Node-copyfrom-path para que no tenham mais o calc/
como parte do caminho. Tambm, voc vai querer remover a seo de dados de despejo que cria o
diretrio calc. Ela ser algo parecido com:
Node-path: calc
Node-action: add
Node-kind: dir
Content-length: 0
Tudo o que resta agora criar seus trs novos repositrios, e carregar cada arquivo de despejo para
dentro do repositrio correto:
127
Administrao do Repositrio
Ambos os subcomandos do svndumpfilter aceitam opes para decidir como lidar com revises
vazias. Se uma dada reviso contiver apenas modificaes em caminhos que foram filtrados, ento
as revises que no foram filtradas podem ser vistas como desinteressantes ou mesmo indesejadas.
Assim, para deixar que o usurio controle o que fazer com tais revises, o svndumpfilter dispe das
seguintes opes de linhas de comando:
--drop-empty-revs
Nunca gera revises vaziasapenas as omite.
--renumber-revs
Se as revises vazias forem removidas (usando a opo --drop-empty-revs), modifica os
nmeros de reviso das revises remanescentes de tal forma que no fiquem partes faltando na
sequncia numrica.
--preserve-revprops
Se as revises vazias no forem removidas, preserva as propriedades de reviso (mensagem de
log, autor, data, propriedades especficas, etc.) para essas revises vazias. Do contrrio, revises
vazias sempre iro conter a datao original, e uma mensagem de log gerada que indica que aquela
reviso foi esvaziada pelo svndumpfilter.
Ainda que o svndumpfilter possa ser bem til e economizar bastamte tempo, infelizmente ele tambm
pode representar uma poro de pegadinha. Primeiro, este utilitrio altamente sensvel semntica
dos caminhos. Preste ateno se os caminhos em seu arquivo de despejo esto especificados com ou
sem uma barra final. Voc vai querer checar os cabealhos Node-path e Node-copyfrom-path.
Node-path: spreadsheet/Makefile
Se os caminhos tiverem uma barra final, voc deveria incluir barras nos caminhos que passar para
o svndumpfilter include e svndumpfilter exclude (e se a barra no existir, voc no deve inclu-
la). Alm disso, se seu arquivo de despejo, por alguma razo, estiver usando essas barras de forma
11
inconsistente, voc provavelmente deveria normalizar estes caminhos de forma a manter sempre,
ou remover sempre, o sinal de barra final.
E tambm, caminhos copiados podem lhe dar algum problema. O Subversion suporta operaes de
cpia no repositrio, sendo que um novo caminho criado copiando-se algum caminho j existente.
possvel que em algum ponto do ciclo de vida de seu repositrio, voc pode ter copiado um arquivo
ou diretrio a partir de algum local que o svndumpfilter desconsidere (um local excludo) para um
local levado em conta (um local includo). Para fazer com que os dados despejados sejam auto-
suficientes, o svndumpfilter ainda precisa mostrar a adio do novo caminhoincluindo o contedo
de alguns arquivos criados pela cpiae que no signifiquem que a adio foi uma cpia a partir
de uma origem que no existia em seu fluxo de dados de despejo filtrados. Mas como o formato de
despejo do repositrio do Subversion apenas contm o que foi modificado em cada uma das revises,
o contedo de origem de sua cpia pode no estar prontamente disponvel. Se voc suspeitar que
11
Ainda que o svnadmin dump obedea a uma poltica de uso consistente de uso desse sinal de barraque nunca inclu-la
outros programas que geram dados de despejo podem no ter a mesma consistncia.
128
Administrao do Repositrio
voc tem cpias desse tipo em seu repositrio, voc pode querer reconsiderar suas configuraes de
caminhos includos/excludos, talvez incluindo os caminhos usados como origens de suas operaes
de cpia problemticas tambm.
Por fim, o svndumpfilter realiza a filtragem baseada em caminhos de forma quase que literal. Se
voc est tentando copiar o histrico de um projeto hospedado sob trunk/my-project e mov-
lo para dentro de um repositrio prprio, voc deveria, obviamente, usar o comando svndumpfilter
include para incluir todas as modificaes dentro de trunk/my-project. Mas o arquivo de despejo
resultando no faz presunes sobre o repositrio no qual voc planeja carregar estes dados.
Especificamente, os dados despejados podem comear com o nmero de reviso no qual foram
adicionados no diretrio trunk/my-project, mas ainda no vo conter diretivas que poderiam criar
o diretrio trunk em si (j que o trunk no corresponde ao filtro de incluso). Voc precisar ter
certeza de que quaisquer diretrios os quais os novos fluxos de despejo esperam existir atualmente
existam no repositrio destino antes de tentar carregar o fluxo para dentro desse repositrio.
Replicao do Repositrio
H diversos cenrios nos quais um bocado til ter um repositrio do Subversion cujo histrico
de verses seja exatamente o mesmo que de algum outro repositrio. Talvez o mais bvio seja a
manuteno de um simples repositrio de backup, a ser usado quando o repositrio primrio estiver
inacessvel devido uma falha de hardware, problema de rede, ou qualquer outro inconveniente. Outros
cenrios incluem implantar repositrios de espelho para distribuir o peso da carga do Subversion por
mltiplos servidores, uso como um mecanismo para atualizao fcil, e assim por diante.
Desde a verso 1.4, o Subversion dispe de um programa para gerenciamento de cenrios como
esseso svnsync. Essencialmente o svnsync trabalha solicitando ao servidor Subversion que repita
revises, uma por vez. E ento usa informaes daquela reviso para imitar uma operao de commit
semelhante no outro repositrio. Nenhum dos repositrios precisa ser acessvel localmente mquina
na qual o svnsync esteja executandoseus parmetros so URLs de repositrio, e ele faz todo o seu
trabalho com base nas interfaces de acesso ao repositrio (RA) do Subversion. Tudo o que o comando
precisa de acesso de leitura no repositrio de origem e de acesso leitura/escrita no repositrio de
destino.
Assumindo que voc j tenha um repositrio de origem que gostaria de espelhar, a prxima coisa
que voc precisa de um repositrio de destino vazio que ir servir de espelho. Este repositrio de
destino pode at mesmo usar sistemas de armazenamento baseado em arquivo (veja Escolhendo
uma Base de Dados), mas no deve ter nenhum histrico de verso dentro de si. O protocolo com o
qual o svnsync comunica informaes de reviso altamente sensvel a diferenas entre histricos
versionados contidos nos repositrios de origem e destino. Por este motivo, ainda que o svnsync
12
no precise que o servidor de destino seja somente-leitura, permitir que o histrico de revises no
repositrio de destino sofra alguma mudana devido a qualquer outro mecanismo que no o processo
de espelhamento uma receita para um desastre.
Nunca modifique um repositrio espelho de maneira a fazer com que seu histrico
de verses difira daquele do repositrio o qual espelhado. As nicas submisses e
modificaes de propriedades de reviso que devem ocorrer no repositrio espelho devem
ser feitas exclusivamente pela ferramenta svnsync.
Outro requisito para o repositrio de destino que o processo svnsync tenha permisso de modificar
certas propriedades de reviso. O svnsync armazena suas informaes gerenciais em propriedades
de reviso especiais na reviso 0 do repositrio de destino. Como o svnsync opera de dentro do
framework do sistema de scripts de hook daquele repositrio, o estado padro do repositrio (que
12
De fato, ele no poderia ser verdadeiramente somente-leitura, ou o prprio svnsync no teria que demandar uma dura tarefa
de copiar o histrico de revises para si.
129
Administrao do Repositrio
uma boa idia implementar medidas de autorizao que permitam que o processo de
rplica de seu repositrio execute suas tarefas ao mesmo tempo em que impede outros
usurios de modificar o contedo do repositrio espelho como um todo.
Vamos avanar ao uso do svnsync em um cenrio tpico de espelhamento. Vamos apimentar este
discurso com recomendaes prticas as quais voc tem liberdade para desconsiderar se elas no
forem necessrias ou no se aplicarem a seu ambiente.
Como um servio aos grandes desenvolvedores de nosso sistema de controle de verso favorito, vamos
espelhar o repositrio do cdigo-fonte do Subversion e disponibilizar este espelho publicamente na
Internet, hospedado em uma mquina diferente daquela onde se encontra o cdigo-fonte original. Este
host remoto tem uma configurao global que permite que usurios annimos leiam o contedo dos
repositrios no host, mas necessita que os usurios se autentiquem para submeter alteraes nesses
repositrios. (Por favor, perdoe-nos por no mencionarmos os detalhes da configurao do servidor do
Subversion neste momentoalguns deles so plenamente abordados em Captulo 6, Configurao do
Servidor.) E apenas para deixar este exemplo ainda mais interessante, vamos conduzir o processo de
replicao tambm para uma terceira mquina, a qual atualmente estamos utilizando efetivamente.
Primeiro, vamos criar o repositrio que ser o nosso espelho. Este e alguns dos prximos passos
seguintes necessitam de acesso ao shell da mquina na qual o repositrio ir ficar. Uma vez que o
repositrios esteja todo configurado, porm, no precisaremos mais mexer diretamente nele de novo.
$ ssh admin@svn.example.com \
"svnadmin create /path/to/repositories/svn-mirror"
admin@svn.example.com's password: ********
$
Neste ponto, temos nosso repositrios, e pela configurao de nosso servidor, esse repositrio agora
est ativo na Internet. Agora, como ns no queremos que nada mais modifique o repositrio alm de
nosso processo replicador, precisamos de alguma forma distinguir esse processo de outros aspirantes
a submissores de modificaes. Para isso, vamos usar um nome de usurio dedicado para nosso
processo. Apenas as submisses e modificaes de propriedades de reviso executadas pelo nome
de usurio especial syncuser sero permitidas.
Vamos usar o sistema de scripts de hook do repositrio para permitir que o processo de replicao faa
tudo o que precisa fazer, e garantir que faa to somente essas coisas. Fazemos isso imeplementando
dois dos ganchos de eventos do repositriopre-revprop-change e start-commit. Nosso script pre-
revprop-change encontrado em Exemplo 5.2, Script de hook pre-revprop-change para operao
de espelhamento, e basicamente verifica se o usurio est tentando realizar a modificao de
propriedade o nosso usurio syncuser. Se o for, a modificao efetivada; seno, ser proibida.
#!/bin/sh
USER="$3"
echo "Only the syncuser user may change revision properties" >&2
exit 1
130
Administrao do Repositrio
Isso cobre as modificaes de propriedades. Agora tambm precisamos garantir que apenas o usurio
syncuser tenha permisso de submeter novas revises ao repositrio. Fazemos isso usando um script
start-commit parecido com aquele em Exemplo 5.3, Script de hook start-commit para operao de
espelhamento.
#!/bin/sh
USER="$2"
echo "Only the syncuser user may commit new revisions" >&2
exit 1
Depois de instalar nossos scripts de hook e de garantir que eles so executveis pelo usurio do
Subversion, ns terminamos com a configurao do repositrio espelho. Agora, vamos entrar na
operao de espelhamento em si.
A primeira coisa que precisamos fazer com o svnsync registrar em nosso repositrio destino o fato de
que ele ser um espelho de um outro repositrio origem. Fazemos isso usando subcomando svnsync
initialize. Note que os vrios subcomandos do svnsync dispem das mesmas diversas opes
relativas a autenticao que o svn possui: --username, --password, --non-interactive, --
config-dir, e --no-auth-cache.
You should not commit to, or make revision property changes in,
the destination repository by any method other than 'svnsync'.
In other words, the destination repository should be a read-only
mirror of the source repository.
Valid options:
--non-interactive : do no interactive prompting
--no-auth-cache : do not cache authentication tokens
--username arg : specify a username ARG
--password arg : specify a password ARG
--config-dir arg : read user configuration files from directory ARG
Nosso repositrio destino agora vai lembrar que um espelho de um repositrio pblico do cdigo-
fonte do Subversion. Perceba que informamos um nome de usurio e uma senha como argumentos
para o svnsynco que requerido pelo script pre-revprop-change de nosso repositrio espelho.
131
Administrao do Repositrio
As URLs informadas para o svnsync devem apontar para os diretrios razes dos
repositrios de destino e de origem, respectivamente. A ferramenta no manipula
espelhamento de sub-rvores de um repositrio.
A verso inicial do svnsync (no Subversion 1.4) tem uma pequena deficinciaos valores
informados para as opes de linha de comando --username e --password so usado
para autenticao em ambos repositrios de origem e de destino. Obviamente, no h
garantia de que as credenciais do usurio sejam as mesmas nesses dois locais. No caso de
elas no serem as mesmas, os usurios que estiverem executando o svnsync em modo
no-interativo (com a opo --non-interactive) podem ter probemas.
E agora vem a parte divertida. Com um nico subcomando, vamos pedir para o svnsync copiar
13
todas as revises que ainda no tiverem sido espelhadas do repositrio de origem para o destino.
O subcomando svnsync synchronize ir checar as propriedades de reviso especiais previamente
armazenadas no repositrio destino, e verificar qual repositrios ele est espelhando e que a reviso
mais recentemente espelhada foi a reviso 0. Ento ele ir consultar o repositrio de origem e
determinar qual foi a ltima reviso naquele repositrio. Finalmente, o comando solicita ao resvidor do
repositrio de origem que comece a re-executar todas as revises entre 0 e a ltima reviso. To logo
o svnsync obtenha a resposta resultante do servidor do repositrio de origem, ele comea a repassar
essas revises para o servidor do repositrio de destino como novas operaes de commit.
Interessante notar aqui que para cada uma das revises espelhadas, h primeiro uma submisso da
reviso para o repositrio de destino, seguida ento por uma mudana de propriedade. Isso se deve
porque a operao de commit inicial executada pelo (e atribuda ao) usurio syncuser, e fica datada
com o horrio da criao da reviso. E tambm, as interfaces de suporte para acesso a repositrios
do Subversion no dispem de um mecanismo arbitrrio para propriedades de reviso como parte
de uma operao de commit. Assim, o svnsync prossegue com uma srie imediata de modificaes
de propriedades que copiam todas as propriedades de reviso encontradas para aquela reviso no
repositrio de origem para o repositrio de destino. Isso tambm tem o efeito de corrigir o autor e o
registro de data da reviso que passam a corresponder com quelas do repositrio de origem.
Algo que tambm deve-se notar que o svnsync realiza registros cuidadosos que lhe permitem
que possam ser interrompidos e reiniciados sem prejuzo para a integridade dos dados espelhados.
13
Esteja ciente de que ainda que levem alguns poucos segundos para que um leitor mediano analise este pargrafo e a sada
ilustrativa que o segue, o tempo total necessrio para concluir uma operao de espelhamento , como dissemos, um bocado
mais demorada.
132
Administrao do Repositrio
Se ocorrer um problema com a conexo de rede enquanto um repositrio estiver sendo espelhado,
simplesmente repita o comando svnsync synchronize e ele ir continuar tranquilamente sua operao
exatamente de onde parou. De fato, tambm se ocorrerem novas revises no repositrio de origem,
isto tambm exatamente o que voc vai fazer para manter seus dados corretamente sincronizados.
Tambm, ainda que de certa forma no represente um lugar comum, o svnsync consegue espelhar
graciosamente os repositrios nos quais o usurio com o qual se autentica s possui acesso de leitura.
Ele apenas copia os bits do repositrio aos quais tem permisso de ver. Obviamente um espelho desse
tipo no to til como uma soluo de backup.
No que diz respeito interao do usurio com os repositrios e os espelhos, possvel ter uma nica
cpia de trabalho que interaja com ambos, mas voc vai ter que mostrar habilidade e resolver algumas
questes para fazer isso. Primeiro, voc precisa garantir que tanto o repositrio primrio quanto o
espelho tenham o mesmo UUID de repositrio (o que no o que acontece por padro). Voc pode
configurar o UUID do repositrio carregando uma parte arquivo de despejo que contenha o UUID do
repositrio primrio, algo tipo:
UUID: 65390229-12b7-0310-b90b-f21a5aa7ec8e
EOF
$
Agora que os dois repositrios possuem o mesmo UUID, voc pode usar um svn switch --relocate
para apontar sua cpia de trabalho para onde quer que estejam os repositrios com que voc quer
trabalhar, um procedimento que descrito em svn switch. Porm, h um grande risco em potencial, que
se os repositrios primrio e de espelho no estiverem adequadamente sincronizados, uma cpia
atualizada, e que aponte para o repositrio primrio ir, se realozada para apontar para um espelho
desatualizado, se tornar confusa sobre a aparente perda de revises que de fato esto plenamente
presentes, e lanar erros reportando isso. Se isto ocorrer, voc pode realocar sua cpia de trabalho
133
Administrao do Repositrio
de volta para o repositrio primrio e ento ou esperar que seu repositrio espelho esteja atualizado,
ou retroceder sua cpia de trabalho para uma reviso que voc sabe estar presente no repositrio
sincronizado e ento tentar a realocao novamente.
Por ltimo, esteja ciente de que a replicao baseada em revises oferecida pelo svnsync no nada
mais do que issoreplicao de revises. Ela no inclui coisas como implementaes de scripts de
hook, dados de configurao de repositrio ou de servidor, transaes no submetidas, ou informaes
sobre travas de usurio ou caminhos de repositrio. Apenas informaes que so carregadas pelo
formato de arquivo de despejo do Subversion esto disponveis para replicao.
Backup de Repositrio
Apesar dos inmeros avanos na tecnologia desde o nascimento do computador moderno, uma coisa
infelizmente permanece to verdadeiramente clara e cristalina como nuncaalgumas vezes, as coisas
do muito, muito errado. Cortes de energia, problemas em conexes de rede, memria RAM corrompida
e falhas em discos rgidos so uma mostra do mal que o destino cruel reserva mesmo o mais consciente
dos administradores. E ento chegamos a este tpico muitssimo importantecomo fazer backups dos
dados de seu repositrio.
No que diz respeito a backups completo, uma abordagem que parece ser a mais consciente, mas a
menos que voc desabilite todos os demais acessos a seu repositrio, fazer simplesmente uma cpia
recursiva do diretrio algo que pode incorrer no risco de se gerar um backup defeituoso. No caso do
Berkeley DB, a documentao descreve uma certa ordem na qual os arquivos da base de dados podem
ser copiados para garantir uma cpia de segurana vlida. Uma ordenao similar existe para dados
FSFS. Mas voc mesmo no precisa implementar tais algoritmos, pois a equipe de desenvolvimento
do Subversion j fez isso para voc. O comando svnadmin hotcopy cuida de todas as mincias
envolvidas em se fazer um backup a quente de seu repositrio. E sua invocao to trivial quanto os
comandos cp dos Unix ou o copy em sistemas Windows:
O backup resultante um repositrio do Subversion completamente funcional, e capaz de ser tido como
um substituto para seu repositrio ativo para o caso de que ocorra algo terrivelmente errado.
Ao fazer cpias de um repositrio Berkeley DB, voc tambm pode dizer para o svnadmin hotcopy
para eliminar quaisquer arquivos de log no usados do Berkeley DB (veja Remover completamente
arquivos de log no usados do Berkeley DB) do repositrio original enquanto a cpia executada.
Simplemente informe a opo --clean-logs na linha de comando.
Um ferramental adicional para este comando tambm est disponvel. O diretrio tools/backup/,
presente nos fontes disponveis do Subversion, contm um script hot-backup.py. Este script adiciona
um pouco de gerncia por sobre o svnadmin hotcopy, permitindo que voc mantenha apenas um
nmero de backups mais recentes configurado para cada repositrio. Esse script ir automaticamente
gerenciar os nomes dos diretrios do repositrio no backup para evitar colises de nomes com backups
anteriores, e tambm ir rotacionar os backups mais antigos, removendo-os de forma que apenas os
mais recentes permaneam. Mesmo se voc j tiver um backup incremental, voc pode querer executar
este programa regularmente. Por exemplo, voc pode considerar usar o script hot-backup.py a partir
de um agendador de tarefas (tal como o cron em sistemas Unix) o que far com que ele seja executado
134
Administrao do Repositrio
diariamente (ou com qualquer que seja a granularidade de tempo que voc considere adequadamente
segura).
Alguns administradores utilizam mecanismos de backup prontos para gerar e armazenar dados
despejados do repositrio. Em Migrando Dados do Repositrio Para Outro Local, descrevemos como
usar o comando svnadmin dump --incremental para executar um backup incremental de uma dada
reviso ou intervalo de revises. E, claro, h a variante para backup completo deste comando,
apenas omitindo-se a opo --incremental. Esses mtodos tm o seu valor, j que o formato de
suas informaes so mantidas flexvelum formato que no depende de nenhuma plataforma em
particular, nenhum tipo de sistema de arquivos, ou de nenhuma verso especfica do Subversion nem
do Berkeley DB. Mas essa flexibilidade tem um custo, que o longo tempo que a recuperao de tais
dados pode demorartanto mais longo quanto mais revises forem submetidas ao seu repositrio. E
tambm, como o caso com alguns dos diversos mtodos de backup, mudanas em propriedades de
reviso feitas em revises que j estiverem em um backup no sero obtidas numa gerao de arquivo
de despejo incremental e no sobrescrevente. Por essas razes, somos contra a dependncia de uma
nica abordagem de backup baseada em arquivos de despejo.
Como voc pode ver, cada um dos vrios tipos de backup e mtodos tem suas vantagens e
desvantagens. A mais fcil mesmo o backup a quente completo, o que ir sempre resultar em
uma rplica perfeitamente funcional de seu repositrio. Se algo de muito ruim acontecer a seu
repositrio de produo, voc pode restaur-lo a partir do backup com um simples comando de cpia
recursiva de diretrio. Infelizmente, se voc estiver mantendo mltiplos backups de seu repositrio,
todas essas cpias iro comer tanto espao em disco quanto seu prprio repositrio de produo.
Backups incrementais, diferentemente, tendem a ser mais rpidos para se gerar e menores para
se armazenar. Mas o processo de restaurao pode ser doloroso, frequentemente envolvendo a
aplicao de mltiplos backups incrementais. Outros mtodos possuem suas prprias peculiaridades.
Administradores precisam encontrar o ponto ideal entre o custo de se gerar o backup e o custo de
recuper-lo.
Falando de uma forma geral, apenas aqueles verdadeiramente paranicos precisam criar backups
de todo o seu repositrio, digamos, a cada operao de commit. No entanto, assumindo que um
dado repositrio tenha algum mecanismo de redundncia implementado e com uma granularidade
relativamente fina (como e-mails de notificao por submisso ou despejos incrementais), um backup
a quente da base de dados pode ser algo que um administrador de repositrio deveria querer incluir
como parte de um backup dirio global do sistema. Os dados so seusento proteja-os da forma
que achar melhor.
135
Administrao do Repositrio
exemplo, fazem backup do repositrio do cdigo-fonte do Subversion uma vez por dia usando o script
hot-backup.py e com uma sincronizao offise usando rsync para os backups completos; mantm
mltiplas cpias de segurana arquivadas de todos os e-mails de notificao das operaes de commit
e de mudanas de propriedades; e possuem espelhos do repositrio mantidos por diversos voluntrios
usando svnsync. Sua soluo pode ser similar, mas deveria ser ajustada s suas necessidades e
considerar o balando adequado entre convenincia e parania. E o que que que seja que voc decida
fazer, valide seus backups de tempos em temposde que serve carregar um estepe furado? Por mais
15
que nada disso salva seu hardware da rgida espada do destino, backups devem certamente ajud-
lo a se recuperar em momentos difceis.
Sumrio
At agora voc deve ter tido um entendimento de como criar, configurar e manter repositrios
Subversion. Ns o introduzimos a vrias ferramentas que o ajudaro nessa tarefa. Ao longo deste
captulo, ns mostramos obstculos comuns e sugestes para evit-los.
Tudo que falta para voc decidir que tipo de informao armazenar no seu repositrio, e finalmente,
como deix-lo disponvel na rede. O prximo captulo todo sobre rede.
15
Voc sabea representao figurativa para todos os seus dedos nervosos.
136
Captulo 6. Configurao do Servidor
Um repositrio Subversion pode ser acessado simultaneamente por clientes executando na mesma
mquina na qual o repositrio se encontra usando o mtodo file://. Mas a configurao tpica do
Subversion envolve ter-se uma nica mquina servidora sendo acessada por clientes em computadores
por todo um escritrioou, talvez, por todo o mundo.
Este captulo descreve como ter seu repositrio Subversion acessvel a partir da mquina onde estiver
instalado para uso por clientes remotos. Vamos cobrir os mecanismos de servidor do Subversion
disponveis atualmente, discutindo a configurao e o uso de cada um. Depois de ler esta seo, voc
deve ser capaz de decidir qual configurao a adequada s suas necessidades, e entender como
habilitar tal configurao em seu servidor.
Viso Geral
O Subversion foi desenvolvido com uma camada de rede abstrata. Isso significa que um repositrio
pode ser acessado via programao por qualquer tipo de processo servidor, e a API de acesso ao
repositrio do cliente permite aos programadores escrever plugins que falem com protocolos de rede
relevantes. Em teoria, o Subversion pode usar um nmero infinito de implementaes de rede. Na
prtica, h apenas dois servidores at o momento em que este livro estava sendo escrito.
O Apache um servidor web extremamente popular; usando o mdulo mod_dav_svn, o Apache pode
acessar um repositrio e torn-lo disponvel para os clientes atravs do protocolo WebDAV/DeltaV, que
uma extenso do HTTP. Como o Apache um servidor web extremamente extensvel, ele prov um
conjunto de recursos de graa, tais como comunicao SSL criptografada, sistema de log, integrao
com diversos sistemas de autenticao de terceiros, alm de navegao simplificada nos repositrios.
Por outro lado est o svnserve: um programa servidor pequeno e leve que conversa com os clientes por
meio de um protocolo especfico. Pelo fato de ter sido explicitamente desenvolvido para o Subversion
e de manter informaes de estado (diferentemente do HTTP), este seu protocolo permite operaes
de rede significativamente mais rpidasainda que ao custo de alguns recursos. Este protocolo s
entende autenticao do tipo CRAM-MD5, no possui recursos de log, nem de navegao web nos
repositrios, e no tem opo de criptografar o trfego de rede. Mas , no entanto, extremamente fcil
de configurar e quase sempre a melhor opo para pequenas equipes que ainda esto iniciando com
o Subversion.
Uma terceira opo o uso do svnserve atravs de uma conexo SSH. Por mais que este cenrio ainda
use o svnserve, ele difere um pouco no que diz respeito aos recursos de uma implantao svnserve
tradicional. SSH usado para criptografar toda a comunicao. O SSH tambm usado exclusivamente
para autenticao, ento so necessrias contas reais no sistema do host servidor (diferentemente do
uso do svnserve tradicional, que possui suas prprias contas de usurio particulares.) Finalmente, pelo
fato desta configurao precisar que cada usurio dispare um processo temporrio svnserve particular,
esta opo equivalente (do ponto de vista de permisses) a permitir total acesso de um grupo local de
usurios no repositrio por meio de URLs file://. Assim, controle de acesso com base em caminhos
no faz sentido, j que cada usurio est acessando os arquivos da base de dados diretamente.
137
Configurao do Servidor
Obviamente, no h uma resposta definitiva para esta pergunta. Cada equipe tem diferentes
necessidades e os diferentes servidores todos representam diferentes conjuntos de caractersticas. O
projeto Subversion em si no endossa um ou outro servidor, nem mesmo considera um servidor mais
oficial que outro.
Aqui esto algumas razes pelas quais voc deveria escolher uma configurao ao invs de outra,
bem como as razes pelas quais voc no deveria escolher uma delas.
O Servidor svnserve
Porque voc pode querer us-lo:
138
Configurao do Servidor
Necessita que os usurios estejam num mesmo grupo no sistema, ou que usem uma chave ssh
compartilhada.
Permite que o Subversion use quaisquer dos inmeros sistemas de autenticao j disponveis
e integrados com o Apache.
Repositrio pode ser montado como um drive de rede para controle de verso transparente.
(Veja Autoversionamento.)
Notavelmente mais lento que o svnserve, pelo fato do HTTP ser um protocolo sem informao
de estado e acabar demandando mais requisies.
Recomendaes
No geral, os autores deste livro recomendam uma instalao tradicional do svnserve para pequenas
equipes que ainda esto tentando familiarizar-se com o servidor Subversion; a forma mais simples
de utilizao, e a que demanda menos esforo de manuteno. Voc sempre pode trocar para uma
implantao de servidor mais complexa conforme suas necessidades mudem.
Aqui seguem algumas recomendaes e dicas em geral, baseadas na experincia de vrios anos de
suporte a usurios:
139
Configurao do Servidor
Se voc est tentando configurar o servidor mais simples possvel para seu grupo, ento uma
instalao tradicional do svnserve o caminho mais fcil e rpido. Note, entretanto, que os dados
de seu repositrio vo ser transmitidos s claras pela rede. Se voc estiver fazendo uma implantao
inteiramente dentro de sua rede LAN ou VPN da sua empresa, isto no chega a ser nenhum
problema. Mas se o repositrio tiver de ser acessvel pela internet, ento voc deveria se assegurar
que o contedo do repositrio no contm dados sensveis (p.ex. se apenas cdigo-fonte.)
Se voc precisar de integrao com alguns sistemas de identificao existentes (LDAP, Active
Directory, NTLM, X.509, etc.), ento uma configurao baseada no Apache ser sua nica opo.
Similarmente, se voc indispensavelmente precisar de log de servidor tanto para registro de erros de
servidor quanto para atividades dos clientes, ento um servidor com base no Apache ser necessrio.
Se voc optou por usar ou o Apache ou o svnserve, crie uma nica conta no sistema para o
usurio svn e faa com que o processo do servidor seja executado por este usurio. Certifique-se
de fazer com que o diretrio do repositrio pertena totalmente ao usurio svn tambm. Do ponto de
vista da segurana, isto deixa os dados do repositrio adequadamente seguros e protegidos pelas
permisses do sistema de arquivos do sistema operacional, alterveis apenas pelo prprio processo
do servidor Subversion.
Se voc j tiver uma infraestrutura fortemente baseada em contas SSH, e se seus usurios j
possurem contas no servidor, ento faz sentido implantar uma soluo usando o svnserve sobre
SSH. Caso contrrio, no recomendamos esta opo largamente ao pblico. Ter seus usurios
acessando o repositrio por meio de contas (imaginrias) gerenciadas pelo svnserve ou pelo Apache
geralmente considerado mais seguro do que ter acesso por meio de contas reais no sistema. Se
o motivo para voc fazer isso for apenas obter uma comunicao criptografada, ns recomendamos
que voc utilize Apache com SSL no lugar.
No e entusiasme simplesmente com a idia de ter todos os seus usurios acessando o repositrio
diretamente atravs de URLs file://. Mesmo se o repositrio estiver disponvel a todos para
leitura atravs de um compartilhamento de rede, isto uma m idia. Esta configurao remove
quaisquer camadas de proteo entre os usurios e o repositrio: os usurios podem acidentalmente
(ou intencionalmente) corromper a base de dados do repositrio, dificulta deixar o repositrio offline
para fins de inspeo ou atualizao, e ainda podem surgir problemas relacionados a permisses de
arquivos (veja Dando Suporte a Mltiplos Mtodos de Acesso ao Repositrio.) Perceba que esta
uma das razes pelas quais ns alertamos acerca do acesso aos repositrios atravs de URLs
svn+ssh://o que sob a perspectiva de segurana, efetivamente o mesmo que ter usurios
locais acessando via file://, e pode resultar nos mesmos problemas se o administrador no for
cuidadoso.
Invocando o Servidor
H poucas maneiras distintas de se invocar o programa svnserve:
Fazer com que o daemon inetd do Unix dispare temporariamente o svnserve a cada vez que uma
requisio chegar numa dada porta.
Fazer com que o SSH execute um svnserve temporrio sobre um tnel criptografado.
140
Configurao do Servidor
$ svnserve -d
$ # o svnserve est rodando agora, ouvindo na porta 3690
Ao executar o svnserve no modo daemon, voc pode usar as opes --listen-port= e --listen-
host= para especificar a porta e o hostname exatos aos quais o servidor estar associado.
Uma vez que tenhamos iniciado o svnserve como mostrado acima, isto torna todos os repositrios
do sistema disponveis na rede. Um cliente precisa especificar uma URL com um caminho absoluto
do repositrio. Por exemplo, se um repositrio estiver localizado em /usr/local/repositories/
project1, ento um cliente deveria acess-lo com svn://host.example.com/usr/local/
repositories/project1. Para aumentar a segurana, voc pode passar a opo -r para o
svnserve, o que limita a exportar apenas os repositrios sob o caminho especificado. Por exemplo:
$ svnserve -d -r /usr/local/repositories
O uso da opo -r efetivamente modifica o local que o programa considera como a raiz do sistema
de arquivos remoto. Os clientes ento usam URLs com aquela parte do caminho removida, tornando-
as mais curtas (e bem menos informativas):
$ svnserve -i
( success ( 1 2 ( ANONYMOUS ) ( edit-pipeline ) ) )
Quando invocado com a opo --inetd, o svnserve tenta se comunicar com um cliente Subversion
por meio do stdin e stdout usando um protocolo especfico. Este o comportamento padro para
um programa sendo executado atravs do inetd. A IANA reservou a porta 3690 para o protocolo
Subversion, assim, em um sistema Unix-like voc poderia adicionar linhas como estas ao arquivo /
etc/services (se elas j no existirem):
E se seu sistema Unix-like estiver usando um daemon inetd clssico, voc pode adicionar esta linha
ao arquivo /etc/inetd.conf:
Assegure-se de que svnowner seja um usurio com permisses apropriadas para acesso aos seus
repositrios. Agora, quando uma conexo do cliente atingir seu servidor na porta 3690, o inetd vai
disparar um processo svnserve para atend-la. Obviamente, voc tambm pode querer adicionar a
opo -r para restringir quais repositrios sero exportados.
141
Configurao do Servidor
Esta opo est descrita com mais detalhes em Tunelamento sobre SSH.
Voc vai precisar definir o novo servio usando a ferramenta de linha de comando SC.EXE..
Semelhantemente linha de configurao do inetd, voc deve especificar a forma exata de invocao
do svnserve para que o Windows o execute na inicializao:
Isto define um novo servio do Windows chamado svn, o qual executa um comando svnserve.exe
particular quando iniciado (neste caso, com raiz em C:\repos.) No entanto, h diversos pontos a
considerar neste exemplo anterior.
Primeiramente, note que o programa svnserve.exe deve sempre ser chamado com a opo --
service. Quaisquer outras opes para o svnserve ento devem ser especificadas na mesma linha,
mas voc no pode adicionar opes conflitantes tais como --daemon (-d), --tunnel, ou --inetd
(-i). J opes como -r ou --listen-port no tero problemas. Em segundo lugar, tenha cuidado
com relao a espaos ao invocar o comando SC.EXE: padres chave= valor no devem conter
espaos entre chave= e devem ter exatamente um espao antes de valor. Por ltimo, tenha cuidado
tambm com espaos na sua linha de comando a ser executada. Se um nome de diretrio contiver
espaos (ou outros caracteres que precisem de escape), coloque todo o valor interno de binpath
entre aspas duplas, escapando-as:
Tambm observe que o termo binpath confusoseu valor a linha de comando, no o caminho
para um executvel. Por isso que voc precisa delimit-lo com aspas se o valor contiver espaos.
142
Configurao do Servidor
Uma vez que o servio esteja definido, ele pode ser parado, iniciado, ou consultado usando-se as
ferramentas GUI (o painel de controle administrativo Servios), bem como atravs da linha de comando:
O servio tambm pode ser desinstalado (i.e. indefinido) excluindo-se sua definio: sc delete svn.
Apenas certifique-se de parar o servio antes! O programa SC.EXE tem diversos outros subcomandos
e opes; digite sc /? para saber mais sobre ele.
ao cliente pode ser permitido fazer requisies de forma annima, sem mesmo precisar receber
um desafio de autenticao, OU
se operando em modo tnel, o cliente ir declarar a si prprio como j tendo sido externamente
autenticado.
At o momento em que este livro estava sendo escrito, o servidor sabia apenas como enviar desafios
1
de autenticao do tipo CRAM-MD5 Essencialmente, o servidor envia uma pequena quantidade de
dados para o cliente. O cliente usa o algoritmo de hash MD5 para criar uma impresso digital dos
dados e da senha combinados, ento envia esta impresso digital como resposta. O servidor realiza a
mesma computao com a senha armazenada para verificar se os resultados coincidem. Em nenhum
momento a senha atual trafegada pela rede.
E claro, tambm possvel para o cliente ser autenticado externamente por meio de um tnel agente, tal
como o SSH. Neste caso, o servidor simplesmente examina o usurio com o qual est sendo executado,
e o utiliza como nome de usurio autenticado. Para mais detalhes sobre isto, veja Tunelamento sobre
SSH.
Como voc j deve ter percebido, o arquivo svnserve.conf do repositrio o mecanismo central para
controle das polticas de autenticao e autorizao. O arquivo possui o mesmo formato que outros
arquivos de configurao (veja rea de Configurao do Tempo de Execuo): nomes de seo so
marcados por colchetes ([ e [), comentrios iniciam por cerquilha (#), e cada seo contm variveis
especficas que podem ser definidas (varivel = valor). Vamos conferir estes arquivos e aprender
como us-los.
[general]
password-db = userfile
realm = example domain
1
Consulte a RFC 2195.
143
Configurao do Servidor
O domnio (realm) um nome que voc define. Ele informa aos clientes a que tipo de espao
de nomes de autenticao voc est se conectando; o cliente Subversion o exibe no prompt de
autenticao, e o utiliza como chave (junto com o hostname do servidor e a porta) para fazer cache de
credenciais no disco (veja Armazenando Credenciais no Cliente). A varivel password-db aponta
para um arquivo em separado que contm uma lista de nomes de usurios e senhas, usando o mesmo
formato familiar. Por exemplo:
[users]
harry = foopassword
sally = barpassword
O valor de password-db pode ser um caminho absoluto ou relativo para o arquivo de usurios. Para
muitos administradores, fcil manter o arquivo logo dentro da rea conf/ do repositrio, juntamente
com o svnserve.conf. Por outro lado, possvel que voc queira ter dois ou mais repositrios
compartilhando o mesmo arquivo de usurios; neste caso, o arquivo provavelmente deve ficar em
um local mais pblico. Repositrios que compartilhem o arquivo de usurios tambm devem ser
configurados para ter um mesmo domnio, uma vez que a lista de usurios essencialmente define um
domnio de autenticao. Onde quer que este arquivo esteja, certifique-se de definir as permisses de
leitura e escrita adequadamente. Se voc sabe com qual(is) usurio(s) o svnserve ir rodar, restrinja
o acesso de leitura ao arquivo de usurios conforme necessrio.
[general]
password-db = userfile
realm = example domain
De fato, as configuraes deste exemplo so os valores padro para as variveis, voc poderia
esquecer de defin-las. Se voc quer ser ainda mais conservador, voc pode bloquear o acesso
annimo completamente:
[general]
password-db = userfile
realm = example realm
O processo servidor no entende apenas esta restrio no controle de acesso ao repositrio, mas
tambm restries de acesso mais granularizadas definidas para arquivos ou diretrios especficos
144
Configurao do Servidor
dentro do repositrio. Para usar este recurso, voc precisa criar um arquivo contendo regras mais
detalhadas, e ento definir o valor da varivel authz-db para o caminho que o aponte:
[general]
password-db = userfile
realm = example realm
fcil usar o SSH juntamente com o svnserve. O cliente simplesmente usa o esquema svn+ssh://
na URL para conectar:
$ whoami
harry
foo
bar
baz
Neste exemplo, o cliente Subversion est invocando um processo ssh local, conectando-se a
host.example.com, autenticando-se como usurio harry, ento disparando um processo svnserve
particular na mquina remota rodando como o usurio harry O comando svnserve est sendo
invocado atravs em modo tnel (-t) e seu protocolo de rede est sendo tunelado pela conexo
criptografada pelo ssh, o tnel agente. O svnserve sabe que est sendo executando pelo usurio
harry, e se o cliente executar um commit, o nome do usurio autenticado ser usado como autor da
nova reviso.
Ao usar URLs svn+ssh:// para acessar um repositrio, lembre-se que o programa ssh que
est solicitando autenticao, e no o programa cliente svn. Isto quer dizer que aqui no h cache
automtico de senhas acontecendo (veja Armazenando Credenciais no Cliente). O cliente Subversion
quase sempre faz mltiplas conexes ao repositrio, apesar de que os usurios normalmente no
percebem isto devido a este recurso de cache de senhas. Ao usar URLs svn+ssh://, entretanto,
os usurios podem ser incomodados repetidamente pelo ssh solicitando senhas a cada conexo que
inicie. A soluo usar uma ferramenta separada para cache de senhas do SSH como o ssh-agent
em um sistema Unix-like, ou o pageant no Windows.
145
Configurao do Servidor
Voc pode ter pensado que essa histria de tunelamento com SSH acabou por aqui, mas no. O
Subversion permite que voc crie comportamentos especficos para o modo tnel em seu arquivo
config de execuo (veja rea de Configurao do Tempo de Execuo). Por exemplo, suponha
3
que voc queira usar o RSH ao invs do SSH . Na seo [tunnels] do seu arquivo config,
simplesmente defina algo parecido com isto:
[tunnels]
rsh = rsh
E agora, voc pode usar este nova definio de tnel usando um esquema de URL que casa com
o nome de sua nova varivel: svn+rsh://host/path. Ao usar o novo esquema de URL, o cliente
Subversion atualmente vai ser executado pelo comando rsh host svnserve -t por trs dos panos. Se
voc incluir um nome de usurio na URL (por exemplo, svn+rsh://username@host/path) o cliente
tambm vai inclu-lo em seu comando (rsh username@host svnserve -t). Mas voc pode definir novos
esquemas de tunelamento que sejam muito mais inteligentes que isto:
[tunnels]
joessh = $JOESSH /opt/alternate/ssh -p 29934
Este exemplo demonstra uma poro de coisas. Primeiro, ele mostra como fazer o cliente do
Subversion executar um binrio de tunelamento bem especfico (este que est localizado em /
opt/alternate/ssh) com opes especficas. Neste caso, acessando uma URL svn+joessh://
deveria invocar o binrio SSH em questo com -p 29934 como argumentostil se voc quer que
o programa do tnel se conecte a uma porta no-padro.
Segundo, esse exemplo mostra como definir uma varivel de ambiente personalizada que pode
sobrescrever o nome do programa de tunelamento. Definir a varivel de ambiente SVN_SSH
uma maneira conveniente de sobrescrever o tnel agente SSH padro. Mas se voc precisar fazer
sobrescrita diversas vezes para diferentes servidores, cada um talvez contactando uma porta diferente
ou passando diferentes conjuntos de opes para o SSH, voc pode usar o mecanismo demonstrado
neste exemplo. Agora se formos definir a varivel de ambiente JOESSH, seu valor ir sobrescrever
o valor inteiro da varivel tnel$JOESSH dever ser executado ao invs de /opt/alternate/ssh -p
29934.
Configurao inicial
Para comear, localize o diretrio home da conta que voc vai usar para executar o svnserve.
Certifique-se de que a conta tenha um par de chaves pblica/privada instalado, e que o usurio consiga
2
Perceba que usar qualquer tipo de controle de acesso atravs do svnserve acaba no fazendo muito sentido; o usurio sempre
possui acesso direto base de dados do repositrio.
3
Atualmente ns no recomendamos isto, uma vez que o RSH sabidamente menos seguro que o SSH.
146
Configurao do Servidor
ter acesso ao sistema por meio de autenticao com chave pblica. A autenticao por senha no
ir funcionar, j que todas as seguintes dicas sobre SSH esto relacionadas com o uso do arquivo
authorized_keys do SSH.
O primeiro campo descreve o tipo da chave, o segundo campo a chave em si codificada em base64,
e o terceiro campo um comentrio. Porm, pouco conhecido o fato de que a linha inteira pode ser
precedida por um campo command:
Quando o campo command definido, o daemon SSH ir rodar o programa descrito em vez da tpica
invocao svnserve -t que o cliente Subversion est esperando. Isto abre espao para um conjunto
de truques no lado do servidor. Nos exemplos a seguir, abreviamos a linha do arquivo para:
Neste exemplo, /caminho/do/svnserve pode ser um script especfico que encapsule uma chamada
ao svnserve e que configure o umask (veja Dando Suporte a Mltiplos Mtodos de Acesso ao
Repositrio). O exemplo tambm mostra como prender o svnserve em um diretrio raiz virtual, tal
como sempre ocorre ao se executar o svnserve como um processo daemon. Isto pode ser feito tanto
para restringir o acesso a partes do sistema, ou simplesmente para facilitar para que o usurio no
tenha de digitar um caminho absoluto na URL svn+ssh://.
Tambm possvel ter mltiplos usurios compartilhando uma nica conta. Ao invs de criar uma conta
em separado no sistema para cada usurio, gere um par de chaves pblica/privada para cada pessoa.
Ento ponha cada chave pblica dentro do arquivo authorized_keys, uma por linha, e utilize a opo
--tunel-user:
Este exemplo permite que Harry e Sally se conectem mesma conta por meio da autenticao de
chave pblica. Cada um deles tem um comando especfico a ser executado; a opo --tunnel-user
diz ao svnserve -t para assumir que o argumento informado um nome de usurio autenticado. No
fosse pelo --tunnel-user pareceria como se todos os commits viessem de uma nica mesma conta
de sistema compartilhada.
Uma ltima palavra de precauo: dando acesso ao usurio atravs de uma chave pblica numa conta
compartilhada deve permitir ainda outras formas de acesso por SSH, ainda que voc j tenha definido
o valor do campo command no authorized_keys. Por exemplo, o usurio pode ainda ter acesso a
um shell atravs do SSH, ou ser capaz de executar o X11 ou outro tipo de redirecionamento de portas
147
Configurao do Servidor
atravs do servidor. Para dar ao usurio o mnimo de permisso possvel, voc pode querer especificar
algumas opes restritivas imediatamente aps o command:
command="svnserve -t --tunnel-user=harry",no-port-forwarding,\
no-agent-forwarding,no-X11-forwarding,no-pty \
TIPO1 CHAVE1 harry@example.com
Muitas das discusses a seguir incluem referncias a diretivas de configurao do Apache. Por mais
que sejam dados exemplos de uso destas diretivas, descrev-las por completo est fora do escopo
deste captulo. A equipe do Apache mantm excelente documentao, disponvel publicamente no seu
website em http://httpd.apache.org. Por exemplo, uma referncia geral das diretivas de configurao
est localizada em http://httpd.apache.org/docs-2.0/mod/directives.html.
Alm disso, quando voc faz alterao na configurao do seu Apache, bem provvel que erros sejam
cometidos em algum ponto. Se voc ainda no est ambientado com o subsistema de logs do Apache,
voc deveria familiarizar-se com ele. Em seu arquivo httpd.conf esto as diretivas que especificam
os caminhos em disco dos logs de acesso e de erros gerados pelo Apache (as diretivas CustomLog e
ErrorLog, respectivamente). O mdulo mod_dav_svn do Subversion tambm usa a interface de logs
de erro do Apache. A qualquer momento voc pode verificar o contedo destes arquivos, buscando
informao que pode revelar a causa de um problema que no seria claramente percebido de outra
forma.
Se voc um administrador de sistemas, bem provvel que voc j esteja rodando o servidor
web Apache e tenha alguma experincia anterior com ele. No momento em que este livro era
escrito, o Apache 1.3 de longe a verso mais popular do Apache. O mundo tem sido um
tanto lento para atualizar para o Apache da srie 2.X por vrias razes: algumas pessoas tm
medo da mudana, especialmente mudana em algo to crtico como um servidor web. Outras
pessoas dependem de mdulos de plug-in que s funcionam sobre a API do Apache 1.3, e esto
aguardando que estes sejam portados para a 2.X. Qualquer que seja a razo, muitas pessoas
comeam a se preocupar quando descobrem que o mdulo Apache do Subversion escrito
especificamente para a API do Apache 2.
A resposta adequada a este problema : no se preocupe com isto. fcil executar o Apache 1.3
e o Apache 2 lado a lado; simplesmente instale-os em locais separados, e use o Apache 2 como
um servidor Subversion dedicado que execute em outra porta que no a 80. Os clientes podem
acessar o repositrio inserindo o nmero da porta na URL:
4
Eles realmente detestam fazer isso.
148
Configurao do Servidor
Pr-requisitos
Para disponibilizar seus repositrios em rede via HTTP, voc basicamente necessita de quatro
componentes, disponveis em dois pacotes. Voc vai precisar do Apache httpd 2.0, do mdulo
DAV mod_dav que j vem com ele, do Subversion, e do mod_dav_svn, mdulo que prov acesso
ao sistema de arquivos distribudo junto com o Subversion. Uma vez que voc tenha todos estes
componentes, o processo de disponibilizar seus repositrios em rede to simples quanto:
instalar o plugin mod_dav_svn no mod_dav, que utiliza as bibliotecas do Subversion para acessar
o repositrio e
Voc pode realizar os primeiros dois passos tanto compilando o httpd e o Subversion a partir do cdigo-
fonte, ou instalando os pacotes binrios pr-construdos para o seu sistema. Para informaes mais
atualizadas sobre como compilar o Subversion para uso com o servidor Apache HTTP, alm de como
compilar e configurar o prprio Apache para este propsito, veja o arquivo INSTALL na pasta de mais
alto nvel na rvore do cdigo-fonte do Subversion.
Note que se o mod_dav foi compilado como um objeto compartilhado (ao invs de ter sido lincado
diretamente ao binrio httpd), voc vai precisar de uma declarao LoadModule para ele, tambm.
Assegure-se de que sua declarao venha antes da linha mod_dav_svn:
Em outra parta de seu arquivo de configurao, voc agora vai dizer ao Apache onde voc mantm
seu repositrio (ou repositrios) Subversion. A diretiva Location tem uma notao parecida com a
de XML, comeando com uma tag de abertura, e terminando com uma tag de fechamento, com vrias
outras diretivas de configurao no meio. O propsito da diretiva Location instruir o Apache a fazer
algo especial quando manipular requisies que sejam direcionadas a uma certa URL ou uma de suas
filhas. No caso do Subversion, quer que o Apache simplesmente desconsidere URLs que apontem para
recursos sob controle de verso na camada DAV. Voc pode instruir o Apache a delegar a manipulao
de todas as URL em que cuja parte do caminho (a parte da URL aps o nome do servidor e do nmero
de porta opcional) comece com /repos/ para um provedor DAV cujo repositrio est localizado em /
caminho/absoluto/do/repositorio usando a seguinte sintaxe do httpd.conf:
<Location /repos>
DAV svn
SVNPath /caminho/absoluto/do/repositrio
149
Configurao do Servidor
</Location>
Se voc pretende disponibilizar mltiplos repositrios Subversion que se encontrem sob um mesmo
diretrio-pai em seu disco local, voc pode usar uma diretiva alternativa, a diretiva SVNParentPath,
para indicar este diretrio-pai comum. Por exemplo, se voc sabe que voc vai criar mltiplos
repositrios Subversion num diretrio /usr/local/svn que poderia ser acessado a partir de URLs
como http://my.server.com/svn/repos1, http://my.server.com/svn/repos2, e assim
por diante, voc pode usar a sintaxe de configurao do httpd.conf do exemplo a seguir:
<Location /svn>
DAV svn
Usando a sintaxe anterior, o Apache vai delegar a manipulao de todas as URLs cuja a parte do
caminho comece com /svn/ para o provedor DAV do Subversion, que ento vai assumir que quaisquer
itens no diretrio especificado pela diretiva SVNParentPath atualmente so repositrios Subversion.
Esta uma sintaxe particularmente conveniente para isto, ao contrrio do uso da diretiva SVNPath,
voc no tem que reiniciar o Apache para criar e acessar via rede os novos repositrios.
Certifique-se de que ao definir seu novo Location, este no se sobreponha a outros Locations
exportados. Por exemplo, se seu DocumentRoot principal estiver exportado para /www, no exporta
um repositrio Subversion em <Location /www/repos>. Se vier uma requisio para a URL
/www/repos/foo.c, o Apache no vai saber se deve procurar pelo arquivo repos/foo.c no
DocumentRoot, ou se delega ao mod_dav_svn para que este retorne foo.c a partir do repositrio
Subversion. O resultado quase sempre um erro de servidor no formato 301 Moved Permanently.
Subversion faz uso da requisio do tipo COPY para executar cpias de arquivos e diretrios do
lado do servidor. Como parte da verificao de integridade feita pelos mdulos do Apache,
espera-se que a origem da cpia esteja localizada na mesma mquina que o destino da cpia.
Para satisfazer este requisito, voc vai precisar dizer ao mod_dav o nome do hostname usado em
seu servidor. Geralmente, voc pode usar a diretiva ServerName no httpd.conf para fazer isto.
ServerName svn.example.com
Se voc est usando o suporte a hosts virtuais do Apache atravs da diretiva NameVirtualHost,
voc pode precisar usar a diretiva ServerAlias para especificar nomes adicionais pelos quais
seu servidor tambm conhecido. Mais uma vez, verifique a documentao do Apache para mais
detalhes.
Neste estgio, voc deve considerar maciamente a questo das permisses. Se voc j estiver
executando o Apache h algum tempo como seu servidor web regular, voc provavelmente j tem uma
poro de contedospginas web, scripts e similares. Estes itens j devem ter sido configurados com
um conjunto de permisses que lhes possibilitam trabalhar com o Apache, ou mais adequadamente,
que permite ao Apache trabalhar com estes arquivos. O Apache, quando usado como um servidor
Subversion, tambm vai precisar das permisses corretas para ler e escrever em seu repositrio
Subversion.
Voc vai precisar determinar uma configurao do sistema de permisses que satisfaa os requisitos
do Subversion sem causar problemas em nenhuma pgina ou script previamente instalado. Isto pode
significar alterar as permisses de seu repositrio Subversion para corresponder quelas em uso
150
Configurao do Servidor
por outras coisas que o Apache lhe serve, ou pode significar usar as diretivas User e Group no
httpd.conf para especificar que o Apache deve executar como o usurio e grupo de que seja dono
do seu repositrio Subversion. No h apenas uma maneira correta de configurar suas permisses, e
cada administrador vai ter diferentes razes para fazer as coisas de uma dada maneira. Apenas tenha
cuidado pois problemas de permisso so talvez a falha mais comum ao se configurar o repositrio
Subversion para uso com o Apache.
Opes de Autenticao
Neste ponto, se voc configurou o httpd.conf para conter algo como
<Location /svn>
DAV svn
SVNParentPath /usr/local/svn
</Location>
ento seu repositrio est anonimamente acessvel ao mundo. At que voc configure algumas
polticas de autenticao e autorizao, os repositrios Subversion que voc disponibilizar atravs da
diretiva Location vo estar globalmente acessveis a qualquer um. Em outras palavras,
qualquer pessoa pode usar seu cliente Subversion para dar checkout numa cpia de trabalho de
uma URL do repositrio (ou qualquer de seus subdiretrios),
qualquer pessoa pode navegar interativamente pela ltima reviso do repositrio, simplesmente
direcionando seu navegador web para a URL do repositrio, e
Certamente, voc pode j ter definido um hook script para prevenir commits (veja Implementando
Ganchos de Repositrio). Mas conforme voc for lendo, ver que tambm possvel usar os mtodos
inerentes ao Apache para restringir o acesso de maneiras especficas.
A seguir, voc precisa adicionar mais algumas diretivas do httpd.conf dentro de seu bloco
Location para indicar ao Apache o que fazer com seu novo arquivo de senhas. A diretiva AuthType
especifica o tipo de sistema de autenticao a usar. Neste caso, vamos especificar o sistema de
151
Configurao do Servidor
autenticao Basic. AuthName um nome arbitrrio que voc d para o domnio da autenticao.
A maioria dos navegadores web vai mostrar este nome da caixa de dilogo quando o navegador
estiver perguntando ao usurio por seu nome e senha. Finalmente, use a diretiva AuthUserFile para
especificar a localizao do arquivo de senhas que voc criou usando o comando htpasswd.
Depois de adicionar estas trs diretivas, seu bloco <Location> deve ser algo parecido com isto:
<Location /svn>
DAV svn
SVNParentPath /usr/local/svn
AuthType Basic
AuthName "Subversion repository"
AuthUserFile /etc/svn-auth-file
</Location>
Este bloco <Location> ainda no est completo, e no far nada de til. Est meramente dizendo ao
Apache que sempre que uma autorizao for requerida, o Apache deve obter um nome de usurio e
senha do cliente Subversion. O que est faltando aqui, entretanto, so diretivas que digam ao Apache
quais tipos de requisies do cliente necessitam de autorizao. Toda vez que uma autorizao for
requerida, o Apache tambm ir exigir uma autorizao. A coisa mais simples a se fazer proteger
todas as requisies. Adicionar Require valid-user indica ao Apache que todas as requisies
requerem um usurio autenticado:
<Location /svn>
DAV svn
SVNParentPath /usr/local/svn
AuthType Basic
AuthName "Subversion repository"
AuthUserFile /etc/svn-auth-file
Require valid-user
</Location>
No deixe de ler a prxima seo (Opes de Autorizao) para mais detalhes sobre a diretiva
Require e outras formas de definir polticas de autorizao.
Uma palavra de alerta: senhas de autenticao HTTP Basic trafegam na rede de forma bem parecida
com texto plano, e portanto so extremamente inseguras. Se voc est preocupado com a privacidade
de suas senhas, pode ser melhor usar algum tipo de criptografia SSL para que o cliente se autentique
atravs de https:// ao invs de http://; no mnimo, voc pode configurar o Apache para usar um
5
certificado de servidor auto-assinado. Consulte a documentao do Apache (e a documentao do
OpenSSL) sobre como faz-lo.
Se um cliente Subversion compilado para usar OpenSSL, ento ele ganha a habilidade de falar com
um servidor Apache atravs de URLs https://. A biblioteca Neon usada pelo cliente Subversion
no apenas capaz de verificar certificados de servidor, mas tambm de prover certificados de cliente
quando necessrio. Quando cliente e o servidor trocam certificados SSL e se autenticam mutuamente
com sucesso, toda a comunicao subseqente criptografada por meio de uma chave de sesso.
5
Por mais que certificados auto-assinados ainda sejam vulnerveis ao ataque do homem do meio, tal ataque muito mais difcil
de ser executado por um observador casual, do que o comparado a vasculhar senhas desprotegidas.
152
Configurao do Servidor
Est fora do escopo deste livro descrever como gerar certificados de cliente e de servidor, e como
configurar o Apache para us-los. Muitos outros livros, incluindo a prpria documentao do Apache,
descrevem esta tarefa. Mas o que pode ser coberto aqui como gerenciar os certificados de cliente e
servidor a partir de um cliente Subversion ordinrio.
Ao se comunicar com o Apache atravs de https://, um cliente Subversion pode receber dois
diferentes tipos de informao:
um certificado de servidor
Se o cliente recebe um certificado de servidor, ele precisa verificar se confia no certificado: o servidor
quem ele realmente diz ser? A biblioteca OpenSSL faz isto examinando o assinador do certificado de
servidor ou autoridade certificadora (AC). Se o OpenSSL for incapaz de confiar automaticamente na AC,
ou se algum outro problema ocorrer (como o certificado ter expirado ou o hostname no corresponder),
o cliente de linha de comando do Subversion vai lhe perguntar se voc quer confiar no certificado do
servidor de qualquer maneira:
Este dilogo deve parecer familiar: essencialmente a mesma pergunta que voc provavelmente
j tenha visto vindo de seu navegador web (o qual apenas outro cliente HTTP como o cliente
Subversion). Se voc escolher a opo (p)ermanente, o certificado do servidor ser armazenado em
cache em sua rea privativa de tempo de execuo, auth/, da mesma forma que seu nome de usurio
e senha so armazenados (veja Armazenando Credenciais no Cliente). Uma vez armazenado, o
Subversion automaticamente lembrar de confiar neste certificado em negociaes futuras.
Seu arquivo em tempo de execuo servers tambm lhe possibilita fazer seu cliente Subversion
confiar automaticamente em ACs especficas, tanto de forma global quanto discriminadamente por
ssl-authority-files para uma lista de certificados das ACs com codificao PEM separados por
ponto e vrgula:
[global]
ssl-authority-files = /caminho/do/CAcert1.pem;/caminho/do/CAcert2.pem
Muitas instalaes OpenSSL tambm possuem um conjunto pr-definido de ACs padro que so
quase que universalmente confiveis. Para fazer o cliente Subversion confiar automaticamente nestas
autoridades padro, atribua o valor da varivel ssl-trust-default-ca para true.
Ao conversar com o Apache, o cliente Subversion pode tambm receber um desafio para um certificado
de cliente. O Apache est solicitando que o cliente identifique a si prprio: o cliente quem ele realmente
diz ser? Se tudo prosseguir corretamente, o cliente Subversion manda de volta um certificado privativo
assinado por uma AC na qual o Apache confia. O certificado do cliente comumente armazenado em
disco num formato criptografado, protegido por uma senha local. Quando o Subversion recebe este
desafio, ele solicitar a voc tanto o caminho do certificado quando a senha que o protege:
153
Configurao do Servidor
Note que o certificado do cliente um arquivo no formato p12. Para usar um certificado de cliente
com o Subversion, este deve estar no formato PKCS#12, que um padro portvel. A maioria dos
navegadores j so capazes de importar e exportar certificados neste formato. Outra opo usar as
ferramentas de linha de comando do OpenSSL para converter certificados existentes para PKCS#12.
Novamente, o arquivo em tempo de execuo servers permite a voc automatizar este desafio numa
configurao baseada em host. Qualquer um ou mesmo os dois tipos de informao podem estar
descritos em variveis em tempo de execuo:
[groups]
examplehost = host.example.com
[examplehost]
ssl-client-cert-file = /caminho/do/meu/cert.p12
ssl-client-cert-password = somepassword
Opes de Autorizao
At este ponto, voc configurou a autenticao, mas no a autorizao. O Apache capaz de desafiar
cliente e confirmar identidades, mas no est sendo dito como permitir ou restringir acesso a clientes
que possuam estas identidades. Esta seo descreve duas estratgias para controle de acesso de
seus repositrios.
The simplest form of access control is to authorize certain users for either read-only access to a
repository, or read/write access to a repository.
Voc pode restringir acesso em todas as operaes de repositrio adicionando a diretiva Require
valid-user ao seu bloco <Location>. Usando nosso exemplo anterior, isto significa que apenas
aos clientes que afirmaram ser harry ou sally, e forneceram a senha correta para seus respectivos
nomes de usurio ser permitido fazer qualquer coisa com o repositrio Subversion:
<Location /svn>
DAV svn
SVNParentPath /usr/local/svn
154
Configurao do Servidor
AuthType Basic
AuthName "Subversion repository"
AuthUserFile /caminho/do/arquivo/users
Algumas vezes voc no precisa de regras to rgidas. Por exemplo, o prprio repositrio do cdigo-
fonte do Subversion em http://svn.collab.net/repos/svn permite a qualquer um no mundo executar
tarefas somente-leitura no repositrio (como verificar cpias de trabalho e navegar pelo repositrio com
um navegador web), mas restringe todas as operaes de escrita a usurios autenticados. Para fazer
este tipo de restrio seletiva, voc pode usar as diretivas de configurao Limit e LimitExcept.
Como a diretiva Location, estes blocos possuem tags de abertura e de fechamento, e voc deve
inser-las dentro de seu bloco <Location>.
Os parmetros presentes nas diretivas Limit e LimitExcept so tipos de requisies HTTP que
so afetadas por aquele bloco. Por exemplo, se voc quiser desabilitar todo o acesso a seu repositrio
exceto as operaes somente-leitura atualmente suportadas, voc deve usar a diretiva LimitExcept,
passando os tipos de requisio GET, PROPFIND, OPTIONS, e REPORT como parmetros. Ento a j
mencionada diretiva Require valid-user deve ser colocada dentro do bloco <LimitExcept> ao
invs de apenas dentro do bloco <Location>.
<Location /svn>
DAV svn
SVNParentPath /usr/local/svn
Estes so apenas uns poucos exemplos simples. Para informao mais aprofundada sobre controle
de acesso e a diretiva Require, d uma olhada na seo Security da coleo de tutoriais da
documentao do Apache em http://httpd.apache.org/docs-2.0/misc/tutorials.html.
155
Configurao do Servidor
Para ativar este mdulo, voc precisa configurar seu bloco Location para usar a diretiva
AuthzSVNAccessFile, a qual especifica um arquivo contendo polticas de permisses para caminhos
dentro de seus repositrios. (Logo, logo, vamos discutir o formato deste arquivo.)
O Apache flexvel, ento voc tem a opo de configurar seu bloco em um destes trs padres
gerais. Para comear, escolha um destes trs padres de configurao. (Os exemplos abaixo so muito
simples; consulte a documentao do prprio Apache para ter muito mais detalhes sobre as opes
de autenticao e autorizao do Apache.)
O bloco mais simples permitir acesso abertamente a todo mundo. Neste cenrio, o Apache nunca
envia desafios de autenticao, ento todos os usurios so tratados como anonymous.
<Location /repos>
DAV svn
SVNParentPath /usr/local/svn
No outro extremo da escala de parania, voc pode configurar seu bloco para requisitar autenticao
de todo mundo. Todos os clientes devem prover suas credenciais para se identificarem. Seu bloco
requer autenticao incondicional atravs da diretiva Require valid-user, e define meios para
autenticao.
<Location /repos>
DAV svn
SVNParentPath /usr/local/svn
Um terceiro padro bem popular permitir uma combinao de acesso autenticado e annimo.
Por exemplo, muitos administradores querem permitir usurios annimos a ler certos diretrios do
repositrio, mas querem que apenas usurios autenticados leiam (ou escrevam) em reas mais
sensveis. Nesta configurao, todos os usurios comeam acessando o repositrio anonimamente.
Se sua poltica de controle de acesso solicitar um nome de usurio real em algum ponto, o Apache
vai solicitar autenticao para o cliente. Para fazer isto, voc usa ambas as diretivas Satisfy Any
e Require valid-user em conjunto.
156
Configurao do Servidor
<Location /repos>
DAV svn
SVNParentPath /usr/local/svn
Tendo se decidido por um destes trs modelos bsicos de httpd.conf, voc ento precisa criar seu
arquivo contendo regras de acesso para determinados caminhos dentro do repositrio. Isto descrito
em Autorizao Baseada em Caminhos.
Toda esta verificao de caminhos algumas vezes pode ser um pouco custosa, especialmente no caso
do svn log. Ao obter uma lista de revises, o servidor olha para cada caminho alterado em cada reviso
e verifica sua legibilidade. Se um caminho ilegvel descoberto, ento ele omitido da lista de caminhos
alterados da reviso (normalmente vista com a opo --verbose), e a mensagem de log completa
suprimida. Desnecessrio dizer que isto pode consumir bastante tempo em revises que afetam um
grande nmero de arquivos. Este o custo da segurana: mesmo se voc ainda nunca tiver configurado
um mdulo como mod_authz_svn, o mdulo mod_dav_svn ainda fica solicitando para que o Apache
httpd execute verificaes de autorizao em cada caminho. O mdulo mod_dav_svn no faz idia de
que mdulos de autorizao esto instalados, ento tudo o que ele pode fazer solicitar que o Apache
invoque todos os que podem estar presentes.
Por outro lado, tambm h um recurso de vlvula de escape, o qual permite a voc troque
caractersticas de segurana por velocidade. Se voc no estiver impondo nenhum tipo de autorizao
por diretrio (i.e. no est usando o mdulo mod_authz_svn ou similar), ento voc pode desabilitar
toda esta checagem de caminhos. Em seu arquivo httpd.conf, use a diretiva SVNPathAuthz:
157
Configurao do Servidor
<Location /repos>
DAV svn
SVNParentPath /usr/local/svn
SVNPathAuthz off
</Location>
A diretiva SVNPathAuthz definida como on por padro. Quando definida para off, toda a
checagem de autorizao baseada em caminhos desabilitada; o mod_dav_svn pra de solicitar
checagem de autorizao em cada caminho que ele descobre.
Facilidades Extras
Cobrimos a maior parte das opes de autenticao e autorizao para o Apache e o mod_dav_svn.
Mas h alguns outros poucos bons recursos que o Apache prov.
Navegao de Repositrio
Um dos mais teis benefcios de uma configurao do Apache/WebDAV para seu repositrio
Subversion que as revises mais recentes de seus arquivos e diretrios sob controle de verso
ficam imediatamente disponveis para visualizao por meio de um navegador web comum. Como
o Subversion usa URLs para identificar recursos sob controle de verso, estas URLs usadas para
acesso ao repositrio baseado em HTTP podem ser digitadas diretamente num navegador Web. Seu
navegador vai emitir uma requisio HTTP GET para aquela URL, e se aquela URL representar um
diretrio ou arquivo sobre controle de verso, o mod_dav_svn ir responder com uma listagem de
diretrio ou com o contedo do arquivo.
J que as URLs no contm nenhuma informao sobre quais verses do recurso voc quer ver,
o mod_dav_svn sempre ir responder com a verso mais recente. Esta funcionalidade tem um
maravilhoso efeito colateral que a possibilidade de informar URLs do Subversion a seus parceiros
como referncias aos documentos, e estas URLs sempre vo apontar para a verso mais recente do
documento. claro, voc ainda pode usar URLs como hiperlinks em outros web sites, tambm.
Com um navegador web comum? Em uma palavra: no. Ao menos, no com o mod_dav_svn
como sua nica ferramenta.
Seu navegador web entende apenas HTTP padro. Isso significa que ele apenas sabe como
obter (GET) URLs pblicas, as quais representam as ltimas verses dos arquivos e diretrios. De
acordo com a especificao WebDAV/DeltaV, cada servidor define uma sintaxe de URL particular
para verses mais antigas dos recursos, e esta sintaxe opaca aos clientes. Para encontrar uma
verso mais antiga de um arquivo, um cliente deve seguir um processo especfico para descobrir
a URL adequada; o procedimento envolve um conjunto de requisies PROPFIND do WebDAV
e a compreenso de conceitos do DeltaV. Isto algo que seu navegador web simplesmente no
consegue fazer.
Ento para responder pergunta, a maneira bvia de ver revises antigas de arquivos e diretrios
pela passagem do argumento --revision (-r) para os comando svn list e svn cat. Para
navegar em revises antigas com seu navegador web, entretanto, voc precisar usar software de
terceiros. Um bom exemplo disto o ViewVC (http://viewvc.tigris.org/). Originalmente o ViewVC
7
foi escrito para exibir repositrios CVS pela web, mas as verses mais recentes trabalham com
repositrios Subversion, tambm.
7
No incio, ele chamava-se ViewCVS.
158
Configurao do Servidor
Ao navegar em um repositrio Subversion, o navegador web obtm um indcio sobre como renderizar
o contedo do arquivo consultando o cabealho Content-Type: retornado na resposta da requisio
HTTP GET. O valor deste cabealho o valor de um tipo MIME. Por padro, o Apache vai indicar
aos navegadores web que todos os arquivos do repositrio so do tipo MIME default, usualmente
o tipo text/plain. Isto pode ser frustrante, entretanto, se um usurio quiser que os arquivos do
repositrio sejam renderizados como algo com mais significadopor exemplo, seria timo que um
arquivo foo.html pudesse ser renderizado como HTML na navegao.
Para fazer isto acontecer, voc s precisa garantir que seus arquivos tenham o svn:mime-
type adequadamente configurado. Isto discutido em mais detalhes em Tipo de Contedo do
Arquivo, a voc ainda pode configurar seu cliente para anexar as propriedades svn:mime-type
automaticamente aos arquivos que estejam entrando no repositrio pela primeira vez; veja Definio
Automtica de Propriedades.
Personalizando a Aparncia
Voc normalmente vai fazer mais uso das URLs para arquivos versionadosafinal, onde o contedo
interessante tende a estar. Mas pode haver certas situaes voc pode precisar navegar na listagem
de diretrios, no que voc rapidamente ir notar que o HTML gerado para exibir estas listagens
muito bsico, e certamente no pretende ser esteticamente agradvel (ou mesmo interessante). Para
possibilitar a personalizao destas exibies de diretrio, o Subversion prov um recurso de ndice
em XML. Uma nica diretiva SVNIndexXSLT no bloco Location do seu httpd.conf vai orientar o
mod_dav_svn a gerar sada XML ao exibir uma listagem de diretrio, e referenciar uma folha de estilos
XSLT sua escolha:
<Location /svn>
DAV svn
SVNParentPath /usr/local/svn
SVNIndexXSLT "/svnindex.xsl"
</Location>
Usando a diretiva SVNIndexXSLT e uma folha de estilos criativa, voc pode fazer com que suas
listagens de diretrios sigam os esquemas de cores e imagens usados em outras partes de seu
website. Ou, se voc preferir, voc pode usar folhas de estilo de exemplo que j vm no diretrio
tools/xslt dos fontes do Subversion. Tenha em mente que o caminho informado para o diretrio
em SVNIndexXSLT atualmente um caminho de URLos navegadores precisam conseguir ler suas
folhas de estilo para que possam fazer uso delas!
Listando Repositrios
Se voc est servindo um conjunto de repositrios a partir de uma nica URL por meio da diretiva
SVNParentPath, ento tambm possvel fazer o Apache exibir todos os repositrios disponveis
para o navegador web. Apenas ative a diretiva SVNListParentPath:
<Location /svn>
DAV svn
159
Configurao do Servidor
SVNParentPath /usr/local/svn
SVNListParentPath on
</Location>
Logs do Apache
Pelo fato de o Apache ser um servidor HTTP por vocao, ele possui recursos para log fantasticamente
flexveis. Est alm do escopo deste livro discutir todas as formas de log que podem ser configuradas,
mas ressaltamos que mesmo o arquivo httpd.conf mais genrico vai fazer com que o Apache
produza dois arquivos de log: error_log e access_log. Estes logs podem ficar em diferentes
lugares, mas comumente so criados na rea de logs de sua instalao do Apache. (No Unix, eles
frequentemente ficam em /usr/local/apache2/logs/.)
O error_log descreve quaisquer erros internos que ocorram com o Apache durante sua execuo.
J o arquivo access_log faz um registro de cada requisio recebida pelo Apache. Com isto fica fcil
de ver, por exemplo, quais endereos IP dos clientes Subversion que esto se conectando, com que
frequncia os clientes acessam o servidor, quais usurios esto devidamente autenticados, e quantas
requisies tiveram sucesso ou falharam.
Infelizmente, como o HTTP um protocolo sem informao de estado, mesmo a mais simples operao
de um cliente Subversion gera mltiplas requisies de rede. muito difcil olhar o arquivo access_log
e deduzir o que o cliente estava fazendomuitas operaes se parecem uma srie de obscuras
requisies PROPPATCH, GET, PUT, e REPORT. Para piorar as coisas, muitas operaes dos clientes
enviam conjuntos de requisies quase idnticas, ento ainda mais difcil diferenci-las.
O mod_dav_svn, entretanto, pode ajudar. Ativando um recurso de log operacional, voc pode pode
instruir o mod_dav_svn a criar arquivos de log separados os tipos de operaes em alto nvel que os
clientes esto executando.
Para fazer isso, voc precisa usar a diretiva CustomLog do Apache (a qual explicada em mais
detalhes na prpria documentao do Apache). Cuide para invocar esta diretiva fora do seu bloco
Location do Subversion:
<Location /svn>
DAV svn
</Location>
Neste exemplo, solicitamos ao Apache que crie um arquivo de log especial svn_logfile no diretrio
de logs padro do Apache. As variveis %t e %u so substitudas, respectivamente, pela hora e pelo
nome do usurio da requisio. A parte realmente importante aqui so as duas instncias de SVN-
ACTION. Quando o Apache v esta varivel, ele substitui o valor da varivel de ambiente SVN-ACTION,
que atribuda automaticamente pelo mod_dav_svn sempre que ele detecta uma ao do cliente em
alto nvel.
160
Configurao do Servidor
Outros Recursos
Vrios recursos j providos pelo Apache como um servidor Web robusto que tambm podem ser
aproveitadas para aprimorar as funcionalidades ou a segurana do Subversion. O Subversion se
comunica com o Apache usando o Neon, que uma biblioteca HTTP/WebDAV genrica com suporte
a alguns mecanismos como o SSL (Secure Socket Layer, discutida anteriormente). Se seu cliente
Subversion tiver sido compilado com suporte a SSL, ento ele pode acessar seu servidor Apache
usando https://.
Igualmente til so outros recursos da relao entre o Apache e o Subversion, como a capacidade
de se especificar uma porta especfica (ao invs da porta 80, padro HTTP) ou um nome de domnio
virtual a partir do qual um repositrio Subversion pode ser acessado, ou a capacidade de se acessar o
repositrio atravs de um proxy HTTP. Tudo isto suportado pelo Neon, ento, por tabela, o Subversion
tem suporte a tudo isto tambm.
Ambos os servidores usam um formato de arquivo comum para descrever estas regras de acesso
baseadas em caminhos. No caso do Apache, precisa-se carregar o mdulo mod_authz_svn e ento
adicionar-se a diretiva AuthzSVNAccessFile (dentro do arquivo httpd.conf) para apontar para
seu arquivo de regras. (Para uma descrio completa, veja Controle de Acesso por Diretrio.) Se voc
est usando o svnserve, ento voc precisa fazer a varivel authz-db (dentro do svnserve.conf)
apontar para seu arquivo de regras.
161
Configurao do Servidor
Muitos administradores que configuram o Subversion pela primeira vez tendem a usar controle de
acesso baseado em caminhos mesmo sem pensar muito sobre ele. O administrador comumente
sabe quais equipes de pessoas esto trabalhando em quais projetos, ento fcil considerar
isso e permitir que certas equipes acessem determinados diretrios e no outros. Parece uma
coisa natural, e isso at tranquiliza os desejos dos administradores de manter um controle rgido
do repositrio.
Perceba, porm, que sempre h custos invisveis (e visveis!) associados a este recurso. Quanto
aos custos visveis, tem-se que o servidor precisa de muito mas esforo para garantir que cada
usurio tenha o acesso correto de leitura ou escrita em cada caminho especfico; em certas
circunstncias, h uma sensvel perda de desempenho. Quanto aos custos invisveis, considere a
cultura que voc est criando. Na maior parte do tempo, ainda que certos usurios no devessem
estar registrando alteraes em certas partes do repositrio, este contrato social no precisa ser
reforado tecnologicamente. Algumas vezes as equipes podem colaborar umas com as outras
espontaneamente; algum pode querer ajudar a algum outro fazendo alteraes em alguma parte
na qual no trabalha normalmente. Ao prevenir este tipo de coisa a nvel de servidor, voc est
criando inesperadas barreiras colaborao. Voc tambm est criando um monte de regras que
devero ser mantidas conforme os projetos so desenvolvidos, novos usurios so adicionados,
e por a vai. muito trabalho extra para manter.
Lembre-se de que isto um sistema de controle de verso! Mesmo que algum acidentalmente
faa alguma alterao em algo que no deveria, fcil desfazer a alterao. E se um usurio
registrar uma modificao intencionalmente no lugar errado, isto um problema social de qualquer
maneira, e este um problema que precisar ser tratado fora do Subversion.
Ento antes de comear a restringir os direitos de acesso dos usurios, pergunte a si mesmo se
h uma razo real e legtima para isto, ou se no algo que apenas parece uma boa idia para
um administrador. Decida ainda se vale a pena sacrificar um pouco da velocidade do servidor, e
lembre-se que h muito pouco risco envolvido; ruim se tornar dependente da tecnologia como
8
uma muleta para problemas sociais .
Como um exemplo a considerar, veja que o prprio projeto Subversion sempre teve a noo de
quem tem permisso para realizar alteraes em que lugares, mas isto j o que acaba ocorrendo
na prtica. Este um bom modelo de confiana da comunidade, especialmente para projetos
open-source. De fato, algumas vezes h razes verdadeiramente legtimas para se ter controle
de acesso baseado em caminhos; em empresas, por exemplo, certos tipos de dados realmente
podem ser sensveis, aos quais os acessos precisam ser verdadeiramente restritos a pequenos
grupos de pessoas.
Uma vez que o servidor saiba onde encontrar seu arquivo de regras, hora de defin-las.
A sintaxe do arquivo aquela mesma sintaxe familiar usada no svnserve.conf e nos arquivos de
configurao em tempo de execuo. Linhas que comecem com cerquilha (#) so ignoradas. Em sua
forma mais simples, cada seo nomeia um repositrio e um caminho dentro dele, e os nomes de
usurios autenticados so os nomes das opes dentro de cada seo. O valor de cada opo descreve
o nvel de acesso dos usurios naquele caminho do repositrio: seja r (somente leitura) ou rw (leitura/
escrita). Se o usurio no for mencionado de forma nenhuma, nenhum acesso ser permitido.
Para ser mais especfico: o valor dos nomes das sees ou so da forma [repos-name:path] ou
da forma [path]. Se voc est usando a diretiva SVNParentPath, ento importante especificar os
nomes dos repositrios em suas sees. Se voc omit-los, ento uma seo como [/algum/dir] ir
corresponder ao caminho /algum/dir em cada repositrio. Se voc est usando a diretiva SVNPath,
porm, ento no h problema em definir apenas os caminhos em suas seesafinal de contas, h
apenas um repositrio.
8
Um tema recorrente neste livro!
162
Configurao do Servidor
[calc:/branches/calc/bug-142]
harry = rw
sally = r
Neste primeiro, o usurio harry tem completo acesso de leitura e escrita ao diretrio /branches/
calc/bug-142 no repositrio calc, mas o usurio sally tem acesso somente leitura. Quaisquer
outros usurios tm seu acesso a este repositrio bloqueado.
claro que as permisses so herdadas de um diretrio para um filho. Isto quer dizer que podemos
especificar um subdiretrio com uma poltica de acesso diferente para Sally:
[calc:/branches/calc/bug-142]
harry = rw
sally = r
Agora Sally pode escrever no subdiretrio testing do ramo, mas ainda continua tendo acesso
somente leitura a outras partes. Harry, no entanto, continua a ter acesso completo de leitura/escrita
ao ramo inteiro.
Tambm possvel negar permisso a alguns usurios atravs das regras de herana, removendo o
valor da varivel do nome do usurio:
[calc:/branches/calc/bug-142]
harry = rw
sally = r
[calc:/branches/calc/bug-142/secret]
harry =
Neste exemplo, Harry tem acesso completo leitura/escrita toda a rvore bug-142, mas no tem
absolutamente nenhum acesso em todo o subdiretrio secret dentro dela.
O que voc deve lembrar que a correspondncia sempre feita com os caminhos mais especficos
primeiro. O servidor tenta achar uma ocorrncia com o prprio caminho, ento depois com o caminho
do diretrio pai, e depois com o pai deste, e assim por diante. O efeito em rede que mencionando
um caminho especfico no arquivo de acesso sempre ir sobrescrever qualquer permisso herdada
dos diretrios pais.
Por padro, ningum tem acesso ao repositrio como um todo. Isto significa que se voc est iniciando
com um arquivo vazio, voc provavelmente quer pelo menos dar permisso de leitura a todos os
usurios na raiz do repositrio. Voc pode fazer isso usando a varivel asterisco (*), o que quer dizer
todos os usurios:
[/]
* = r
Esta uma configurao comum; note que no aparece o nome de nenhum repositrio no nome da
seo. Isto torna todos os repositrios legveis para todos os usurios. Uma vez que todos os usurios
tem acesso de leitura aos repositrios, voc pode dar permisses rw explcitas a certos usurios em
subdiretrios dentro de repositrios especficos.
A varivel asterisco (*) merece tambm um destaque especial aqui: o nico padro que corresponde
com o usurio annimo. Se voc configurou seu bloco servidor para permitir um misto de acesso
163
Configurao do Servidor
annimo e autenticado, todos os usurios iniciam acessando anonimamente. O servidor procura por
um valor * definido para o caminho sendo acessado; se encontrar, ento requisita autenticao efetiva
do cliente.
O arquivo de acesso tambm lhe possibilita definir grupos inteiros de usurios, tal como o arquivo /
etc/group do Unix:
[groups]
calc-developers = harry, sally, joe
paint-developers = frank, sally, jane
everyone = harry, sally, joe, frank, sally, jane
Controle de acesso pode ser definido para grupos da mesma forma como para usurios. Sendo que
os grupos se distinguem por tem um sinal de arroba (@) na frente:
[calc:/projects/calc]
@calc-developers = rw
[paint:/projects/paint]
@paint-developers = rw
jane = r
[groups]
calc-developers = harry, sally, joe
paint-developers = frank, sally, jane
everyone = @calc-developers, @paint-developers
Se voc est usando o Apache como seu servidor Subversion e deixou determinados
subdiretrios de seu repositrio ilegveis para certos usurios, ento voc precisa ter cuidado com
um possvel comportamento no-otimizado do comando svn checkout.
Quando o cliente realiza um checkout ou update sobre HTTP, ele faz uma nica requisio ao
servidor, e recebe uma nica resposta (quase sempre bem grande). Quando o servidor recebe a
requisio, que a nica oportunidade que o Apache tem de solicitar autenticao do usurio. Isto
tem alguns efeitos colaterais. Por exemplo, se um certo determinado subdiretrio do repositrio
legvel apenas pelo usurio Sally, e o usurio Harry d um checkout num diretrio pai, seu
cliente vai atender ao desafio de autenticao inicial como Harry. Como o servidor gera uma
resposta grande, no h uma forma de reenviar um desafio de autenticao quando encontrar
um subdiretrio especial; pulando assim este subdiretrio como um todo, em vez de solicitar
que o usurio se re-autentique como Sally no momento certo. De maneira similar, se a raiz do
repositrio legvel anonimamente por todos, ento todo checkout ser feito sem autenticao
novamente, pulando o diretrio legvel em vez de solicitar autenticao para ter acesso a essas
partes do repositrio.
164
Configurao do Servidor
A qualquer momento, estes processos podem demandar acesso de leitura e escrita ao seu repositrio:
usurios regulares do sistema, usando um cliente Subversion (como si prprios) para acessar o
repositrio diretamente por meio de URLs file://;
O problema mais comum que os administradores enfrentam diz respeito a propriedade e a permisses
do repositrio. Cada um dos processos (ou usurios) da lista anterior tem direito de ler e escrever
nos arquivos Berkeley DB da base de dados? Assumindo que voc esteja num sistema operacional
Unix-like, uma abordagem simples poderia ser colocar cada usurio do repositrio em potencial em
um novo grupo svn, e fazer com que o repositrio inteiro pertena a este grupo. Mas isso ainda no
o suficiente, porque um processo pode escrever nos arquivos da base de dados usando um valor de
umask problemticoque impossibilite o acesso de outros usurios.
Ento alm de definir um grupo comum para os usurios do repositrio, o prximo passo forar que
cada processo que acesse o repositrio use um valor adequado de umask. Para usurios que acessam
o repositrio diretamente, voc pode transformar o programa svn em um script que primeiro defina
umask 002 e ento execute o programa cliente svn real. Voc pode escrever um script semelhante para
o programa svnserve, e adicionar um comando umask 002 ao prprio script de script de inicializao
do Apache, apachectl. Por exemplo:
$ cat /usr/bin/svn
#!/bin/sh
umask 002
/usr/bin/svn-real "$@"
Uma vez realizados estes passos, seu repositrio deve ser acessvel para todos os processos
necessrios. Pode parecer um pouco confuso e complicado, mas os problemas de ter mltiplos usurios
compartilhando acesso de escrita a arquivos comuns so problemas clssicos e que muitas vezes no
so resolvidos de maneira muito elegante.
165
Configurao do Servidor
Pode ser um pouco complicado fazer com que uma poro de usurios com contas SSH
existentes compartilhem um repositrio sem problemas de permisso. Se voc est confuso sobre
todas as coisas que voc (como um administrador) precisa fazer em um sistema Unix-like, aqui
est um breve checklist que resume algumas das coisas discutidas nesta seo:
Todos os seus usurios SSH precisam ser capazes de ler e escrever no repositrio, ento:
ponha todos os usurios SSH em um mesmo grupo.
Seus usurios precisar usar um valor de umask adequado ao acessar o repositrio, ento:
confirme que o svnserve (/usr/bin/svnserve), ou onde quer que ele esteja no $PATH) seja
atualmente um script que encapsule umask 002 e execute o binrio svnserve real.
166
Captulo 7. Customizando sua
Experincia com Subversion
Controle de verso pode ser um tema complexo, assim como arte ou cincia, e oferecer variadas
maneiras fazer as coisas. Atravs desse livro voc leu sobre vrios subcomandos do cliente de linha
de comando e as opes para modificar seu comportamento. Nesse captulo, vamos dar uma olhada e
mais maneiras de customizar o jeito que o Subversion trabalha para vocdefinindo as configuraes
em tempo de execuo, usando ajuda de aplicaes externas, a interao do Subversion com as
configuraes locais do sistema operacional, e assim por diante.
A rea de configurao do Subversion uma hierarquia de opes com nomes e seus valores, em dois
nveis. Normalmente, isto resume-se a um diretrio especial que contm arquivos de configurao (o
primeiro nvel), os quais so apenas arquivos de texto no formato padro INI (com sees provendo
o segundo nvel). Estes arquivos podem ser facilmente editados usando seu editor de texto favorito
(como Emacs ou vi), e contm diretivas que so lidas pelo cliente para determinar quais dos vrios
comportamentos opcionais o usurio prefere.
Alm da rea de configurao por usurio, o Subversion tambm reconhece a existncia de uma
rea de configurao a nvel de sistema. Isto oferece aos administradores de sistema a habilidade
de estabelecer padres para todos usurios em uma determinada mquina. Note que a rea de
configurao a nvel de sistema no define uma poltica obrigatriaas definies na rea de
configurao do usurio substitui as de nvel de sistema, e os argumentos de linha de comando
passados ao programa svn possuem a palavra final no comportamento realizado. Em plataformas
Unix, espera-se que a rea de configurao do sistema esteja no diretrio /etc/subversion; em
mquinas Windows, ela aparece em um diretrio Subversion dentro do local Application Data
do sistema (novamente, como especificado pelo Registro do Windows). Diferentemente do caso por
usurio, o programa svn no tenta criar a rea de configurao a nvel de sistema.
A rea de configurao por usurio atualmente contm trs arquivosdois arquivos de configurao
(config e servers), e um arquivo README.txt que descreve o formato INI. Quando so criados,
os arquivos contm valores padro para cada uma das opes suportadas pelo Subversion, a maioria
1
A varivel de ambiente APPDATA aponta para a rea Application Data, assim voc sempre pode referir a esta pasta como
%APPDATA%\Subversion.
167
Customizando sua
Experincia com Subversion
comentadas e agrupadas com descries textuais sobre como os valores para as chaves afetam o
comportamento do Subversion. Para mudar um certo comportamento, voc apenas precisa carregar o
arquivo de configurao apropriado em um editor de texto, e modificar o valor da opo desejada. Se,
a qualquer momento, voc desejar ter as definies da configurao padro restauradas, voc pode
simplesmente remover (ou renomear) seu diretrio de configurao e ento executar algum comando
svn inofensivo, como o svn --version. Um novo diretrio de configurao com o contedo padro ser
criado.
A rea de configurao por usurio tambm contm uma cache dos dados de autenticao. O diretrio
auth possui um conjunto de subdiretrios que contm pedaos das informaes armazenadas e
usadas pelos vrios mtodos de autenticao suportados pelo Subversion. Este diretrio criado de
tal forma que somente o prprio usurio possui permisso para ler seu contedo.
O cliente de linha de comando, svn, tenta escrever no registro do Windows, e ento no tentar
escrever uma rea de configurao padro. Voc pode criar as chaves que voc precisa usando o
programa REGEDIT. Alternativamente, voc pode criar um arquivo .reg, e ento dar um duplo clique
nele a partir do Windows Explorer, o que ir fazer com que os dados sejam mesclados ao seu registro.
168
Customizando sua
Experincia com Subversion
REGEDIT4
[HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\groups]
[HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\global]
"#http-proxy-host"=""
"#http-proxy-port"=""
"#http-proxy-username"=""
"#http-proxy-password"=""
"#http-proxy-exceptions"=""
"#http-timeout"="0"
"#http-compression"="yes"
"#neon-debug-mask"=""
"#ssl-authority-files"=""
"#ssl-trust-default-ca"=""
"#ssl-client-cert-file"=""
"#ssl-client-cert-password"=""
[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auth]
"#store-passwords"="yes"
"#store-auth-creds"="yes"
[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\helpers]
"#editor-cmd"="notepad"
"#diff-cmd"=""
"#diff3-cmd"=""
"#diff3-has-program-arg"=""
[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\tunnels]
[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\miscellany]
"#global-ignores"="*.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store"
"#log-encoding"=""
"#use-commit-times"=""
"#no-unlock"=""
"#enable-auto-props"=""
[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auto-props]
O exemplo anterior mostra o contedo de um arquivo .reg que contm algumas das opes de
configurao mais comuns e seus valores padro. Note a presena tanto de configuraes em nvel
de sistema (para opes relacionadas a proxies de rede) e configuraes especficas por usurio
(programa editor de texto e armazenamento de senhas, entre outras). Tambm note que todas as
opes esto efetivamente comentadas. Voc precisa apenas remover o caractere de cerquilha (#) do
comeo dos nomes das opes, e definir os valores como voc quiser.
Opes de Configurao
Nesta seo, vamos discutir as opes de configurao especficas de tempo de execuo que so
atualmente suportadas pelo Subversion.
169
Customizando sua
Experincia com Subversion
Servidores
O arquivo servers contm opes de configurao relacionadas camada de rede. H dois nomes de
seo neste arquivogroups e global. A seo groups essencialmente uma tabela de referncia
cruzada. As chaves nesta seo so os nomes de outras sees no arquivo; seus valores so globs
indicadores textuais que possivelmente podem conter caracteres coringaque so comparados com
os nomes de hosts das mquinas s quais as requisies do Subversion so enviadas.
[groups]
beanie-babies = *.red-bean.com
collabnet = svn.collab.net
[beanie-babies]
[collabnet]
Quando o Subversion usado em rede, ele tenta casar o nome do servidor ao qual est tentando
alcanar com o nome do grupo na seo groups. Se encontrar uma correspondncia, o Subversion
ento procura por uma seo no arquivo servers com o mesmo nome do grupo em questo. A partir
dessa seo, ele l as configuraes de rede atuais.
A seo global contm as configuraes que so feitas para todos os servidores para os quais
no haja correspondncia na seo groups. As opes disponveis nesta seo so exatamente as
mesmas que aquelas vlidas para outras sees de servidores no arquivo (exceto, claro, a seo
especial groups), e so como o que se segue:
http-proxy-exceptions
Isto especifica uma lista de padres de nomes de hosts separados por vrgulas e que devem
ser acessados diretamente, sem que seja por meio de uma mquina de proxy. A sintaxe desses
padres a mesma que utilizada no shell do Unix para nomes de arquivos. Um nome de host de um
repositrio que corresponda a qualquer desses padres no ser acessado atravs de um proxy.
http-proxy-host
Isto especifica o nome do host do computador proxy atravs do qual suas requisies HTTP para
o Subversion devem passar. Seu padro um valor vazio, o que significa que o Subversion no
tentar rotear requisies HTTP atravs de um computador proxy, ao invs disso tentando acessar
a mquina de destino diretamente.
http-proxy-port
Isto especifica o nmero de porta a ser usada no host proxy. Seu valor padro tambm vazio.
http-proxy-username
Isto especifica o nome de usurio a ser informado para a mquina proxy. Seu valor padro vazio.
http-proxy-password
Isto especifica a senha do usurio a ser informada para a mquina proxy. Seu valor padro vazio.
http-timeout
Isto especifica o total de tempo, em segundos, a aguardar por uma resposta do servidor. Se voc
tiver problemas com uma conexo de rede lenta e que faam com que as operaes do Subversion
terminem por expirao do limite de tempo, voc deveria aumentar o valor desta opo. O valor
padro 0, o que instrui a biblioteca HTTP da camada inferior, a Neon, para usar sua prpria
configurao de limite de tempo.
http-compression
Isto especifica se o Subversion deve ou no tentar compactar as requisies de rede feitas a
servidores compatveis com DAV. O valor padro yes (ainda que a compactao s ir ocorrer
170
Customizando sua
Experincia com Subversion
se o suporte a este recurso estiver compilado na camada de rede). Atribua a esta opo o valor no
para desabilitar compactao, por exemplo ao depurar transmisses de rede.
neon-debug-mask
Isto uma mscara inteira que a biblioteca HTTP da camada inferior, a Neon, utiliza para escolher
que tipo de sada de depurao ela deve gerar. O valor padro 0, que ir silenciar toda a sada
de depurao. Para mais informaes sobre como o Subversion faz uso da biblioteca Neon, veja
Captulo 8, Incorporando o Subversion.
ssl-authority-files
Isto uma lista de caminhos delimitada por pontos-e-vrgulas, para os arquivos que contenham
certificados das autoridades certificadoras (as ACs) que so aceitas pelo cliente Subversion quando
acessando repositrios sob HTTPS.
ssl-trust-default-ca
Defina esta varivel para yes se voc quer que o Subversion confie automaticamente no conjunto
padro de ACs que vm com o OpenSSL.
ssl-client-cert-file
Se um host (ou um conjunto de hosts) necessitar de um certificado SSL de cliente, voc
provavelmente ser solicitado a informar um caminho para seu certificado. Ao definir esta
varivel para o mesmo caminho, o Subversion ser capaz de encontrar seu certificado de cliente
automaticamente sem precisa lhe solicitar esta informao. No h um local padronizado para
armazenar seu certificado de cliente no disco; o Subversion conseguir l-lo a partir de qualquer
caminho que voc especificar.
ssl-client-cert-password
Se seu arquivo do certificado de cliente SSL estiver criptografado com uma frase-senha, o
Subversion ir lhe pedir que voc fornea a frase-senha toda vez que certificado for usado. Se voc
achar isto um estorvo (e se no se importa em deixar a senha armazenada no arquivo servers),
ento voc pode definir esta varivel para a frase-senha do certificado. Assim, esta informao
no mais lhe ser solicitada.
Configurao
O arquivo config contm as demais opes em tempo de execuo atualmente disponveis no
Subversion, estas no relacionadas conexo de rede. H apenas algumas poucas opes em uso
at o momento em que este livro estava sendo escrito, mas elas ainda so agrupadas em sees na
expectativa para adies futuras.
store-passwords
Isto orienta o Subversion a armazenar, ou no, em cache as senhas que so informadas pelo
usurio em resposta a desafios de autenticao do servidor. O valor padro yes. Altere seu
valor para no para desabilitar este recurso de cache de senhas em disco. Voc pode sobrescrever
esta opo para uma nica instncia do comando svn usando o parmetro --no-auth-cache de
linha de comando (para os subcomandos que dem suporte a ele). Para mais informaes, veja
Armazenando Credenciais no Cliente.
store-auth-creds
Esta configurao idntica a store-passwords, exceto que ela habilita ou desabilita o cache
em disco de todas as informaes de autenticao: nomes de usurio, senhas, certificados de
servidor, e quaisquer outros tipos de credenciais armazenveis.
A seo helpers controla quais aplicaes externas o Subversion usa como suporte na execuo de
suas tarefas. Opes vlidas nesta seo so:
171
Customizando sua
Experincia com Subversion
editor-cmd
Isto especifica o programa que o Subversion ir usar para solicitar uma mensagem longa ao usurio
durante uma operao de submisso, como ao usar svn commit sem as opes --message (-
m) ou --file (-F). Este programa tambm usado com o comando svn propeditum arquivo
temporrio preenchido com o valor atual da propriedade que o usurio pretende editar, e permite
que o usurio realize as modificaes neste programa editor (veja Propriedades). O valor padro
para esta opo vazio. A ordem de prioridade para determinar o comando editor (em ordem
crescente de precedncia) :
diff-cmd
Isto especifica o caminho absoluto para um programa de diferenciao, usado quando o Subversion
gera sada em formato diff (como ao usar o comando svn diff). Por padro, o Subversion usa uma
biblioteca interna de diferenciaoatribuir um valor a esta opo ir fazer com que o Subversion
realize essa tarefa executando um programa externo. Veja Usando Ferramentas Externas de
Diferenciao para mais detalhes sobre como usar tais programas.
diff3-cmd
Isto especifica o caminho absoluto para um programa de diferenciao em trs vias. O Subversion
usa este programa para mesclar alteraes feitas pelo usurio com aquelas recebidas do
repositrio. Por padro, o Subversion usa uma biblioteca interna de diferenciaoatribuir um valor
a esta opo ir fazer com que o Subversion execute esta tarefa usando um programa externo.
Veja Usando Ferramentas Externas de Diferenciao para mais detalhes sobre como usar tais
programas.
diff3-has-program-arg
Esta opo deve ser atribuda para true se o programa especificado pela opo diff3-cmd
aceitar um parmetro --diff-program de linha de comando.
A seo tunnels permite que voc defina um novo esquema de tnel para uso com o svnserve e
clientes de conexes svn://. Para mais detalhes, veja Tunelamento sobre SSH.
A seo miscellany onde se encontram todas aquelas opes que no pertenam a nenhuma das
2
outras sees. Nesta seo, voc pode encontrar:
global-ignores
Ao executar o comando svn status, o Subversion lista arquivos e diretrios no-versionados
juntamente com os versionados, marcando-os com um caractere ? (veja Obtendo uma viso geral
de suas alteraes). Algumas vezes, pode ser chato ficar sempre vendo itens no-versionados,
desinteressantespor exemplo, arquivos objeto que resultantes da compilao de um programa
na tela. A opo global-ignores uma lista de campos delimitados por espaos e que
descrevem os nomes de arquivos e diretrios que o Subversion no deveria exibir a no ser
2
Algum para um jantar improvisado?
172
Customizando sua
Experincia com Subversion
apenas quando versionados. Seu valor padro *.o *.lo *.la #*# .*.rej *.rej .*~
*~ .#* .DS_Store.
Bem como o svn status, os comandos svn add e svn import tambm ignoram arquivos que
correspondam com esta lista quando esto escaneando um diretrio. Voc pode sobrescrever
este comportamento para uma nica instncia de qualquer desses comandos especificando
explicitamente o nome do arquivo ou usando a opo --no-ignore em linha de comando.
Para mais informao sobre controle granularizado de itens ignorados, veja Ignorando Itens No-
Versionados.
enable-auto-props
Isto faz com que o Subversion defina propriedades automaticamente em novos arquivos
adicionados ou importados. Seu valor padro no, altere-o para yes para habilitar propriedades
automticas. A seo auto-props deste arquivo especifica quais propriedades sero definidas
em quais arquivos.
log-encoding
Esta varivel define a codificao de caracteres padro para mensagens de log de submisses.
uma verso permanente da opo --encoding (veja Opes do svn). O repositrio Subversion
armazena mensagens de log em UTF-8, e assume que suas mensagens de log sejam escritas
usando a localizao nativa do sistema operacional. Voc deve especificar uma codificao
diferente se suas mensagens de commit forem escritas em um outro conjunto de caracteres.
use-commit-times
Normalmente, os arquivos de sua cpia de trabalho tm registros de tempo que refletem o momento
da ltima vez em que eles foram referenciados ou alterados por algum processo, que pode ser seu
prprio editor ou mesmo algum subcomando do svn. Isto geralmente conveniente para pessoas
que desenvolvem software, porque sistemas de compilao quase sempre verificam registros de
tempo como uma forma de decidir quais arquivos precisam ser recompilados.
Em outras situaes, porm, algumas vezes bom ter registros de tempo de arquivos na cpia
de trabalho que reflitam a ltima vez em que eles foram modificados no repositrio. O comando
svn export sempre pe estes registros de tempo do ltimo commit nas rvores geradas por ele.
Ao definir esta varivel de configurao para yes, os comandos svn checkout, svn update, svn
switch, e svn revert passaro a registrar momentos de tempo dos comandos de ltimo commit
nos arquivos que manipularem.
Localizao
Localizao o ato de fazer com que programas comportem-se de um modo especfico de regio.
Quando um programa formata nmeros ou datas em um modo especfico para sua parte do mundo, ou
imprime mensagens (ou aceita uma entrada) em sua linguagem nativa, o programa dito ser localizado.
Esta seo descreve os passos que o Subversion tem feito a respeito de localizao.
Compreendendo localidades
A maioria dos sistemas operacionais modernos tm uma noo da localidade atualisto , a regio ou
pas cujas convenes de localizao so aplicadas. Estas convenesnormalmente escolhidas por
173
Customizando sua
Experincia com Subversion
Na maioria dos sistemas Unix, voc pode verificar os valores das opes de configurao relacionadas
localidade pela execuo do comando locale:
$ locale
LANG=
LC_COLLATE="C"
LC_CTYPE="C"
LC_MESSAGES="C"
LC_MONETARY="C"
LC_NUMERIC="C"
LC_TIME="C"
LC_ALL="C"
A sada uma lista de variveis de ambiente, relacionadas com a localidade, e seus valores atuais.
Neste exemplo, as variveis esto todas definidas com o local padro C, mas os usurios podem definir
estas variveis para especificar combinaes de cdigo pas/idioma. Por exemplo, se algum quisesse
definir a varivel LC_TIME com o valor fr_CA, ento os programas saberiam apresentar informaes
de data e hora formatadas de acordo com a expectativa de um Canadense que fala Francs. E se
algum quisesse definir a varivel LC_MESSAGES com o valor zh_TW, ento os programas saberiam
apresentar mensagens legveis em Chins Tradicional. Configurar a varivel LC_ALL tem o efeito de
modificar todas as variveis de localidade para o mesmo valor. O valor de LANG utilizado como um
valor padro para qualquer varivel de localidade que est indefinida. Para ver a lista de localidades
disponveis em um sistema Unix, execute o comando locale -a.
No Windows, a configurao de localidade feita por meio do item Opes Regionais e de Idioma
no painel de controle. L voc poder ver e selecionar os valores das configuraes individuais
das localidades disponveis, e at mesmo personalizar (a um nvel de detalhe enjoativo) vrias das
convenes de formatao de exibio.
$ export LC_MESSAGES=de_DE
$ svn help cat
cat: Gibt den Inhalt der angegebenen Dateien oder URLs aus.
Aufruf: cat ZIEL[@REV]...
Este comportamento ocorre identicamente tanto em sistemas Unix quando em Windows. Note,
entretanto, que enquanto seu sistema operacional possa ter suporte para uma certa localidade, o
cliente do Subversion ainda pode no estar hbil para falar com o idioma especfico. A fim de produzir
mensagens localizadas, pessoas voluntrias podem fornecer tradues para cada linguagem. As
tradues so escritas usando o pacote GNU gettext, que resultam em mdulos de traduo que
terminam com a extenso .mo no nome do arquivo. Por exemplo, o arquivo de traduo para o Alemo
nomeado de.mo. Estes arquivos de traduo esto instalados em algum lugar em seu sistema.
No Unix, eles normalmente ficam em /usr/share/locale/, enquanto que no Windows eles so
frequentemente encontrados na pasta \share\locale\ na rea de instalao do Subversion. Uma
vez instalado, um mdulo que contm o nome do programa que fornece as tradues. Por exemplo, o
arquivo de.mo pode vir a ser finalmente instalado como /usr/share/locale/de/LC_MESSAGES/
subversion.mo. Ao navegar pelos arquivos .mo instalados, voc pode ver quais linguagens o cliente
Subversion est hbil para falar.
174
Customizando sua
Experincia com Subversion
A segunda forma na qual a localidade aplicada envolve como o svn interpreta suas entradas.
O repositrio armazena todos os caminhos, nomes de arquivo, e mensagens de log em Unicode,
codificadas como UTF-8. Nesse sentido, o repositrio est internacionalizadoisto , o repositrio est
pronto para aceitar entradas em qualquer linguagem humana. Isso significa, contudo, que o cliente do
Subversion responsvel por enviar somente nomes de arquivos e mensagens de log em UTF-8 para
o repositrio. Para isso, ele deve converter os dados a partir da localidade nativa em UTF-8.
Por exemplo, suponha que voc criou uma arquivo chamado caff.txt, e ento ao submeter o
arquivo, voc escreve a mensagem de log como Adesso il caff pi forte. Tanto o nome do arquivo
quanto a mensagem de log contem caracteres no-ASCII, porm, sua localidade est definida como
it_IT, e o cliente Subversion sabe interpret-los como Italiano. Ele usa um conjunto de caracteres do
Italiano para converter os dados para UTF-8 antes de envi-los para o repositrio.
Observe que, enquanto o repositrio demanda nomes de arquivo e mensagens de log em UTF-8, ele
no presta ateno ao contedo do arquivo. O Subversion trata o contedo do arquivo como sequncias
de bytes quaisquer, e nem o cliente nem servidor fazem uma tentativa de entender o conjunto de
caracteres ou codificao do contedo.
Quando estiver usando o Subversion, voc pode receber um erro relacionado a converses de
conjuntos de caractere:
Erros como estes normalmente ocorrem quando o cliente do Subversion recebeu uma sequncia
UTF-8 do repositrio, mas nem todos os caracteres nesta sequncia podem ser representados
usando a codificao da localidade atual. Por exemplo, se sua localidade en_US mas um
colaborador submeteu um nome de arquivo em Japons, voc provavelmente ver este erro
quando for receber o arquivo durante um svn update.
A soluo est tanto em definir sua localidade para alguma que possa representar os dados
UTF-8 recebidos, ou modificar o nome do arquivo ou mensagem de log dentro do repositrio.
(E no esquea de dar uma bofetada na mo de seu colaboradoros projetos devem decidir o
quanto antes as linguagens comuns, para que todos participantes estejam utilizando a mesma
localidade.)
A interface entre o Subversion e ferramentas externas de diferenciao e fuso remontam a uma poca
em que as nicas capacidades de diferenciao do Subversion eram construdas sobre invocaes
de utilitrios do kit de ferramentas diffutils do GNU, especificamente os utilitrios diff e diff3. Para
conseguir o tipo de comportamento de que o Subversion precisa, ele chamava esses utilitrios com
mais algumas opes e parmetros teis, muitas das quais eram bastante especficas desses utilitrios.
Algum tempo depois, o Subversion desenvolveu-se com sua prpria biblioteca de diferenciao, e com
175
Customizando sua
Experincia com Subversion
3
mecanismos de recuperao de falhas, as opes --diff-cmd e --diff3-cmd foram adicionadas
ao cliente de linha de comando do Subversion e ento os usurios puderam indicar com mais
facilidade se preferiam usar os utilitrios GNU diff e diff3 ao invs da nova biblioteca biblioteca interna
de diferenciao. Se essas opes forem usadas, o Subversion dever simplesmente ignorar sua
biblioteca interna de diferenciao, voltando a usar programas externos, longas listas de argumentos
e tudo o mais. E assim que as coisas permanecem at hoje.
No demora muito para as pessoas perceberem que dispor de tais mecanismos de configurao para
especificar que o Subversion deve usar os utilitrios GNU diff e diff3 localizados em um local especfico
no sistema poderia ser aplicado tambm para o uso de outras ferramentas de diferenciao e fuso.
No fim das contas, o Subversion atualmente nem verifica se as coisas que mencionamos executar
eram membros do kit de ferramentas GNU diffutils. Mas o nico aspecto configurvel ao usar estas
ferramentas externas a sua localizao no sistemae no o conjunto de opes, parmetros, ordem,
etc. O Subversion continua incluindo todas essas opes de utilitrios GNU sua ferramenta externa
de diferenciao independentemente se o programa em questo pode entender tais opes ou no. E
aqui que as coisas deixam de ser intuitivas para a maioria dos usurios.
O ponto chave ao usar ferramentas externas de diferenciao e fuso com o Subversion (que no as diff
e diff3 do kit GNU, claro) usar scripts encapsuladores que convertam a entrada do Subversion em
algo que sua ferramenta de diferenciao possa entender, e ento converter a sada de sua ferramenta
de volta num formato esperado pelo Subversiono formato que as ferramentas GNU deveriam usar.
As sees seguintes abordam os detalhes sobre esses formatos.
A deciso sobre quando disparar uma diferenciao ou fuso contextual como parte de
uma operao maior do Subversion feita inteiramente pelo Subversion, e afetada por,
entre outras coisas, se os arquivos em questo sobre os quais o sistema estiver operando
estiver ou no em um formato legvel por humanos como determinado a partir de sua
propriedade svn:mime-type. Isto quer dizer, por exemplo, que mesmo que se voc tiver
a ferramenta ou plugin de diferenciao ou fuso do Microsoft Word mais esperta do
universo, ela nunca deveria ser invocada pelo Subversion se seus documentos do Word
sob controle de verso possurem um tipo MIME configurado que denote que eles no so
legveis por humanos (tal como application/msword). Para mais informaes sobre
configuraes de tipos MIME, veja Tipo de Contedo do Arquivo
Exemplo 7.2, diffwrap.sh e Exemplo 7.3, diffwrap.bat so modelos para scripts encapsuladores para
ferramentas diff externas, em formato de arquivos shell Bourne e batch do Windows, respectivamente.
3
Os desenvolvedores do Subversion so muito bons, mas at os melhores s vezes comentem erros.
4
A pgina de manual do GNU diff descreve isso da seguinte forma: Uma sada de status de 0 significa que no foram encontradas
diferenas, 1 significa que algumas diferenas foram encontradas, e 2 significa problemas.
176
Customizando sua
Experincia com Subversion
#!/bin/sh
@ECHO OFF
REM Chama o comando diff (modifique a linha a seguir de acordo com seu
REM programa).
%DIFF% --left %LEFT% --right %RIGHT%
177
Customizando sua
Experincia com Subversion
Exemplo 7.4, diff3wrap.sh e Exemplo 7.5, diff3wrap.bat so modelos para scripts encapsuladores
para ferramentas de fuso de texto externas, em formato de arquivos shell Bourne e batch do Windows,
respectivamente.
#!/bin/sh
@ECHO OFF
REM O Subversion dispe dos caminhos que precisamos como o nono, dcimo e
REM dcimo primeiro parmetros. Mas s temos acesso a nove parmetros de
REM cada vez, ento deslocamos nosso nove parmetros duas vezes para que
REM possamos obter os valores que precisamos.
SHIFT
SHIFT
SET MINE=%7
SET OLDER=%8
SET YOURS=%9
178
Captulo 8. Incorporando o
Subversion
O Subversion tem uma estrutura modular: ele implementado como uma coleo de bibliotecas escritas
em C. Cada biblioteca tem um propsito bem definido e uma Interface de Programao de Aplicao
(API - Application Programming Interface), e esta interface est disponvel no s para o prprio
Subversion usar, mas para qualquer software que queira incorporar ou controlar o Subversion atravs
de programao. Adicionalmente, a API do Subversion est disponvel no s para outros programas
em C, mas tambm para programas em linguagens de alto nvel como Python, Perl, Java ou Ruby.
Este captulo para aqueles que desejam interagir com o Subversion atravs da sua API pblica
ou seus vrios vnculos de linguagem. Se voc deseja escrever scripts robustos ao redor das
funcionalidades do Subversion para simplificar sua vida, se est tentando desenvolver integraes mais
complexas entre o Subversion e outras partes de um software, ou apenas tem interesse nas vrias
bibliotecas modulares e o que elas tem a oferecer, este captulo para voc. Se, entretanto, voc no
se v participando com o Subversion nesse nvel, sinta-se livre para pular este captulo certo que suas
experincias como usurio do Subversion no sero afetadas.
libsvn_client
Interface primria para programas cliente
libsvn_delta
Rotinas de diferenciao de rvore e fluxo de bytes
libsvn_diff
Rotinas de diferenciao e mesclagem contextuais
libsvn_fs
Base comum e carregador de mdulo para sistema de arquivos
libsvn_fs_base
A base para sistema de arquivos do Berkeley DB
libsvn_fs_fs
A base para sistema de arquivos nativo (FSFS)
libsvn_ra
Base comum e carregador de mdulo para Acesso ao Repositrio
libsvn_ra_dav
O mdulo para Acesso ao Repositrio por WebDAV
libsvn_ra_local
O mdulo de Acesso ao Repositrio localmente
libsvn_ra_serf
Outro mdulo (experimental) para Acesso ao Repositrio por WebDAV
libsvn_ra_svn
O mdulo de Acesso ao Repositrio do protocolo padro
179
Incorporando o Subversion
libsvn_repos
Interface de Repositrio
libsvn_subr
Diversas sub-rotinas teis
libsvn_wc
A biblioteca de gerenciamento de cpia de trabalho
mod_authz_svn
Mdulo de autorizao do Apache para acesso a repositrios do Subversion via WebDAV
mod_dav_svn
Mdulo Apache para mapeamento de operaes WebDAV para operaes do Subversion
O fato da palavra diversas s aparecer uma vez na lista anterior um bom sinal. A equipe de
desenvolvimento do Subversion se esfora bastante para fazer com que as funcionalidades fiquem
na camada certa e nas bibliotecas certas. Talvez a maior vantagem de um sistema modular a
pouca complexidade do ponto de vista do desenvolvedor. Como desenvolvedor, voc pode enxergar
rapidamente um tipo de grande figura que permite voc achar o local de certos pedaos de
funcionalidade com certa facilidade.
Outro benefcio da modularidade a habilidade de substituir um dado mdulo por uma biblioteca
inteiramente nova que implementa a mesma API sem afetar o resto do cdigo base. De certo modo,
isso j acontece dentro do Subversion. Cada uma das bibliotecas libsvn_ra_dav, libsvn_ra_local,
libsvn_ra_serf, e libsvn_ra_svn implementam a mesma interface, todas funcionando como extenses
de libsvn_ra. E todas as quatro se comunicam com a Camada de Repositriolibsvn_ra_local conecta-
se ao repositrio diretamente; as outras trs atravs de uma rede. As bibliotecas libsvn_fs_base e
libsvn_fs_fs so outro par de bibliotecas que implementam a mesma funcionalidade de maneiras
diferentesambas so extenses para a biblioteca libsvn_fs comum.
Camada de Repositrio
Quando referirmos Camada de Repositrio do Subversion, estamos geralmente falando sobre dois
conceitos bsicosa implementao de sistema de arquivos versionados (acessada via libsvn_fs, e
suportada por suas extenses libsvn_fs_base e libsvn_fs_fs), e a lgica do repositrio que a encapsula
(implementada em libsvn_respos). Estas bibliotecas provem os mecanismos de armazenamento e
relatrios para as vrias revises de seus dados em controle de verso. Esta camada est conectada
com a Camada de Cliente atravs da Camada de Acesso ao Repositrio, e , da da perspectiva do
usurio Subversion, a coisa no outro extremo da linha.
180
Incorporando o Subversion
projetos: eles anunciaram em meados de 2006 que os membros de sua equipe Open Source teriam
escrito uma nova extenso proprietria para o sistema de arquivos do Subversion que usaria seu banco
de dados ultra-escalvel Bigtable em seu armazenamento.
A API de sistema de arquivos exportada por libsvn_fs contm os tipos de funcionalidade que voc
esperaria de qualquer outra API de sistema de arquivosvoc pode criar e remover arquivos e
diretrios, copiar e mov-los, modificar o contedo de arquivos, e assim por diante. Ela tambm
tem funcionalidades que no so to comuns, como a habilidade de adicionar, modificar, e remover
metadados (propriedades) em cada arquivo ou diretrio. Alm de tudo, o Sistema de Arquivos
Subversion um sistema de versionamento, o que significa que assim que voc faz mudanas em sua
rvore de diretrios, o Subversion lembra como sua rvore estava quando essas mudanas ocorreram.
E as mudanas anteriores. E as anteriores a essas. E assim por diante, todo o caminho de volta durante
o tempo de versionamento at (e no mximo) o primeiro momento em que voc iniciou a adio de
coisas ao sistema de arquivos.
Todas as modificaes que voc fez em sua rvore so feitas dentro do contexto de uma transao
de submisso do Subversion. A seguir veremos uma rotina simplificada e genrica de modificao de
seu sistema de arquivos:
Uma vez que voc submeteu sua transao, suas modificaes no sistema de arquivo so
permanentemente armazenadas como artefatos de histrico. Cada um desses ciclos produz uma nica
e nova reviso de sua rvore, e cada reviso ser sempre acessvel como uma imagem imutvel de
como as coisas estavam.
A noo de transao no Subversion pode ser facilmente confundida com o suporte a transaes
oferecido pelo banco de dados encapsulado propriamente dito, especialmente pelo cdigo de
libsvn_fs_base se aproximar ao cdigo do banco de dados Berkeley DB. Ambos os tipos de
transao existem para prover atomicidade e isolamento. Em outra palavras, transaes do a
voc a habilidade de realizar um conjunto de aes em uma forma tudo ou nadaou todas as
aes so completadas com sucesso, ou todas so tratadas como se nenhuma delas tivesse
ocorridoe em modo que no exista interferncia com outros processos atuando nos dados.
Felizmente para os usurios da API de sistema de arquivos, o suporte a transao provido pelo
sistema de banco de dados est quase totalmente escondido para exibio (como seria esperado
de um esquema de bibliotecas devidamente modularizadas). Apenas quando voc comea a
procurar dentro da implementao do prprio sistema de arquivos que essas coisas comeam a
ficar visveis (ou interessantes).
A maioria das funcionalidades providas pela interface de sistema de arquivos lida com aes que
ocorrem em caminhos de sistema de arquivos individuais. Isto , de fora do sistema de arquivos, o
mecanismo primrio para descrever e acessar as revises individuais de arquivos e diretrios vem
atravs do uso de de caminhos como /foo/bar, como se voc estivesse endereando arquivos e
diretrios atravs de seu programa de terminal favorito. Voc adiciona novos arquivos e diretrios
181
Incorporando o Subversion
passando seus futuros caminhos para as funes certas da API. Voc requisita informaes sobre eles
pelo mesmo mecanismo.
A diferena aqui que o sistema de arquivos Subversion tem uma brilhante terceira dimenso que
1
muitos sistemas de arquivos no possuemTempo! Na interface de sistema de arquivos, quase
toda funo que tem um um argumento path tambm espera um argumento root. Este argumento
svn_fs_root_t descreve tanto uma reviso quanto uma transao do Subversion (que simplesmente
uma reviso em formao), e oferece esse contexto de terceira dimenso necessrio para entender a
diferena entre /foot/bar na reviso 32, e o mesmo caminho existente na reviso 98. A Figura 8.2,
Versionando o tempoa terceira dimenso! mostra o histrico de revises como uma dimenso
adicional no universo do sistema de arquivos Subversion.
1
Ns entendemos que isso pode ser um choque para os fs de fico cientfica que esto a muito tempo sob a impresso de
que Tempo na verdade a quarta dimenso, e ns pedimos desculpamos por qualquer trauma emocional causado por nossa
declarao de uma teoria diferente.
182
Incorporando o Subversion
Como mencionado anteriormente, a API de libsvn_fs parece como qualquer outro sistema de arquivos,
exceto que ele tem essa maravilhosa capacidade de versionamento. Ela foi projetada para ser
usvel por qualquer programa interessado em um sistema de arquivos com versionamento. No
coincidentemente, o prprio Subversion tem interesse nessa funcionalidade. Mas enquanto a API
do sistema de arquivos deveria ser suficiente para suporte bsico em versionamento de arquivos e
diretrios, o Subversion quer maise a que aparece a libsvn_repos.
No obstante, o mecanismo de ganchos uma das razes para a abstrao de uma biblioteca de
repositrio separada do restante do cdigo do sistema de arquivo. A API de libsvn_repos oferece muitas
outras utilidades importantes ao Subversion. Isso inclui as habilidades para:
consultar as mensagens de log das submisses associadas com todas (ou algumas) das revises
nas quais um conjunto de arquivos foi modificado no sistema de arquivos.
gerar um despejo do sistema de arquivos que seja legvel ao ser humano, uma completa
representao das revises no sistema de arquivos.
J que Subversion usa URLs para identificar suas fontes de repositrio, a parte protocolo do esquema
URL (normalmente file://, http://, https://, svn://, ou ou svn+ssh://) usada para
determinar qual mdulo RA manipular as comunicaes. Cada mdulo registra uma lista dos
protocolos que sabem como conversar para que o carregador de RA possa, em tempo de execuo,
determinar qual mdulo usar para realizar a tarefa. Voc pode descobrir quais mdulos RA esto
disponveis ao cliente de linha de comando do Subversion e que protocolos eles suportam, executando
svn --version:
$ svn --version
svn, version 1.4.3 (r23084)
compiled Jan 18 2007, 07:47:40
183
Incorporando o Subversion
A API pblica exportada pela Camada RA contm as funcionalidades necessrias para enviar e
receber dados versionados para e do repositrio. E cada uma das extenses disponveis est hbil
para realizar esta tarefa usando um protocolo especficolibsvn_ra_dav conversa em HTTP/WebDAV
(opcionalmente usando criptografia com SSL) com um Servidor HTTP Apache que estiver rodando o
mdulo mod_dav_svn de servidor Subversion; libsvn_ra_svn conversa num protocolo de rede especial
com o programa svnserve; e assim por diante.
E para aqueles que desejam acessar um repositrio Subversion usando ainda outro protocolo, isso
perfeitamente possvel porque a Camada de Acesso ao Repositrio modularizada! Desenvolvedores
podem simplesmente escrever uma nova biblioteca que implementa a interface RA em um dos lados
e comunicar com o repositrio no outro lado. Sua nova biblioteca pode usar protocolos de rede
j existentes, ou voc pode inventar o seu prprio. Voc poderia usar chamadas de comunicao
entre processos (IPC), ouvamos ficar loucos, devemos?voc pode at implementar um protocolo
baseado em email. O Subversion oferece as APIs; voc oferece a criatividade.
Camada Cliente
No lado do cliente, a cpia de trabalho do Subversion onde todas as aes tomam lugar. A pilha
de funcionalidades implementadas pelas bibliotecas do lado cliente existem para o nico propsito
de gerenciar cpias de trabalhodiretrios cheios de arquivos e outros sub-diretrios que servem
como uma espcie de reflexos locais e editveis de um ou mais locais do repositrioe propagando
mudanas para e a partir da Camada de Acesso ao Repositrio.
A biblioteca do cliente Subversion, libsvn_client, tem uma responsabilidade mais abrangente; seu
trabalho combinar a funcionalidade da biblioteca de cpia de trabalho com as da Camada de Acesso
ao Repositrio, e ento oferecer uma API de alto nvel para qualquer aplicao que desejar realizar
aes gerais de controle de reviso. Por exemplo, a funo svn_client_checkout() pega uma
URL como argumento. Ela passa esta URL para a camada de RA e abre uma sesso autenticada com
um determinado repositrio. Ela ento pede ao repositrio por uma certa rvore, e envia esta rvore
para a biblioteca de cpia de trabalho, que ento escrever toda a cpia de trabalho no disco (o diretrio
.svn e tudo mais).
184
Incorporando o Subversion
A biblioteca cliente projetada para ser usada por qualquer aplicao. Enquanto o cdigo fonte do
Subversion inclui um cliente de linha de comando padro, deveria ser muito fcil escrever qualquer
nmero de clientes GUI sob essa biblioteca cliente. Novas interfaces grficas (ou qualquer novo cliente)
para o Subversion no precisam ser invlucros desajeitados sobre o cliente de linha de linha de
comandoelas possuem acesso total pela API de libsvn_client s mesmas funcionalidades, dados e
mecanismos de resposta que o cliente de linha de comando usa. De fato, a rvore do cdigo fonte do
Subversion contm um pequeno programa em C (o qual pode ser encontrado em tools/examples/
minimal_client.c que exemplifica como manusear a API do Subversion para criar um simples
programa cliente.
Porque seu programa GUI deveria vincular-se diretamente com libsvn_client em vez de agir
como uma cobertura em volta do programa de linha de comando? Alm de ser mais eficiente,
pode ser mais correto tambm. Um programa de linha de comando (como o oferecido com o
Subversion) que se vincula com a biblioteca cliente precisa traduzir eficientemente os bits das
respostas e requisies de dados dos tipos C para alguma forma de sada legvel por seres
humanos. Esse tipo de traduo pode ser dispendioso. Sendo assim, o programa pode no
mostrar todas as informaes colhidas pela API, ou pode combinar pedaos de informaes para
uma apresentao compacta.
Se voc encobrir um programa de linha de comando com outro programa, o segundo programa
ter acesso apenas s informaes j interpretadas (e como mencionado, possivelmente
incompletas), que devem ser novamente traduzidas para seu prprio formato de apresentao.
Com cada camada de encapsulamento, a integridade dos dados originais potencialmente
degradada mais e mais, quase como o resultado de fazer uma cpia de uma cpia (de uma cpia
) do seu cassete de udio ou vdeo favorito.
Mas o argumento mais contundente para vincular diretamente s APIs em vez de encapsular
outros programas que o projeto Subversion fez promessas de compatibilidade entre suas APIs.
Atravs de verses menores dessas APIs (como entre 1.3 e 1.4), nenhum prottipo de funo
mudar. Em outras palavras, voc no ser forado a atualizar o cdigo fonte de seu programa
simplesmente porque voc atualizou para uma nova verso do Subversion. Algumas funes
podem ficar defasadas, mas elas ainda funcionaro, e isso te d um intervalo de tempo para
comear a usar as novas APIs. Esse tipo de compatibilidade no prometido para as mensagens
de sada do cliente de linha de comando do Subversion, as quais esto sujeitas a mudanas de
uma verso para outra.
Que reviso de cada um destes arquivos e diretrios est atualmente presente na sua cpia de
trabalho.
Todas propriedades definidas pelo usurio que possam estar anexadas a esses arquivos e diretrios.
185
Incorporando o Subversion
pelo Subversion, para acessar e manipular os dados da cpia de trabalho, em vez de ler ou modificar
esses arquivos diretamente. Os formatos de arquivo empregados pela biblioteca de cpia local para
seus dados administrativos mudam de tempos em temposum fato em que as APIs pblicas fazem
um bom trabalho ao esconder do usurio comum. Nesta seo, vamos expor alguns destes detalhes
de implementao para satisfazer sua imensa curiosidade.
Os Arquivos de Entrada
Talvez o mais importante arquivo no diretrio .svn seja o arquivo entries. Ele contm a maior
parte das informaes administrativas sobre os tens versionados em um diretrio da cpia de
trabalho. este nico arquivo que registra as URLs do repositrio, reviso inalterada, checksum dos
arquivos, textos inalterados e timestamp das propriedades, informaes de agendamento e conflitos,
ltimas informaes conhecida de submisso (autor, reviso, timestamp), histrico da cpia local
praticamente tudo que um cliente Subversion tem interesse em saber sobre um recurso versionado
(ou a ser versionado)!
Pessoas familiares com os diretrios administrativos do CVS tero reconhecido neste ponto que o
arquivo .svn/entries do Subversion serve o propsito, entre outras coisas, dos arquivos CVS/
Entries, CVS/Root e CVS/Repository do CSV combinados.
O formato do arquivo .snv/entries tem mudado ao longo do tempo. Originalmente um arquivo XML,
ele agora usa um formato de arquivo customizadoapesar de ainda legvel a humanos. Enquanto o
XML foi uma boa escolha no incio para os desenvolvedores do Subversion que foram freqentemente
depurando o contedo do arquivo (e o comportamento do Subversion em funo dele), a necessidade
de uma depurao fcil no desenvolvimento foi se reduzindo com a maturidade do Subversion, e vem
sendo substituda pela necessidade de desempenho do usurio. Fique ciente que a biblioteca de cpia
de trabalho do Subversion atualiza automaticamente as cpias de trabalho de um formato para outro
ela l os formatos antigos, e escreve os novoso que salva voc do problema de verificar uma nova
cpia de trabalho, mas pode complicar em situaes onde diferentes verses do Subversion podem
estar tentando usar a mesma cpia de trabalho.
Com propsito similar aos arquivos text-base esto os arquivos de propriedade e suas cpias prop-
base intactas, localizadas em .svn/props e .svn/prop-base respectivamente. J que diretrios
podem ter propriedades, tambm existem os arquivos .svn/dir-props e .svn/dir-prop-base.
Usando as APIs
Desenvolver aplicaes junto com as APIs de biblioteca do Subversion bastante simples. O
Subversion essencialmente um conjunto de bibliotecas C, com arquivos de cabealho (.h) que ficam
no diretrio subversion/include da rvore de fontes. Estes cabealhos so copiados para locais
de seu sistema (por exemplo, /usr/local/include) quando voc constri e instala o Subversion
a partir dos fontes. Estes cabealhos representam o conjunto das funes e tipos que so acessveis
pelos usurios das bibliotecas do Subversion. A comunidade de desenvolvedores do Subversion
186
Incorporando o Subversion
meticulosa em garantir que a API pblica esteja bem documentadarefere-se diretamente aos
arquivos de cabealho para esta documentao.
Ao examinar os arquivos de cabealho pblicos, a primeira coisa que voc pode perceber que os
tipos de dado e funes do Subversion possuem um espao de nomes protegidos. Isto , cada nome
de smbolo pblico do Subversion inicia com svn_, seguido por um cdigo curto para a biblioteca na
qual o smbolo est definido (como wc, client, fs, etc.), seguido por um nico sublinhado (_) e ento
o restante do nome do smbolo. As funes semi-pblicas (usadas entre os arquivos fonte de uma dada
biblioteca mas no por cdigo fora desta biblioteca, e encontrada dentro de seus prprios diretrios)
diferem deste esquema de nomeao em que, em vez de um nico sublinhado depois do cdigo da
biblioteca, elas usam um sublinhado duplo (__). As funes que so privadas a um dado arquivo fonte
no possuem prefixao especial, e so declaradas como static. Evidentemente, um compilador
no est interessado nestas convenes de nomeao, mas elas ajudam esclarecer o escopo de uma
dada funo ou tipo de dado.
Uma outra boa fonte de informaes sobre programao com as APIs do Subversion so as diretrizes
de hacking do projeto, o qual pode ser encontrado em http://subversion.tigris.org/hacking.html. Este
documento contm informaes teis que, embora destinadas a desenvolvedores e aos prprios
desenvolvedores do Subversion, igualmente aplicvel a pessoas desenvolvendo com o Subversion
2
como um conjunto de bibliotecas de terceiros.
2
Afinal, o Subversion usa as APIs do Subversion, tambm.
3
O Subversion usa chamadas de sistema e tipos de dado em ANSI sempre que possvel.
4
Neon e Berkeley DB so exemplos de tais bibliotecas.
187
Incorporando o Subversion
Quase todo desenvolvedor que usou a linguagem de programao C teve em algum ponto
suspirou fundo ao enfrentar a assustadora tarefa de gerenciar o uso de memria. Alocar memria
suficiente para o uso, manter controle dessas alocaes, liberar a memria quando voc no
precisa mais delaestas tarefas podem ser bastante complexas. E certamente, falhar ao fazer
essas coisas adequadamente pode resultar em um programa que trava sozinho, ou pior ainda,
trava todo o computador.
Em linguagens de alto nvel, por outro lado, deixam o trabalho de gerenciamento de memria
5
completamente distante do desenvolvedor. Linguagens como Java e Python usam um coletor
de lixo, alocando memria para os objetos quando necessrio, e automaticamente liberando esta
memria quando o objeto no est mais em uso.
Alm disso, as APIs do Subversion requerem que todos os parmetros da URL sejam devidamente
codificados em URI. Assim, em vez de passar file:///home/username/My File.txt como a
URL de um arquivo nomeado My File.txt, voc precisa passar file:///home/username/My
%20File.txt. Novamente, o Subversion fornece funes auxiliares que sua aplicao pode usar
svn_path_uri_encode() e svn_path_uri_decode(), para codificao e decodificao de
URI, respectivamente.
188
Incorporando o Subversion
Esforos significantes vm sendo realizados na criao de vnculos funcionais gerados por SWIG
para Python, Perl e Ruby. De certa forma, o trabalho realizado preparando os arquivos de interface
SWIG para estas linguagens reutilizvel em esforos para produzir vnculos para outras linguagens
suportadas por SWIG (as quais incluem verses de C#, Guile, Java, MzScheme, OCaml, PHP, e Tcl,
entre outras). No entanto, alguma programao extra necessria para compensar as APIs complexas,
assim o SWIG precisa de alguma ajuda na traduo entre linguagens. Para mais informaes sobre o
SWIG, veja o site do projeto em http://www.swig.org/.
O Subversion tambm possui vnculos de linguagem para Java. Os vnculos JavaJL (localizados em
subversion/bindings/java na rvore de fontes do Subversion) no so baseados no SWIG,
porm so uma mistura de javah e JNI codificada na unha. JavaHL abrange a maior parte das APIs
do Subversion no lado do cliente, e especificamente orientada aos implementadores de clientes
Subversion baseado em Java e integraes em IDE.
Cabe notar aqui que existem outras opes para interfacear com o Subversion usando outras
linguagens: vnculos alternativos para o Subversion que no so fornecidos por toda a comunidade de
desenvolvimento do Subversion. Voc pode encontrar links para estes vnculos alternativos na pgina
de links do projeto Subversion (em http://subversion.tigris.org/links.html), mas existe uma dupla popular
que sentimos serem especialmente notveis. Primeiro, os vnculos PySVN de Barry Scott (http://
pysvn.tigris.org/) so uma opo popular para vinculao com Python. PySVN ostenta uma interface
mais Pythnica do que a das APIs baseadas na da C e oferecida pelos vnculos Python do prprio
Subversion. Para pessoas procurando por uma implementao puramente em Java do Subversion,
verifiquem o SVNKit (http://svnkit.com/), que um Subversion reescrito totalmente em Java. Contudo,
voc deve ter muito cuidado aquiporque o SVNKit no utiliza as bibliotecas base do Subversion, seu
comportamento no possui garantias de coincidir com o do prprio Subversion.
Exemplos de Cdigo
Exemplo 8.1, Usando a Camada de Repositrio contm um segmento de cdigo (escrito em C) que
ilustra alguns dos conceitos que estamos discutindo. Ele usa ambas as interfaces de repositrio e
sistema de arquivo (como pode ser determinado pelos prefixos svn_repos_ e svn_fs_ dos nomes de
funo, respectivamente) para criar uma nova reviso na qual um diretrio adicionado. Voc pode ver
o uso de um recipiente APR, o qual passado para propsitos de alocao de memria. Alm disso, o
cdigo revela um fato um tanto obscuro sobre tratamento de erros do Subversiontodos os erros do
Subversion devem ser explicitamente tratados para evitar vazamento de memria (e em alguns casos,
falha da aplicao).
189
/* Abre o repositrio localizado em REPOS_PATH.
*/
INT_ERR(svn_repos_open(&repos, repos_path, pool));
Incorporando o Subversion
/* Obtm um ponteiro para o objeto de sistema de arquivo armazenado em REPOS.
*/
Exemplo 8.1. Usando a Camada de Repositrio
fs = svn_repos_fs(repos);
/* Pede ao sistema de arquivo para nos retornar a mais jovem reviso que
* existe atualmente.
*/
INT_ERR(svn_fs_youngest_rev(&youngest_rev, fs, pool));
/* Inicia uma nova transao que tem por base a YOUNGEST_REV. Ns estamos
* menos provveis de ter nossa submisso rejeitada como conflitante se
* sempre tentarmos fazer nossas mudanas novamente em uma cpia da ltima
* imagem da rvore do sistema de arquivo.
*/
INT_ERR(svn_fs_begin_txn(&txn, fs, youngest_rev, pool));
/* Agora que temos iniciada uma nova transao Subversion, recupera um objeto
* raz que representa esta transao.
*/
INT_ERR(svn_fs_txn_root(&txn_root, txn, pool));
INT_ERR(err);
}
190
Incorporando o Subversion
Note que em Exemplo 8.1, Usando a Camada de Repositrio, o cdigo poderia ter apenas to
facilmente submetido a transao usando svn_fs_commit_txn(). Mas a API do sistema de arquivo
sabe nada sobre o mecanismo de gancho da biblioteca do repositrio. Se voc quer que seu repositrio
Subversion realize automaticamente algum conjunto de tarefas no-Subversion toda vez que voc
submeter uma transao (como, por exemplo, enviar um email que descreve todas as mudanas
feitas nesta transao para sua lista de discusso de desenvolvedores), voc precisa usar a verso
desta funo embrulhada em libsvn_repos, a qual adiciona a funcionalidade de disparo de gancho
neste caso, svn_repos_fs_commit_txn(). (Para mais informaes em relao aos ganchos de
repositrio Subversion, veja Implementando Ganchos de Repositrio.)
Agora vamos trocar as linguagens. Exemplo 8.2, Usando a Camada de Repositrio com Python um
exemplo de programa que usa os vnculos Python SWIG do Subversion para recursivamente rastrear a
mais jovem reviso do repositrio, e imprimir os vrios caminhos descobertos durante o rastreamento.
191
#!/usr/bin/python
import sys
Exemplo
import 8.2. Usando a Camada de Repositrio
os.path com Python
import svn.fs, svn.core, svn.repos
def crawl_youngest(repos_path):
"""Abre o repositrio em REPOS_PATH, e rastreia recursivamente sua
reviso mais recente."""
if __name__ == "__main__":
# Verifica se o uso est correto.
if len(sys.argv) != 2:
sys.stderr.write("Usage: %s REPOS_PATH\n"
% (os.path.basename(sys.argv[0])))
sys.exit(1)
192
Incorporando o Subversion
Este mesmo programa em C precisaria lidar com o sistema de recipiente de memria da APR. Mas
Python manipula o uso de memria automaticamente, e os vnculos Python do Subversion aderem a
esta conveno. Em C, voc teria que trabalhar com tipos de dados personalizados (como aqueles
oferecidos pela biblioteca APR) para representar o hash de entradas e a lista de caminhos, mas Python
possui hashes (chamados dicionrios) e listas como tipos de dados embutidos, e oferece uma rica
coleo de funes para operar nesses tipos. Ento a SWIG (com a ajuda de algumas personalizaes
na camada de vnculos de linguagem do Subversion) toma o cuidado de mapear esses tipos de dados
personalizados para os tipos de dados nativos da linguagem alvo. Isto oferece uma interface mais
intuitiva para os usurios desta linguagem.
Os vnculos Python do Subversion podem ser usados para trabalhar com operaes de cpia, tambm.
Na seo anterior deste captulo, mencionamos a interface libsvn_client, e como ela existe para
o nico propsito de simplificar o processo de escrever um cliente Subversion. O Exemplo 8.3, Um
Rastreador de Status em Python um breve exemplo de como esta biblioteca pode ser acessada por
meio dos vnculos Python da SWIG para recriar uma verso menos escalada do comando svn status.
193
svn.wc.svn_wc_status_modified : 'M',
svn.wc.svn_wc_status_merged : 'G',
svn.wc.svn_wc_status_conflicted : 'C',
Incorporando o Subversion
svn.wc.svn_wc_status_obstructed : '~',
svn.wc.svn_wc_status_ignored : 'I',
svn.wc.svn_wc_status_external : 'X',
Exemplo 8.3. Um Rastreador de Status em Python
svn.wc.svn_wc_status_unversioned : '?',
}
return code_map.get(status, '?')
def usage_and_exit(errorcode):
"""Imprime a mensagem do modo de uso, e sai com ERRORCODE."""
stream = errorcode and sys.stderr or sys.stdout
stream.write("""Usage: %s OPTIONS WC-PATH
Options:
--help, -h : Show this usage message
--verbose, -v : Show all statuses, even uninteresting ones
""" % (os.path.basename(sys.argv[0])))
sys.exit(errorcode)
if __name__ == '__main__':
# Analisa as opes de linha de comando.
try:
opts, args = getopt.getopt(sys.argv[1:], "hv", ["help", "verbose"])
except getopt.GetoptError:
usage_and_exit(1)
verbose = 0
for opt, arg in opts:
if opt in ("-h", "--help"):
usage_and_exit(0)
if opt in ("-v", "--verbose"):
verbose = 1
if len(args) != 1:
usage_and_exit(2)
194
Incorporando o Subversion
Como foi o caso no Exemplo 8.2, Usando a Camada de Repositrio com Python, este programa no
precisa de recipiente e usa, para na maior parte, os tipos de dados normais do Python. A chamada
para svn_client_ctx_t() est enganando porque a API pblica do Subversion no tem tal funo
isto apenas acontece por ser um caso onde a gerao automtica de linguagem da SWIG no
funciona para algumas partes (a funo um tipo de funo que fabrica a verso Python da estrutura
complexa correspondente em C). Note tambm que o caminho passado para este programa (como
aquele ltimo) passa atravs da svn_path_canonicalize(), porque no fazendo isso corre-se o
risco de desencadear as asseres subjacentes da biblioteca C do Subversion sobre tais coisas, que
se traduz a um aborto imediato e sem cerimnia da execuo do programa.
195
Captulo 9. Referncia Completa do
Subversion
Este captulo tem a inteno de ser uma referncia completa para o uso do Subversion. Ele inclui o
comando (svn) e todos os seus subcomandos, assim como programas de administrao de repositrio
(svnadmin e svnlook) e seus respectivos sub-comandos.
$ svn -v status
$ svn status -v
$ svn status -v meuarquivo
Voc pode encontrar muitos exemplos de como usar a maioria dos comandos do cliente Subversion
Captulo 2, Uso Bsico e dos comandos para gerenciamento de propriedades em Propriedades.
Opes do svn
Ainda que o Subversion tenha diferentes opes para seus subcomandos, todas as opes so globais
isto , garante-se que cada opo signifique a mesma coisa independentemente do subcomando
que voc use com ela. Por exemplo, --verbose (-v) sempre significa sada verbosa, qualquer que
seja o subcomando que voc utilizar com ela.
--auto-props
Habilita auto-props, sobrescrevendo a diretiva enable-auto-props no arquivo config.
--config-dir DIR
Diz para o Subversion ler a informao de configurao a partir do diretrio especificado ao invs
de seu local padro (.subversion no diretrio home do usurio).
--diff-cmd CMD
Especifica um programa externo a ser usado para exibir diferenas entre arquivos. Quando svn
diff invocado sem esta opo, ele usa o mecanismo de diff interno do Subversion, que exibe
diffs unificados por padro. Se voc quiser usar um programa diff externo, use --diff-cmd. Voc
pode passar opes para o programa diff com a opo --extensions (mais detalhes sobre isso
mais adiante nesta seo).
--diff3-cmd CMD
Especifica um programa externo a ser usado para mesclar arquivos.
--dry-run
Faz meno de todos os passos de execuo de um comando, mas sem efetuar qualquer alterao
tanto no disco quanto no repositrio.
1
Sim, sim, voc no precisa de um subcomando para usar a opo --version, mas vamos falar disso num instante.
196
Referncia Completa
do Subversion
--editor-cmd CMD
Especifica um programa externo a ser usado para editar mensagens de log ou valores de
propriedades. Consulte a seo editor-cmd em Configurao para ver as formas de especificar
um editor padro.
--encoding ENC
Informa ao Subversion que sua mensagem de submisso est codificada com o charset dado. O
padro o locale nativo de seu sistema operacional, e voc deve especificar a codificao se sua
mensagem de commit estiver em alguma codificao diferente.
--force
Fora a execuo de um comando ou operao especficos. H algumas operaes em que o
Subversion ir impedi-lo de prosseguir, em sua utilizao normal, mas voc pode passar a opo
force para dizer ao Subversion Eu sei o que estou fazendo, bem como as possveis consequncias
disto, ento deixe-me faz-lo. Esta opo seria o equivalente a fazer voc mesmo um reparo
eltrico com a energia ligadase voc no souber o que est fazendo, provvel que tome um
choque desagradvel.
--force-log
Fora que um parmetro suspeito passado para s opes --message (-m) ou --file (-F)
seja aceito como vlido. Por padro, o Subversion ir produzir um erro se os parmetros destas
opes parecerem com argumentos de destino do subcomando. Por exemplo, se voc passar
um caminho de um arquivo versionado para a opo --file (-F), o Subversion ir assumir que
voc cometeu um engano, que caminho informado pretendia ser o objeto alvo da operao, e que
voc simplesmente esqueceu de informar algum outro arquivono-versionadocontendo sua
mensagem de log. Para confirmar sua inteno e sobrescrever esse tipo de erro, passe a opo
--force-log para os subcomandos que aceitam mensagens de log.
--ignore-ancestry
Diz para o Subversion ignorar ancestrais (diretrios acima) ao determinar diferenas (baseia-se
apenas em contedos dos caminhos).
--ignore-externals
Diz para o Subversion ignorar definies externas e cpias de trabalho externas gerenciadas por
elas.
--incremental
Exibe sada em um formado adequado para concatenao.
--limit NUM
Exibe apenas as primeiras NUM mensagens de log.
197
Referncia Completa
do Subversion
--new ARG
Utiliza ARG como objeto alvo novo (para uso com svn diff).
--no-auth-cache
Evita cache de informao de autenticao (p.ex. nome de usurio e senha) nos diretrios
administrativos do Subversion.
--no-auto-props
Desabilita auto-props, sobrescrevendo a diretiva enable-auto-props no arquivo config.
--no-diff-added
Evita que o Subversion exiba diferenas para arquivos adicionados. O comportamento padro ao
adicionar um arquivo que o svn diff exiba as mesmas diferenas que voc veria se tivesse
adicionado todo o contedo a um arquivo (vazio) existente.
--no-diff-deleted
Evita que o Subversion exiba diferenas para arquivos excludos. O comportamento padro ao
remover um arquivo que o svn diff exiba as mesmas diferenas que voc veria se tivesse mantido
o arquivo mas removido todo o seu contedo.
--no-ignore
Mostra arquivos na listagem de status que normalmente seriam omitidos por corresponderem a
um padro na opo de configurao global-ignores ou na propriedade svn:ignore. Veja
Configurao e Ignorando Itens No-Versionados para mais informaes.
--no-unlock
No destrava arquivos automaticamente (o comportamento padro destravar todos os arquivos
listados como parte de um commit). Veja Travamento para mais informaes.
--non-interactive
No caso de uma falha de autenticao, ou credenciais insuficientes, evita a outra solicitao de
credenciais (p.ex. nome de usurio ou senha). til se voc estiver executando o Subversion
dentro de um script automatizado e for mais adequado ter uma falha de autenticao do Subversion
do que um prompt solicitando mais informao.
--non-recursive (-N)
Evita a recurso de um subcomando dentro de subdiretrios. Muitos subcomandos fazem recurso
por padro, mas alguns subcomandosusualmente aqueles com potencial de remover ou desfazer
suas alteraes locaisno.
--notice-ancestry
Leva os ancestrais (diretrios acima) em considerao ao determinar diferenas.
--old ARG
Utiliza ARG como objeto alvo antigo (para uso com svn diff).
--password PASS
Indica que voc est informando sua senha para autenticao na linha de comandodo contrrio,
se for preciso, o Subversion ir solicit-la interativamente.
--quiet (-q)
Solicita que o cliente exiba apenas as informaes mais essenciais ao executar uma dada
operao.
--recursive (-R)
Faz um subcomando executar recursivamente dentro dos subdiretrios. A maioria dos
subcomandos j executam recursivamente por padro.
198
Referncia Completa
do Subversion
--revprop
Opera em uma propriedade de reviso ao invs de uma propriedade especfica de um arquivo ou
diretrio. Esta opo requer que voc tambm informe uma reviso com a opo --revision
(-r).
--show-updates (-u)
Faz com que o cliente exiba informao sobre quais arquivos em sua cpia de trabalho esto
desatualizados. Isto no atualiza nenhum de seus arquivosapenas mostra a voc quais arquivos
sero atualizados se voc executar um svn update.
--stop-on-copy
Faz com que um subcomando do Subversion que est varrendo o histrico de um recurso
versionado pare de vasculhar essas informaes histricas quando uma cpiaisto , um local no
histrico em que o recurso foi copiado de outro local no repositrioseja encontrada.
--strict
Faz com que o Subversion use semntica estrita, um conceito que um pouco vago a no ser
quando aplicado a subcomandos especficos (especificamente ao svn propget).
--targets FILENAME
Diz para o Subversion obter a lista de arquivos em que voc quer executar uma operao a partir
de um nome de arquivo informado ao invs de ter de listar todos os arquivos na linha de comando.
--username NAME
Indica que voc est informando seu nome de usurio para autenticao na linha de comando
de outra forma, se for necessrio, o Subversion ir solicit-lo a voc interativamente.
--verbose (-v)
Solicita que o cliente exibe o mximo de informao que puder ao executar qualquer subcomando.
Isto pode fazer com que o Subversion exiba campos adicionais, informaes detalhadas sobre
cada arquivo, ou informaes extras sobre suas aes em execuo.
--version
Exibe informao da verso do cliente. Esta informao no apenas inclui o nmero de verso do
cliente, mas tambm uma listagem de todos os mdulos de acesso ao repositrio que o cliente
pode usar para acessar um repositrio Subversion. Com --quiet (-q) ele exibe apenas o nmero
de verso de forma compacta.
--xml
Exibe a sada em um formato XML.
199
Referncia Completa
do Subversion
Subcomandos svn
Aqui temos vrios subcomandos:
200
Referncia Completa
do Subversion
Nome
svn add Adiciona arquivos, diretrios ou links simblicos.
Sinopse
svn add PATH...
Descrio
Agenda arquivos, diretrios ou links simblicos em sua cpia de trabalho para adio no repositrio.
Eles sero carregados e adicionados efetivamente ao repositrio em sua prxima submisso. Se voc
adicionar alguma coisa e mudar de idia antes de realizar o commit, voc pode cancelar o agendamento
usando svn revert.
Nomes Alternativos
Nenhum
Altera
Cpia de trabalho
Acessa o Repositrio
No
Opes
--targets FILENAME
--non-recursive (-N)
--quiet (-q)
--config-dir DIR
--no-ignore
--auto-props
--no-auto-props
--force
Exemplos
Para adicionar um arquivo para sua cpia de trabalho:
201
Referncia Completa
do Subversion
Normalmente, o comando svn add * vai desconsiderar quaisquer diretrios que j estiverem sob
controle de verso. Algumas vezes, no entanto, voc pode querer adicionar quaisquer objetos no-
versionados em sua cpia de trabalho, incluindo os que estiverem escondidos mais profundamente na
rvore de diretrios. Passar a opo --force faz com que o svn add aja recursivamente tambm
nos diretrios versionados:
202
Referncia Completa
do Subversion
Nome
svn blame Mostra informao de autor e reviso por linha para os arquivos ou URLs especificados.
Sinopse
svn blame TARGET[@REV]...
Descrio
Mostra informao de autor e reviso por linha para os arquivos ou URLs especificados. Cada linha de
texto prefixada com o nome do autor (nome de usurio) e o nmero de reviso da ltima alterao
naquela linha.
Nomes Alternativos
praise, annotate, ann
Altera
Nada
Acessa o Repositrio
Sim
Opes
Exemplos
Se voc quiser ver informao dos responsveis pelos fontes para readme.txt em seu repositrio:
Ainda que o svn blame informe que Harry modificou o arquivo readme.txt por ltimo na reviso 5, voc
ter de verificar exatamente o que a reviso mudou para ter certeza de que Harry tenha mudado o
context da linhaele pode ter apenas ajustado espaos em branco, p.ex.
203
Referncia Completa
do Subversion
Nome
svn cat Exibe o contedo de arquivos ou URLs especificadas.
Sinopse
svn cat TARGET[@REV]...
Descrio
Exibe o contedo de arquivos ou URLs especificadas. Para listar o contedo de diretrios, veja svn list.
Nomes Alternativos
Nenhum
Altera
Nada
Acessa o Repositrio
Sim
Opes
Exemplos
Se voc quiser ver o arquivo readme.txt em seu repositrio sem carreg-lo para sua cpia de trabalho
(check out):
Se sua cpia de trabalho estiver desatualizada (ou se voc tiver alteraes locais) e voc
quiser ver a reviso HEAD de um arquivo em sua cpia de trabalho, o svn cat vai obter
automaticamente a reviso HEAD quando voc lhe passar um caminho:
$ cat foo.c
This file is in my local working copy
and has changes that I've made.
204
Referncia Completa
do Subversion
Nome
svn checkout Carrega uma cpia de trabalho a partir do repositrio.
Sinopse
svn checkout URL[@REV]... [PATH]
Descrio
Carrega uma cpia de trabalho a partir do repositrio. Se PATH for omitido, a base da URL ser usada
como destino. Se mltiplas URLs forem informadas, cada uma ser carregada dentro de um subdiretrio
de PATH, com o nome do subdiretrio sendo a base da URL.
Nomes Alternativos
co
Altera
Cria uma cpia de trabalho.
Acessa o Repositrio
Sim
Opes
Exemplos
Carrega uma cpia de trabalho dentro de subdiretrio chamado mine:
205
Referncia Completa
do Subversion
A quiz/m
Checked out revision 2.
$ ls
quiz test
Carrega dois diretrios diferentes para duas cpias de trabalho separadas, mas pe ambas dentro de
um diretrio chamado working-copies:
Se voc interromper um checkout (ou houver qualquer coisa que o interrompa, como perda da conexo
de rede, etc.), voc pode reinici-lo tanto executando um comando checkout idntico outra vez, como
atualizando sua cpia de trabalho incompleta:
$ cd test
$ svn update
A test/e
A test/f
Updated to revision 3.
206
Referncia Completa
do Subversion
Nome
svn cleanup Faz recursivamente uma limpeza na rea de trabalho.
Sinopse
svn cleanup [PATH...]
Descrio
Faz recursivamente uma limpeza na rea de trabalho, removendo travas da cpia de trabalho e
concluindo operaes no finalizadas. Sempre que voc obtiver um erro de cpia de trabalho travada,
execute este comando para remover travas perdidas e deixar sua cpia de trabalho no estado usvel
novamente.
Se, por algum motivo, um svn update falhar devido a um problema ao executar um programa diff
externo (p.ex. devido a entrada do usurio ou falha de rede), passe a opo --diff3-cmd para
permitir que a limpeza complete qualquer mesclagem com seu programa diff externo. Voc tambm
pode especificar um diretrio de configurao com --config-dir, mas voc deve precisar destas
opes em rarssimas ocasies.
Nomes Alternativos
Nenhum
Altera
Cpia de trabalho
Acessa o Repositrio
No
Opes
--diff3-cmd CMD
--config-dir DIR
Exemplos
Bem, no h muito para esta parte de exemplo aqui pois o svn cleanup no gera nenhuma sada. Se
voc no informar um caminho (PATH), ento . usado.
$ svn cleanup
207
Referncia Completa
do Subversion
Nome
svn commit Envia as alteraes de sua cpia de trabalho para o repositrio.
Sinopse
svn commit [PATH...]
Descrio
Envia as alteraes de sua cpia de trabalho para o repositrio. Se voc no informar uma mensagem
de log de registro usando seja a opo --file ou a opo --message, o svn vai executar seu editor de
texto para que voc escreva uma mensagem de commit. Veja a seo editor-cmd em Configurao.
svn commit vai enviar quaisquer marcadores de trava que encontrar e ir liberar as travas em todos
os caminhos PATHS submetidos (recursivamente), a menos que --no-unlock seja passado.
Se voc comear um commit e o Subversion executar seu editor para que voc componha
a mensagem de registro, voc ainda pode abortar sem submeter suas alteraes. Se voc
quiser cancelar a operao, apenas feche o editor sem salvar sua mensagem de log e
o Subversion ir lhe perguntar se voc quer cancelar a operao, prosseguir sem uma
mensagem de log, ou editar a mensagem novamente.
Nomes Alternativos
ci (abreviao para check in; e no co, que a abreviao para checkout)
Altera
Cpia de trabalho, repositrio
Acessa o Repositrio
Sim
Opes
Exemplos
Submete uma modificao simples em um arquivo com a mensagem de log na linha de comando e um
alvo implcito de seu diretrio atual (.):
208
Referncia Completa
do Subversion
Sending a
Transmitting file data .
Committed revision 3.
Submete uma modificao no arquivo foo.c (explicitamente especificado na linha de comando) com
a mensagem de log contida em um arquivo chamado msg:
Se voc quiser usar um arquivo que est sob controle de verso para sua mensagem de log com --
file, voc precisa passar a opo --force-log:
Committed revision 7.
209
Referncia Completa
do Subversion
Nome
svn copy Copia um arquivo ou diretrio em uma cpia de trabalho ou no repositrio.
Sinopse
svn copy SRC DST
Descrio
Copia um arquivo em uma cpia de trabalho ou no repositrio. SRC e DST podem ser tanto um caminho
em uma cpia de trabalho (WC) ou uma URL:
WC -> WC
Copia e agenda um item para adio (com o histrico).
WC -> URL
Imediatamente submete uma cpia de WC para a URL.
URL -> WC
Obtm (check out) a URL para dentro da WC, agendando-a para adio.
Nomes Alternativos
cp
Altera
O repositrio, se o destino for uma URL.
Acessa o Repositrio
Se a origem ou destino da cpia for o repositrio, ou se for preciso buscar um dado nmero de reviso
da origem.
Opes
210
Referncia Completa
do Subversion
--config-dir DIR
Exemplos
Copia um item para dentro de sua cpia de trabalho ( apenas agenda a cpianada ocorre com o
repositrio at que voc submeta a alterao):
Copia um item de sua cpia de trabalho para uma URL no repositrio (com submisso imediata, ento
voc deve informar tambm uma mensagem de log):
Committed revision 8.
Copia um item do repositrio para sua cpia de trabalho (apenas agenda a cpianada ocorre com
o repositrio at que voc submeta a alterao):
Committed revision 9.
Esta a forma mais fcil de rotular (tag) uma reviso em seu repositrioapenas execute
um svn copy daquela reviso (normalmente a HEAD) para dentro de seu diretrio tags.
E no se preocupe se voc se esquecer de rotular voc pode sempre especificar uma reviso mais
antiga e o rtulo a qualquer momento:
211
Referncia Completa
do Subversion
Nome
svn delete Exclui um item de uma cpia de trabalho ou do repositrio.
Sinopse
svn delete PATH...
Descrio
Os itens especificados pelo PATH so agendados para excluso at o prximo commit. Os arquivos
(e diretrios que ainda no foram submetidos) so imediatamente removidos da cpia de trabalho. O
comando no ir remover quaisquer itens no versionados ou modificados; utilize a opo --force
para sobrescrever este comportamento.
Itens especificados pela URL so excludos do repositrio por meio de um registro (commit) imediato.
Mltiplas URLs sofrem as alteraes de forma atmica.
Nomes Alternativos
del, remove, rm
Altera
Cpia de trabalho, se executando sobre arquivos; repositrio, se operando sobre URLs
Acessa o Repositrio
Apenas quando executado sobre URLs
Opes
--force
--force-log
--message (-m) TEXT
--file (-F) FILE
--quiet (-q)
--targets FILENAME
--username USER
--password PASS
--no-auth-cache
--non-interactive
--editor-cmd EDITOR
--encoding ENC
--config-dir DIR
Exemplos
Usar svn para excluir um arquivo de sua cpia de trabalho remove sua cpia local do arquivo, mas
apenas faz o agendamento para que ele seja removido do repositrio. Quando voc submeter a
alterao, o arquivo excludo efetivamente do repositrio.
212
Referncia Completa
do Subversion
Excluir uma URL, no entanto, imediato, ento voc deve informar tambm uma mensagem de log:
Aqui est um exemplo de como forar a excluso de um arquivo que j foi modificado localmente:
213
Referncia Completa
do Subversion
Nome
svn diff Exibe as diferenas entre duas revises ou caminhos.
Sinopse
diff [-c M | -r N[:M]] [TARGET[@REV]...]
Descrio
Exibe as diferenas entre dois caminhos. As formas de se usar o svn diff so:
Use somente svn diff' para exibir as modificaes locais em uma cpia de trabalho.
Exibe as mudanas feitas nos TARGETs de como eram em REV entre duas revises. TARGETs podem
ser todos cpias de trabalho como URLs. Se TARGETs so caminhos na cpia de trabalho, N se referir
por padro a BASE e M, cpia de trabalho; se forem URLs, N deve ser especificado e M servir de
referncia a HEAD. A opo -c M equivalente a -r N:M sendo N = M-1. Usar -c -M faz o contrrio:
-r M:N sendo N = M-1.
Exibe as diferenas entre OLD-TGT de como estava em OLDREV e NEW-TGT de como estava em
NEWREV. PATHs, se especificados, so relativos a OLD-TGT e NEW-TGT e restringem a sada s
diferenas entre estes caminhos. OLD-TGT e NEW-TGT podem ser caminhos na cpia de trabalho ou
URL[@REV]. NEW-TGT, por padro, se refere a OLD-TGT se no for especificada. -r N faz com que
OLDREV seja N, -r N:M faz com que OLDREV seja N e que NEWREV seja M.
svn diff -r N:M URL abreviao para svn diff -r N:M --old=URL --new=URL.
svn diff [-r N[:M]] URL1[@N] URL2[@M] abreviao para svn diff [-r N[:M]] --old=URL1 --
new=URL2.
Se TARGET for uma URL, ento as revises N e M podem ser dadas tanto pela opo --revision
como pela notao @ como descrito anteriormente.
--revision N:M
O servidor compara TARGET@N e TARGET@M.
--revision N
O cliente compara TARGET@N com a cpia de trabalho.
(sem --revision)
O cliente compara a base com a cpia de trabalho de TARGET.
Se a sintaxe alternativa for usada, o servidor compara URL1 e URL2 nas revises N e M respectivamente.
Se tanto N ou M forem omitidos, assumido o valor de HEAD.
Por padro, svn diff ignora os diretrios superiores dos caminhos dos arquivos e meramente compara o
contedo dos dois arquivos sendo comparados. Se voc usar --notice-ancestry, estes ancestrais
dos caminhos sero levados em considerao ao comparar as revises (isto , se voc executar svn
diff em dois arquivos com contedos idnticos mas com diretrios superiores em caminhos diferentes,
voc ir ver o contedo inteiro do arquivo como se ele tivesse sido removido e adicionado novamente).
214
Referncia Completa
do Subversion
Nomes Alternativos
di
Altera
Nada
Acessa o Repositrio
Para obter as diferenas de qualquer coisa com relao reviso BASE em sua cpia de trabalho
Opes
Exemplos
Compara BASE e sua cpia de trabalho (um dos usos mais comuns do svn diff):
Verificar como as modificaes em sua cpia de trabalho se comparam com relao a revises mais
antigas:
215
Referncia Completa
do Subversion
===================================================================
--- COMMITTERS (revision 3900)
+++ COMMITTERS (working copy)
Compara a reviso 3000 com a reviso 3500 usando a notao de intervalo (voc passa apenas uma
URL neste caso):
Compara a reviso 3000 com a reviso 3500 de todos os arquivos em trunk usando a notao de
intervalo:
Compara a reviso 3000 com a reviso 3500 apenas de trs arquivos em trunk usando a notao
de intervalo:
Se voc j tem uma cpia de trabalho, voc pode obter as diferenas sem digitar URLs longas:
Use --diff-cmd CMD -x para passar argumentos diretamente para o programa diff externo
216
Referncia Completa
do Subversion
Nome
svn export Exporta uma rvore de diretrios limpa.
Sinopse
svn export [-r REV] URL[@PEGREV] [PATH]
Descrio
A primeira forma exporta uma rvore de diretrios limpa a partir do repositrio especificado pela URL,
na reviso REV se esta for dada, ou de HEAD em caso contrrio, para o caminho dado por PATH. Se
PATH for omitido, o ltimo componente da URL usado como nome do diretrio local.
A segunda forma exporta uma rvore de diretrios limpa a partir da cpia de trabalho especificada
por PATH1 para o caminho dado por PATH2. Todas as modificaes locais sero preservadas, mas
arquivos que no estiverem sob controle de verso no sero copiados.
Nomes Alternativos
Nenhum
Altera
Disco local
Acessa o Repositrio
Apenas se exportando a partir de uma URL
Opes
Exemplos
Exporta a partir de sua cpia de trabalho (no exibe nenhum arquivo ou diretrio):
217
Referncia Completa
do Subversion
A my-export/test
A my-export/quiz
Ao distribuir pacotes de seus repositrio especficos para um determinado sistema operacional, pode
ser til exportar uma rvore que use o marcador de fim de linha (EOL) especfico. A opo --native-
eol far isso, mas ela afeta apenas os arquivos que tenham a propriedade svn:eol-style =
native anexada a si. Por exemplo, para exportar uma rvore com todas as terminaes de linhas
dadas do tipo CRLF (possivelmente para distribuio de arquivos .zip para Windows):
Voc pode especificar LR, CR, ou CRLF como tipos de marcadores de fim de linha com esta opo --
native-eol.
218
Referncia Completa
do Subversion
Nome
svn help Ajuda!
Sinopse
svn help [SUBCOMMAND...]
Descrio
Este seu melhor amigo quando estiver usando o Subversion e este livro sequer chegar a seus ps!
Nomes Alternativos
?, h
As opes -?, -h e --help tm todas o mesmo efeito que usando o subcomando help.
Altera
Nada
Acessa o Repositrio
No
Opes
--config-dir DIR
219
Referncia Completa
do Subversion
Nome
svn import Submete (commit) um arquivo ou rvore no-versionada ao repositrio.
Sinopse
svn import [PATH] URL
Descrio
Submete recursivamente uma cpia de PATH para URL. Se PATH for omitido, ento . assumido.
Diretrios anteriores so criados no repositrio, se necessrio.
Nomes Alternativos
Nenhum
Altera
Repositrio
Acessa o Repositrio
Sim
Opes
Exemplos
Isto importa o diretrio local myproj para dentro de trunk/misc em seu repositrio. O diretrio
trunk/misc no precisa existir antes da operaosvn import ir criar diretrios recursivamente
para voc.
Atente que isto no cria um diretrio chamado myproj no repositrio. Se isso o que voc quer,
simplesmente adicione myproj ao final da URL:
220
Referncia Completa
do Subversion
Depois de importar dados, perceba que a rvore original not est sob controle de verso. Para comear
a trabalhar, voc ainda precisa realizar um svn checkout para obter uma nova cpia de trabalho da
rvore.
221
Referncia Completa
do Subversion
Nome
svn info Exibe informao sobre um item local ou remoto.
Sinopse
svn info [TARGET[@REV]...]
Descrio
Exibe informao sobre caminhos na cpia de trabalho ou URLs especificadas. A informao exibida
para ambos pode incluir:
Path
Name
URL
Repository Root
Repository UUID
Revision
Node Kind
Lock Token
Lock Owner
Tipos adicionais de informao disponveis apenas para caminhos em cpias de trabalho so:
Schedule
Checksum
222
Referncia Completa
do Subversion
Nomes Alternativos
Nenhum
Altera
Nada
Acessa o Repositrio
Apenas se operando sobre URLs
Opes
Exemplos
svn info ir mostrar a voc toda a informao til que tiver para itens em sua cpia de trabalho. Ele
exibir informaes sobre arquivos:
223
Referncia Completa
do Subversion
svn info tambm funciona em URLs (perceba tambm que o arquivo readme.doc neste exemplo est
travado, ento a informao da trava tambm exibida):
224
Referncia Completa
do Subversion
Nome
svn list Lista entradas de diretrio no repositrio.
Sinopse
svn list [TARGET[@REV]...]
Descrio
Lista cada arquivo em TARGET e o contedo de cada diretrio em TARGET como existirem no repositrio.
Se TARGET for um caminho em uma cpia de trabalho, a URL correspondente no repositrio ser usada.
Com --verbose, svn list exibe os seguintes campos para cada item:
Com --xml, a sada fica em um formato XML (com um cabealho e um elemento de documento
encapsulador, a menos que --incremental tambm seja especificado). Toda a informao est
presente; a opo --verbose no aceita.
Nomes Alternativos
ls
Altera
Nada
Acessa o Repositrio
Sim
Opes
Exemplos
svn list mais til se voc quiser ver que arquivos um repositrio tem sem precisar obter uma cpia
de trabalho:
225
Referncia Completa
do Subversion
Voc pode passar a opo --verbose para informaes adicionais, similar ao comando UNIX ls -l:
226
Referncia Completa
do Subversion
Nome
svn lock Trava caminhos na cpia de trabalho ou em URLs no repositrio, assim nenhum outro
usurio poder submeter alteraes neles.
Sinopse
svn lock TARGET...
Descrio
Trava cada TARGET. Se algum TARGET j estiver travado por outro usurio, exibe uma mensagem de
aviso e continua travando os demais TARGETs informados. Use --force para roubar uma trava de
outro usurio ou cpia de trabalho.
Nomes Alternativos
Nenhum
Altera
Cpia de trabalho, Repositrio
Acessa o Repositrio
Sim
Opes
--targets FILENAME
--message (-m) TEXT
--file (-F) FILE
--force-log
--encoding ENC
--username USER
--password PASS
--no-auth-cache
--non-interactive
--config-dir DIR
--force
Exemplos
Trava dois arquivos em sua cpia de trabalho:
Trava um arquivo em sua cpia de trabalho que j estava travado por outro usurio:
227
Referncia Completa
do Subversion
228
Referncia Completa
do Subversion
Nome
svn log Exibe as mensagens de log submetidas.
Sinopse
svn log [PATH]
Descrio
Exibe mensagens de log do repositrio. Se nenhum argumento for informado, svn log exibe as
mensagens de log para todos os arquivos e diretrios dentro do diretrio atual (inclusive) de sua cpia
de trabalho. Voc pode refinar os resultados especificando um caminho, uma ou mais revises, ou
qualquer combinao das duas. O intervalo padro de revises para caminhos locais BASE:1.
Se voc especificar uma URL sozinha, ento o comando exibe as mensagens de log para tudo o que a
URL contiver. Se voc adicionar caminhos depois da URL, apenas as mensagens para estes caminhos
sob a URL sero exibidas. O intervalo padro de revises para uma URL HEAD:1.
Com --verbose, svn log tambm ir exibir todos os caminhos afetados com cada mensagem de log.
Com --quiet, svn log no ir exibir o corpo da mensagem de log em si (isto compatvel com --
verbose).
Cada mensagem de log exibida apenas uma vez, mesmo se mais de um dos caminhos afetados por
aquela reviso forem solicitados explicitamente. As mensagens de log seguem o histrico de cpias
por padro. Use --stop-on-copy para desabilitar este comportamento, o que pode ser til para
determinar pontos de ramificao.
Nomes Alternativos
Nenhum
Altera
Nada
Acessa o Repositrio
Sim
Opes
229
Referncia Completa
do Subversion
Exemplos
Voc pode ver as mensagens de log para todos os caminhos que sofreram alteraes em sua cpia
de trabalho, executando svn log a partir da raiz da mesma:
$ svn log
------------------------------------------------------------------------
r20 | harry | 2003-01-17 22:56:19 -0600 (Fri, 17 Jan 2003) | 1 line
Tweak.
------------------------------------------------------------------------
r17 | sally | 2003-01-16 23:21:19 -0600 (Thu, 16 Jan 2003) | 2 lines
Examine todas as mensagens de log para um dado arquivo em sua cpia de trabalho:
Added defines.
------------------------------------------------------------------------
r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines
Se voc no tiver uma cpia de trabalho mo, voc pode obter as mensagens de log a partir de
uma URL:
Added defines.
------------------------------------------------------------------------
r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines
Se voc quiser as mensagens de diversos arquivos sob uma mesma URL, voc pode usar a sintaxe
URL [PATH...].
Added defines.
------------------------------------------------------------------------
r31 | harry | 2003-01-10 12:25:08 -0600 (Fri, 10 Jan 2003) | 1 line
Quando estiver concatenando os resultados de mltiplas chamadas ao comando log, voc tambm
pode usar a opo --incremental. O svn log normalmente exibe uma linha tracejada no comeo de
230
Referncia Completa
do Subversion
cada mensagem de log, depois de cada mensagem de log subsequente, e aps a ltima mensagem
de log. Se voc executou o svn log com um intervalo de revises, voc deve ter obtido isto:
------------------------------------------------------------------------
r15 |
------------------------------------------------------------------------
Entretanto, se voc queria gravar duas mensagens de log no-sequenciais em um arquivo, voc poderia
ter feito algo assim:
------------------------------------------------------------------------
------------------------------------------------------------------------
r19 |
------------------------------------------------------------------------
------------------------------------------------------------------------
r27 |
------------------------------------------------------------------------
Voc pode evitar a baguna das duplas linhas tracejadas em sua sada usando a opo incremental:
------------------------------------------------------------------------
r19 |
------------------------------------------------------------------------
r27 |
A opo --incremental resulta em um controle da sada semelhante tambm quando usada com
a opo --xml.
Se voc executar svn log em um dado especfico e informar uma reviso especfica e no
obtiver nada como sada
231
Referncia Completa
do Subversion
Isto apenas significa que aquele caminho no foi modificado naquela reviso. Se voc
obtiver o log a partir da raiz do repositrio, ou souber o arquivo que foi alterado naquela
reviso, voc pode especific-lo explicitamente:
Made a change.
------------------------------------------------------------------------
232
Referncia Completa
do Subversion
Nome
svn merge Aplica as diferenas entre duas fontes para um caminho numa cpia de trabalho.
Sinopse
svn merge [-c M | -r N:M] SOURCE[@REV] [WCPATH]
Descrio
Na primeira e na segunda formas, os caminhos de origem (URLs na primeira forma, caminhos na cpia
de trabalho na segunda) so especificados nas revises N e M. Estas so as duas fontes a serem
comparadas. A reviso padro, quando omitida, ser HEAD.
A opo -c M equivalente a -r N:M onde N = M-1. Usar -c -M faz o inverso: -r M:N onde N = M-1.
Na terceira forma, SOURCE pode ser uma URL ou um item numa cpia de trabalho, neste caso a URL
correspondente usada. Esta URL, nas revises N e M, define as duas fontes a serem comparadas.
WCPATH o caminho na cpia de trabalho que iro receber as alteraes. Se WCPATH for omitido,
ser assumido . como valor padro, a menos que as fontes tenham nomes de base idnticos que
correspondam a um arquivo dentro de .: neste caso, as diferenas sero aplicadas quele arquivo.
Nomes Alternativos
Nenhum
Altera
Cpia de trabalho
Acessa o Repositrio
Apenas se trabalhando com URLs
Opes
233
Referncia Completa
do Subversion
--non-interactive
--config-dir DIR
Exemplos
Mescla um ramo de volta ao trunk (assumindo que voc tem uma cpia de trabalho de trunk, e que o
ramo tenha sido criado na reviso 250):
Se voc tiver feito a ramificao na reviso 23, e quiser mesclar as alteraes feitas no trunk para seu
ramo, voc pode fazer isto de dentro da cpia de trabalho de seu ramo:
$ cd myproj
$ svn merge -r 30:31 thhgttg.txt
U thhgttg.txt
234
Referncia Completa
do Subversion
Nome
svn mkdir Cria um novo diretrio sob controle de verso.
Sinopse
svn mkdir PATH...
Descrio
Cria um diretrio com o nome dado pelo ltimo componente de PATH ou da URL. Um diretrio
especificado por PATH como um caminho na cpia de trabalho agendado para adio. Um diretrio
especificado por uma URL criado no repositrio por meio de um commit imediato. Mltiplas URLs
de diretrio so submetidas atomicamente. Em ambos os casos, todos os diretrios intermedirios j
devem existir.
Nomes Alternativos
Nenhum
Altera
Cpia de trabalho, repositrio se executando sobre uma URL
Acessa o Repositrio
Apenas se executando sobre uma URL
Opes
Exemplos
Cria um diretrio em sua cpia de trabalho:
Cria um diretrio no repositrio (submisso instantnea, ento uma mensagem de log requerida):
235
Referncia Completa
do Subversion
Nome
svn move Move um arquivo ou diretrio.
Sinopse
svn move SRC DST
Descrio
Este comando move um arquivo ou diretrio em sua cpia de trabalho ou no repositrio.
WC -> WC
Move e agenda um arquivo ou diretrio para adio (com histrico).
Nomes Alternativos
mv, rename, ren
Altera
Cpia de trabalho, repositrio se executando sobre uma URL
Acessa o Repositrio
Apenas se executando sobre uma URL
Opes
Exemplos
Move um arquivo em sua cpia de trabalho:
236
Referncia Completa
do Subversion
Move um arquivo no repositrio (commit imediato, necessitando, ento, de uma mensagem de log):
237
Referncia Completa
do Subversion
Nome
svn propdel Remove uma propriedade de um item.
Sinopse
svn propdel PROPNAME [PATH...]
Descrio
Este comando remove as propriedades de arquivos, diretrios, ou revises. A primeira forma remove
propriedades versionadas em sua cpia de trabalho, enquanto que a segunda remove propriedades
no-versionadas remotas em uma reviso no repositrio (TARGET apenas determina qual repositrio
acessar).
Nomes Alternativos
pdel, pd
Altera
Cpia de trabalho, repositrio apenas se executando sobre uma URL
Acessa o Repositrio
Apenas se executando sobre uma URL
Opes
--quiet (-q)
--recursive (-R)
--revision (-r) REV
--revprop
--username USER
--password PASS
--no-auth-cache
--non-interactive
--config-dir DIR
Exemplos
Remove uma propriedade de um arquivo em sua cpia de trabalho
238
Referncia Completa
do Subversion
Nome
svn propedit Edita a propriedade de um ou mais itens sob controle de verso.
Sinopse
svn propedit PROPNAME PATH...
Descrio
Edita uma ou mais propriedades usando seu editor preferido. A primeira forma edita propriedades
versionadas em sua cpia de trabalho, enquanto que a segunda edita propriedades no-versionadas
remotas em uma reviso de repositrio (TARGET apenas determina qual repositrio acessar).
Nomes Alternativos
pedit, pe
Altera
Cpia de trabalho, repositrio apenas se executando sobre uma URL
Acessa o Repositrio
Apenas se executando sobre uma URL
Opes
Exemplos
svn propedit facilita a modificao de propriedades que tenham mltiplos valores:
239
Referncia Completa
do Subversion
Nome
svn propget Exibe o valor de uma propriedade.
Sinopse
svn propget PROPNAME [TARGET[@REV]...]
Descrio
Exibe o valor de uma propriedade de arquivos, diretrios ou revises. A primeira forma exibe a
propriedade versionada de um item ou itens em sua cpia de trabalho, enquanto que a segunda exibe
propriedades remotas no-versionadas em uma reviso de repositrio. Veja Propriedades para mais
informaes sobre propriedades.
Nomes Alternativos
pget, pg
Altera
Cpia de trabalho, repositrio apenas se executando sobre uma URL
Acessa o Repositrio
Apenas se executando sobre uma URL
Opes
--recursive (-R)
--revision (-r) REV
--revprop
--strict
--username USER
--password PASS
--no-auth-cache
--non-interactive
--config-dir DIR
Exemplos
Examina uma propriedade de um arquivo em sua cpia de trabalho:
240
Referncia Completa
do Subversion
Nome
svn proplist Lista todas as propriedades.
Sinopse
svn proplist [TARGET[@REV]...]
Descrio
Lista todas as propriedades de arquivos, diretrios, ou revises. A primeira forma lista propriedades
versionadas em sua cpia de trabalho, enquanto que a segunda lista propriedades remotas no-
versionadas em uma reviso de repositrio (TARGET apenas determina que repositrio acessar).
Nomes Alternativos
plist, pl
Altera
Cpia de trabalho, repositrio apenas se executando sobre uma URL
Acessa o Repositrio
Apenas se executando sobre uma URL
Opes
--verbose (-v)
--recursive (-R)
--revision (-r) REV
--quiet (-q)
--revprop
--username USER
--password PASS
--no-auth-cache
--non-interactive
--config-dir DIR
Exemplos
Voc pode usar proplist para ver as propriedades de um item em sua cpia de trabalho:
Mas com a opo --verbose, o svn proplist torna-se extremamente til pois tambm lhe mostra os
valores das propriedades:
241
Referncia Completa
do Subversion
svn:mime-type : text/plain
svn:keywords : Author Date Rev
owner : sally
242
Referncia Completa
do Subversion
Nome
svn propset Define PROPNAME para PROPVAL em arquivos, diretrios, ou revises.
Sinopse
svn propset PROPNAME [PROPVAL | -F VALFILE] PATH...
Descrio
Define PROPNAME para PROPVAL em arquivos, diretrios, ou revises. O primeiro exemplo cria
uma modificao numa propriedade local, versionada, na cpia de trabalho; e o segundo cria uma
modificao numa propriedade remota, no-versionada, em uma reviso de repositrio (TARGET
apenas determina que repositrio acessar).
Nomes Alternativos
pset, ps
Altera
Cpia de trabalho, repositrio apenas se executando sobre uma URL
Acessa o Repositrio
Apenas se executando sobre uma URL
Opes
Exemplos
Define o tipo mime de um arquivo:
Em um sistema UNIX, se voc quiser que um arquivo tenha a permisso de execuo definida:
243
Referncia Completa
do Subversion
Talvez voc tenha uma poltica interna que defina certas propriedades para beneficiar seus
colaboradores:
Se voc se enganar escrevendo uma mensagem de log para uma dada reviso e quiser mud-la, use
--revprop e atribua o valor de svn:log para a nova mensagem de log:
Ou, se voc no tiver uma cpia de trabalho, voc pode informar uma URL.
Por fim, voc pode informar ao propset para obter suas entradas a partir de um arquivo. Voc ainda
pode usar isso para definir o contedo de uma propriedade para qualquer valor binrio:
244
Referncia Completa
do Subversion
Nome
svn resolved Remove arquivo ou diretrios da cpia de trabalho do estado de conflito.
Sinopse
svn resolved PATH...
Descrio
Remove o estado de conflito em arquivos ou diretrios numa cpia de trabalho. Esta rotina no resolve
marcadores de conflito semanticamente; ele apenas remove os arquivos auxiliares relacionados ao
conflito e permite que o PATH possa ser submetido novamente; isto , ele informa ao Subversion que o
conflito foi resolvido. Leia Resolvendo Conflitos (Combinando Alteraes de Outros) para uma viso
mais aprofundada sobre resoluo de conflitos.
Nomes Alternativos
Nenhum
Altera
Cpia de trabalho
Acessa o Repositrio
No
Opes
--targets FILENAME
--recursive (-R)
--quiet (-q)
--config-dir DIR
Exemplos
Se voc obtiver um conflito em uma atualizao, sua cpia de trabalho ir gerar trs novos arquivos:
$ svn update
C foo.c
Updated to revision 31.
$ ls
foo.c
foo.c.mine
foo.c.r30
foo.c.r31
Uma vez que voc tenha resolvido o conflito e que foo.c esteja pronto para ser submetido, execute o
comando svn resolved para fazer com que sua cpia de trabalho saiba que voc j cuidou de tudo.
245
Referncia Completa
do Subversion
Nome
svn revert Desfaz todas as edies locais.
Sinopse
svn revert PATH...
Descrio
Reverte quaisquer alteraes feitas em um arquivo ou diretrio e resolve quaisquer estados de
conflito. svn revert no apenas ir reverter o contedo de um item em sua cpia de trabalho mas
tambm quaisquer modificao de propriedades. Finalmente, voc pode us-lo para desfazer qualquer
operao de agendamento que voc possa ter feito (p.ex., arquivos agendados para adio ou remoo
podem ser desagendados).
Nomes Alternativos
Nenhum
Altera
Cpia de trabalho
Acessa o Repositrio
No
Opes
--targets FILENAME
--recursive (-R)
--quiet (-q)
--config-dir DIR
Exemplos
Descarta as alteraes em um arquivo:
246
Referncia Completa
do Subversion
$ svn status
? mistake.txt
? whoops
O svn revert intrinsecamente perigoso, j que todo o seu propsito descartar dados
especificamente, modificaes no submetidas ao repositrio. Uma vez que voc tenha
feito uma reverso, o Subversion no disponibiliza nenhuma forma de obter estes dados
de suas alteraes no submetidas.
Se voc no informar um alvo para o svn revert, ele no far nadapara proteg-lo de
perder suas alteraes acidentalmente em sua cpia de trabalho, o svn revert requer que
voc informe pelo menos um alvo.
247
Referncia Completa
do Subversion
Nome
svn status Exibe informao sobre o estado de arquivos e diretrios na cpia de trabalho.
Sinopse
svn status [PATH...]
Descrio
Exibe informao sobre o estado de arquivos e diretrios na cpia de trabalho. Sem argumentos, o
comando exibe apenas os itens modificados localmente (sem acesso ao repositrio). Com --show-
updates, ele adiciona informao sobre a reviso de trabalho e informaes defasadas de servidor.
Com --verbose, exibe informaes completas sobre reviso de cada item.
As primeiras seis colunas na sada tm um caractere de largura cada, e cada coluna lhe d informao
sobre diferentes aspectos de cada item na cpia de trabalho.
A primeira coluna indica que um item foi adicionado, removido, ou ento alterado.
''
Sem modificaes.
'A'
O item foi agendado para adio.
'D'
O item foi agendado para remoo (deleo).
'M'
O item est sendo modificado.
'R'
O item foi substitudo em sua cpia de trabalho. Isto significa que o arquivo foi agendado para
remoo, e ento um novo arquivo com o mesmo nome foi agendado para adio em seu lugar.
'C'
O contedo (ao contrrio das propriedades) do item entra em conflito com as atualizaes recebidas
do repositrio.
'X'
O item est presente devido a uma definio externa.
'I'
O item est sendo ignorado (p.ex., com a propriedade svn:ignore).
'?'
O item no est sob controle de verso.
'!'
O item est faltando (p.ex., voc o moveu ou removeu sem usar o svn). Isto tambm indica que
um diretrio est incompleto (uma operao de checkout ou update foi interrompida).
'~'
O item est versionado como um tipo de objeto ( arquivo, diretrio, link), mas est sendo substitudo
por um tipo diferente de objeto.
''
Sem modificaes.
248
Referncia Completa
do Subversion
'M'
Propriedades deste item foram modificadas.
'C'
As propriedades para este item entram em conflito com as atualizaes de propriedades recebidas
do repositrio.
A terceira coluna preenchida apenas se a cpia de trabalho estiver travada. (Veja s Vezes Voc
S Precisa Limpar.)
''
O item no est travado.
'L'
O item est travado.
A quarta coluna preenchida se o item estiver agendado para adio com histrico.
''
O histrico no est agendado para submisso.
'+'
O histrico est agendado para submisso.
A quinta coluna preenchida apenas se o item tiver sido trocado relativo a seus diretrios anteriores
(veja Atravessando Ramos).
''
O item filho de seu diretrio pai.
'S'
O item foi trocado.
''
Quando --show-updates usado, o arquivo no est travado. Se --show-updates no
usado, isto apenas significa que o arquivo no est travado nesta cpia de trabalho.
K
O arquivo est travado nesta cpia de trabalho.
O
O arquivo ou est travado por outro usurio ou em outra cpia de trabalho. Isto s aparece quando
--show-updates usado.
T
O arquivo estava travado nesta cpia de trabalho, mas a trava foi roubada e est invlida. O
arquivo atualmente est travado no repositrio. Isto s aparece quando --show-updates usado.
B
O arquivo estava travado nesta cpia de trabalho, mas a trava est sendo quebrada e est
invlida. O arquivo no est mais travado. Isto s aparece quando --show-updates usado
A informao defasada aparece na stima coluna (apenas se voc passar a opo --show-updates).
''
O item em sua cpia de trabalho est atualizado.
'*'
Uma nova reviso do item existe no servidor.
249
Referncia Completa
do Subversion
Se a opo --verbose for passada, a ltima reviso submetida e o ltimo autor so exibidos na
sequncia.
O caminho na cpia de trabalho sempre o ltimo campo, ento ele pode incluir espaos.
Nomes Alternativos
stat, st
Altera
Nada
Acessa o Repositrio
Apenas quando usando --show-updates
Opes
--show-updates (-u)
--verbose (-v)
--non-recursive (-N)
--quiet (-q)
--no-ignore
--username USER
--password PASS
--no-auth-cache
--non-interactive
--config-dir DIR
--ignore-externals
Exemplos
Esta a forma mais fcil de encontrar quais alteraes voc fez em sua cpia de trabalho:
$ svn status wc
M wc/bar.c
A + wc/qax.c
Se voc quiser encontrar quais arquivos em sua cpia de trabalho esto desatualizados, passe a opo
--show-updates (isto no faz quaisquer alteraes em sua cpia de trabalho). Aqui voc pode ver
que wc/foo.c foi modificado no repositrio desde a ltima atualizao em sua cpia de trabalho:
250
Referncia Completa
do Subversion
E finalmente, o mximo de informao que voc pode obter com o subcomando status:
Para mais exemplos de svn status, veja Obtendo uma viso geral de suas alteraes.
251
Referncia Completa
do Subversion
Nome
svn switch Atualiza a cpia de trabalho para uma URL diferente.
Sinopse
svn switch URL [PATH]
Descrio
A primeira variante deste subcomando (sem a opo --relocate) atualiza sua cpia de trabalho
para apontar para uma nova URLfrequentemente uma URL que compartilhe um ancestral comum
com sua cpia de trabalho, apesar de no ser necessrio. Esta a forma que o Subversion usa para
mover uma cpia de trabalho para um novo ramo. Consulte Atravessando Ramos para uma viso
mais aprofundada sobre este recurso.
A opo --relocate faz com que o svn switch execute algo diferente: ele atualiza sua cpia de
trabalho para apontar para o mesmo diretrio no repositrio, apenas numa URL diferente (tipicamente
porque um administrador moveu o repositrio para um outro servidor, ou para outra URL no mesmo
servidor).
Nomes Alternativos
sw
Altera
Cpia de trabalho
Acessa o Repositrio
Sim
Opes
Exemplos
Se voc atualmente dentro do diretrio vendors, o qual foi ramificado para vendors-with-fix, e
voc gostaria de trocar sua cpia de trabalho para esse ramo:
252
Referncia Completa
do Subversion
U myproj/qux.c
Updated to revision 31.
A para trocar de volta, apenas informa a URL para o local no repositrio a partir do qual voc
originalmente obteve sua cpia de trabalho:
Voc pode apenas trocar parte de sua cpia de trabalho para um ramo se voc no quiser
trocar toda a sua cpia de trabalho.
Algumas vezes um administrador pode mudar a localizao base de seu repositrioem outras
palavras, o contedo do repositrio no muda, mas a URL principal que d acesso raiz do repositrio
sim. Por exemplo, o nome do host pode mudar, o esquema da URL pode mudar, ou qualquer parte da
URL relacionada ao repositrio em si pode mudar. Ao invs de obter (check out) uma nova cpia de
trabalho, voc pode fazer com que o comando svn switch reescreva os comeos de todas as URLs
em sua cpia de trabalho. Use a opo --relocate para fazer a substituio. Nenhum contedo de
arquivo modificado, nem sequer o repositrio contactado. semelhante a executar um script em
Perl sobre os diretrios .svn/ de sua cpia de trabalho, executando s/OldRoot/NewRoot/.
$ mv repos newlocation
$ cd test/
$ svn update
svn: Unable to open an ra_local session to URL
svn: Unable to open repository 'file:///tmp/repos'
Se sua cpia de trabalho precisar refletir um novo diretrio dentro do repositrio, ento
apenas use svn switch.
253
Referncia Completa
do Subversion
Nome
svn unlock Destrava caminhos na cpia de trabalho ou URLs.
Sinopse
svn unlock TARGET...
Descrio
Destrava cada TARGET. Se algum TARGET estiver ou travado por outro usurio ou se nenhum token
de travamento vlido existir na cpia de trabalho, exibe um aviso e continua destravando os demais
TARGETs. Use --force para quebrar uma trava que pertena a outro usurio na cpia de trabalho.
Nomes Alternativos
Nenhum
Altera
Cpia de trabalho, Repositrio
Acessa o Repositrio
Sim
Opes
--targets FILENAME
--username USER
--password PASS
--no-auth-cache
--non-interactive
--config-dir DIR
--force
Exemplos
Destrava dois arquivos em sua cpia de trabalho:
Destrava um arquivo em sua cpia de trabalho que j est travado por outro usurio:
254
Referncia Completa
do Subversion
'tree.jpg unlocked.
255
Referncia Completa
do Subversion
Nome
svn update Update your working copy.
Sinopse
svn update [PATH...]
Descrio
svn update traz as alteraes do repositrio para sua cpia de trabalho. Se nenhuma reviso for
informada, ele atualiza sua cpia de trabalho para a reviso HEAD. Do contrrio, ele sincroniza a cpia
de trabalho para a reviso dada pela opo --revision. Como parte da sincronizao, o svn update
tambm remove quaisquer travas roubadas (veja s Vezes Voc S Precisa Limpar) encontradas na
cpia de trabalho.
Para cada item atualizado, o comando exibe uma linha que inicia com um caractere informando a ao
tomada. Estes caracteres tm o seguinte significado:
A
Adicionado
D
Removido (deleted)
U
Atualizado (updated)
C
Em conflito
G
Mesclado (merged)
Um caractere na primeira coluna significa uma atualizao no arquivo atual, que atualizou as
propriedades do arquivo mostradas na segunda coluna.
Nomes Alternativos
up
Altera
Cpia de trabalho
Acessa o Repositrio
Sim
Opes
256
Referncia Completa
do Subversion
--password PASS
--no-auth-cache
--non-interactive
--config-dir DIR
--ignore-externals
Exemplos
Obtm as alteraes do repositrio que ocorreram desde a ltima operao de update:
$ svn update
A newdir/toggle.c
A newdir/disclose.c
A newdir/launch.c
D newdir/README
Updated to revision 32.
Voc tambm pode atualizar sua cpia de trabalho para uma reviso mais antiga (o Subversion no
tem o conceito de arquivos aderentes (sticky) que o CVS tem; consulte Apndice B, Subversion para
Usurios de CVS):
Se voc quiser examinar uma reviso mais antiga de um nico arquivo, voc pode querer
usar svn cat no lugarele no altera sua cpia de trabalho.
svnadmin
O svnadmin a ferramenta administrativa para monitoramento e manuteno de seu repositrio
Subversion. Para informaes detalhadas, veja svnadmin.
Como o svnadmin trabalha com acesso direto ao repositrio (e assim s pode ser usado na prpria
mquina onde se encontra o repositrio), ele se refere ao repositrio com um caminho e no com uma
URL.
Opes do svnadmin
--bdb-log-keep
(Especfica para o Berkeley DB) Desabilita remoo automtica de log dos arquivos de loga da
base de dados. Manter esses arquivos de log pode ser conveniente se voc precisar fazer uma
restaurao aps uma falha catastrfica no repositrio.
--bdb-txn-nosync
(Especfica para o Berkeley DB) Desabilita o fsync ao submeter transaes na base de dados.
Usada com o comando svnadmin create para criar um repositrio baseado em Berkeley DB com
DB_TXN_NOSYNC habilitado (o que melhora a velocidade mas possui riscos associados).
--bypass-hooks
Ignora o sistema de scripts de ganchos do repositrio.
257
Referncia Completa
do Subversion
--clean-logs
Remove logs no utilizados do Berkeley DB logs.
--force-uuid
Por padro, ao carregar dados no repositrio que j contenha revises, o svnadmin vai ignorar o
UUID a partir do fluxo de despejo (dump stream). Esta opo far com que o UUID do repositrio
seja definido para o mesmo UUID do fluxo.
--ignore-uuid
Por padro, ao carregar dados no repositrio que j contenha revises, o svnadmin vai ignorar o
UUID a partir do fluxo de despejo. Esta opo vai fazer com que o UUID seja ignorado (til para
sobrescrever seu arquivo de configurao se ele estava com --force-uuid definido).
--incremental
Despeja uma reviso apenas como um diff relativo reviso anterior, ao invs do texto completo,
que o normal.
--parent-dir DIR
Ao carregar um arquivo de despejo, considera os caminhos razes em DIR ao invs de em /.
--quiet
No exibe o progresso normalmostra apenas erros.
--use-post-commit-hook
Ao carregar um arquivo de despejo, executa os scripts de hook de post-commit do repositrio
depois de terminar com cada reviso recm carregada.
--use-pre-commit-hook
Ao carregar um arquivo de despejo, executa os scripts de hook de pre-commit do repositrio antes
de terminar com cada reviso recm carregada. Se o script falhar, aborta a operao e encerra
o processo de carga.
Subcomandos do svnadmin
258
Referncia Completa
do Subversion
Nome
svnadmin create Cria um novo repositrio vazio.
Sinopse
svnadmin create REPOS_PATH
Descrio
Cria um novo repositrio vazio no caminho dado. Se o diretrio informado no existir, ele ser criado
1
para voc. Desde o Subversion 1.2, o svnadmin cria novos repositrios baseados no sistema de
arquivos fsfs por padro.
Opes
--bdb-txn-nosync
--bdb-log-keep
--config-dir DIR
--fs-type TYPE
Exemplos
Criar um novo repositrio bem fcil:
No Subversion 1.0, sempre criado um repositrio do tipo Berkeley DB. No Subversion 1.1, Berkeley
DB o tipo de repositrio padro, mas um repositrio FSFS pode ser criado com a opo --fs-type:
1
Lembre-se, o svnadmin s trabalha com caminhos locais e no com URLs.
259
Referncia Completa
do Subversion
Nome
svnadmin deltify Deltifica os caminhos modificados em um intervalo de revises.
Sinopse
svnadmin deltify [-r LOWER[:UPPER]] REPOS_PATH
Descrio
svnadmin deltify existe nas verses atuais do Subversion apenas por razes histricas. Este comando
obsoleto e no tem mais utilidade.
Esse comando vem do tempo em que o Subversion oferecia aos administratores um grande controle
sobre estratgias de compactao no repositrio. Isto mostrou-se ser algo de muito complexo (muito
custo) para pouqussimo ganho (pouco benefcio), e este recurso hoje est depreciado.
Opes
260
Referncia Completa
do Subversion
Nome
svnadmin dump Despeja o contedo do sistema de arquivos para o stdout.
Sinopse
svnadmin dump REPOS_PATH [-r LOWER[:UPPER]] [--incremental]
Descrio
Despeja o contedo do sistema de arquivos para o stdout em um formato portvel de dumpfile,
enviando mensagens de feedback para stderr. Despeja as revises de LOWER rev at UPPER rev.
Se revises no forem informadas, despeja todas as rvores de revises. Se somente LOWER for
informada, ento essa rvore de reviso ser despejada. Veja Migrando Dados do Repositrio Para
Outro Local para exemplos prticos de uso.
Por padro, o fluxo do arquivo de despejo do Subversion contm uma nica reviso (a primeira reviso
no intervalo de revises) em que cada arquivo e diretrio no repositrio naquela reviso est presente
tal como se a rvore completa tivesse sido adicionada de uma s vez, seguido de outras revises (o
restante das revises no intervalo informado) as quais contm somente os arquivos e diretrio que
foram modificados nessas revises. Para um arquivo no modificado, a representao completa de
seu contedo, bem como todas as suas propriedades, so apresentadas no arquivo de despejo; para
um diretrio, todas as suas propriedades so apresentadas.
H duas opes teis que modificam o comportamento do gerador do arquivo de despejo. A primeira
a opo --incremental, a qual simplesmente faz com que a primeira reviso no fluxo do arquivo
contenha apenas os arquivos e diretrios modificados naquela reviso, ao invs de serem apresentadas
como adies de uma nova rvore, e exatamente da mesma maneira que qualquer outra reviso no
arquivo de despejo apresentada. Isto til para gerar arquivos de despejo relativamente pequenos
para serem carregados em outro repositrio que j possua os arquivos e diretrios existentes no
repositrio original.
A segunda opo til --deltas. Esta opo faz com que o svnadmin dump, ao invs
de emitir representaes completas dos contedos de arquivos e listas de propriedades, emita
apenas as diferenas desses itens relativas a suas verses anteriores. Isto reduz (em alguns
casos, drasticamente) o tamanho do arquivo de despejo criado pelo svnadmin dump. H, porm,
algumas desvantagens em se usar esta opoarquivos de despejo deltificados precisam de mais
processamento de CPU para serem criados, no podem ser utilizados com svndumpfilter e tendem
a no serem compactados to bem quanto seus correspondentes normais quando ferramentas de
compactao externas, como o gzip e o bzip2, so usadas.
Opes
Exemplos
Despeja todo o seu repositrio:
261
Referncia Completa
do Subversion
Content-length: 56
262
Referncia Completa
do Subversion
Nome
svnadmin help Help!
Sinopse
svnadmin help [SUBCOMMAND...]
Descrio
Este comando til quando voc estiver perdido em uma ilha deserta e no tiver uma conexo de
Internet e nem mesmo uma cpia deste livro.
Nomes Alternativos
?, h
263
Referncia Completa
do Subversion
Nome
svnadmin hotcopy Faz uma cpia a quente do repositrio.
Sinopse
svnadmin hotcopy REPOS_PATH NEW_REPOS_PATH
Descrio
Este subcomando faz um backup completo a quente de seu repositrio, incluindo todos os scripts de
hook, arquivos de configurao, e, claro, os arquivos da base de dados. Se voc passar a opo
--clean-logs, o svnadmin vai executar uma cpia a quante de seu repositrio, e ento remover
arquivos de log no utilizados do Berkeley DB de seu repositrio original. Voc pode executar este
comando a qualquer momento e fazer uma cpia de segurana do repositrio, independentemente de
que outros processos estejam usando o repositrio.
Opes
--clean-logs
Como descrito em Berkeley DB, repositrios Berkeley DB que sejam copiados a quente
no so portveis para outros sistemas operacionais, e tambm no iro funcionar em
mquinas com finalidades distintas que a da mquina em que foram criados.
264
Referncia Completa
do Subversion
Nome
svnadmin list-dblogs Solicita ao Berkeley DB informao sobre quais arquivos de log existem para
um dado repositrio do Subversion (se aplica apenas a repositrio baseados em bdb).
Sinopse
svnadmin list-dblogs REPOS_PATH
Descrio
O Berkeley DB cria logs de todas as modificaes no repositrio, o que lhe permite se recuperar de
alguma eventual catstrofe. A menos que voc habilite DB_LOG_AUTOREMOVE, os arquivos de log se
acumulam, ainda que a maioria no seja mais usada e possa ser normalmente excluda para liberao
de espao em disco. Veja Gerenciando Espao em Disco para mais informaes.
265
Referncia Completa
do Subversion
Nome
svnadmin list-unused-dblogs Solicita ao Ask Berkeley DB informao sobre quais arquivos de log
podem ser seguramente excludos (se aplica apenas a repositrios baseados em bdb).
Sinopse
svnadmin list-unused-dblogs REPOS_PATH
Descrio
O Berkeley DB cria logs de todas as modificaes no repositrio, o que lhe permite se recuperar de
alguma eventual catstrofe. A menos que voc habilite DB_LOG_AUTOREMOVE, os arquivos de log se
acumulam, ainda que a maioria no seja mais usada e possa ser normalmente excluda para liberao
de espao em disco. Veja Gerenciando Espao em Disco para mais informaes.
Exemplos
Remove todos osa rquivos de log no usados de um repositrio:
266
Referncia Completa
do Subversion
Nome
svnadmin load L uma entrada no formato de um arquivo de despejo a partir de stdin.
Sinopse
svnadmin load REPOS_PATH
Descrio
L uma entrada no formato de um arquivo de despejo a partir de stdin, submetendo novas revises para
o sistema de arquivos do repositrio. Envia informao sobre o andamento da operao para stdout.
Opes
--quiet (-q)
--ignore-uuid
--force-uuid
--use-pre-commit-hook
--use-post-commit-hook
--parent-dir
Exemplos
Isto mostra o comeo da carga de um repositrio a partir de um arquivo de backup (feito, obviamente,
com svnadmin dump):
267
Referncia Completa
do Subversion
Nome
svnadmin lslocks Exibe a descrio de todas as travas.
Sinopse
svnadmin lslocks REPOS_PATH
Descrio
Exibe a descrio de todas as travas em um repositrio.
Opes
Nenhum
Exemplo
Isto lista o arquivo travado no repositrio em /svn/repos:
268
Referncia Completa
do Subversion
Nome
svnadmin lstxns Exibe os nomes de todas as transaes no submetidas.
Sinopse
svnadmin lstxns REPOS_PATH
Descrio
Exibe os nomes de todas as transaes no submetidas. Veja Removendo transaes mortas para
informao sobre como transaes no submetidas so criadas e sobre como voc deveria lidar com
elas.
Exemplos
Lista todas as transaes pendentes em um repositrio.
269
Referncia Completa
do Subversion
Nome
svnadmin recover Traz uma base de dados de repositrio de volta a um estado consistente (se
aplica apenas a repositrios baseados em bdb). Alm disso, se repos/conf/passwd no existir, ele
vai criar um arquivo de senhas padro.
Sinopse
svnadmin recover REPOS_PATH
Descrio
Execute este comando se voc obtiver uma indicao de erro dizendo que seu repositrio precisa ser
recuperado.
Opes
--wait
Exemplos
Recupera um repositrio problemtico:
Recovery completed.
The latest repos revision is 34.
Recuperar a base de dados precisa de uma trava exclusiva no repositrio. (Esta uma trava da base
de dados; veja Os trs significados de trava.) Se outro processo estiver acessando o repositrio, ento
o svnadmin recover ir falhar:
A opo --wait, entretanto, vai fazer com que o svnadmin recover aguarde indefinidamente at que
os outros processo se desconectem:
Recovery completed.
The latest repos revision is 34.
270
Referncia Completa
do Subversion
Nome
svnadmin rmlocks Remove, incondicionalmente, uma ou mais travas de um repositrio.
Sinopse
svnadmin rmlocks REPOS_PATH LOCKED_PATH...
Descrio
Remove a trava de cada um dos itens em LOCKED_PATH.
Opes
Nenhum
Exemplo
Isto remove as travas em tree.jpg e house.jpg no repositrio em /svn/repos
271
Referncia Completa
do Subversion
Nome
svnadmin rmtxns Exclui transaes de um repositrio.
Sinopse
svnadmin rmtxns REPOS_PATH TXN_NAME...
Descrio
Exclui transaes pendentes de um repositrio. Este subcomando coberto em detalhes em
Removendo transaes mortas.
Opes
--quiet (-q)
Exemplos
Exclui transaes nomeadas:
272
Referncia Completa
do Subversion
Nome
svnadmin setlog Define a mensagem de log de uma reviso.
Sinopse
svnadmin setlog REPOS_PATH -r REVISION FILE
Descrio
Define a mensagem de log da reviso REVISION para o contedo de FILE.
Isto similar a se usar svn propset --revprop para definir a propriedade svn:log de uma reviso,
exceto que voc tambm pode usar a opo --bypass-hooks para previnir que qualquer script de
hook pre- ou post-commit seja executado, o que til se a modificao nas propriedades da reviso
no estava habilitada no script pre-revprop-change.
Opes
Exemplos
Define a mensagem de log da reviso 19 para o contedo do arquivo msg:
273
Referncia Completa
do Subversion
Nome
svnadmin verify Verifica os dados armazenados no repositrio.
Sinopse
svnadmin verify REPOS_PATH
Descrio
Execute este comando se voc quiser verificar a integridade de seu repositrio. Ele basicamente itera
por todas as revises no repositrio despejando todas as revises internamente e descartando a sada
uma boa idia executar este comando regularmente para se previnir contra falhas latentes do disco
rgido e bitrot. Se este comando falharo que ocorrer quando encontrar o primeiro sinal de algum
problemaisso quer dizer que seu repositrio tem pelo menos uma reviso corrompida e que voc
deveria restaurar tal reviso corrompida a partir de um backup (voc faz backups sempre, no faz?).
Exemplo
Verifica um repositrio problemtico:
svnlook
svnlook um comando de console til para examinar diferentes aspectos do repositrio Subversion.
Ele no faz nenhuma mudana no repositrio usado mesmo para dar uma dar uma espiada.
svnlook usando tipicamente usado pelos hooks do repositrio, mas o administrador do repositrio
pode ach-lo til como ferramente de diagnstico.
J que svnlook funciona via acesso direto ao repositrio, (e por isso s pode ser usado em mquinas
que tenham repositrios), ele se refere ao repositrio por um caminho, no uma URL.
Se nenhuma reviso ou transao for especificada, o padro do svnlook da reviso mais jovem(mais
recente) do repositrio.
Opes do svnlook
Opes no svnlook so globais, assim como no svn e svnadmin; entretanto, a maioria das opes
apenas se aplicam a um commando j que as funcionalidades do svnlook (intencionalmente) limitado
ao escopo.
--no-diff-deleted
Previne o svnlook de mostrar as diferenas entre arquivos deletados. O comportamento padro
quando um arquivo deletado numa transao/reviso mostrar as mesmas diferenas que voc
veria se tivesse deixado o arquivo mas apagado seu conteudo.
--revision (-r)
Especifica uma reviso em particular que voc deseja examinar.
--revprop
Opera uma propriedade da reviso ao invs da propriedade especificada para o arquivo ou diretrio.
Essa opo exige que voc passe a reviso com a opo --revision (-r).
--transaction (-t)
Especifica um ID de transao particular que voc deseja examinar.
274
Referncia Completa
do Subversion
--show-ids
Mostrar o ID da reviso do nodo do sistema de arquivos para cada caminho da rvore do sistema
de arquivos.
Sub-comandos do svnlook
275
Referncia Completa
do Subversion
Nome
autor svnlook Mostrar o autor.
Sinopse
svnlook author REPOS_PATH
Descrio
Mostrar o autor da reviso ou transao no repositrio.
Opes
Exemplos
svnlook author til, mas no muito excitante:
276
Referncia Completa
do Subversion
Nome
svnlook cat Mostra o conteudo de um arquivo.
Sinopse
svnlook cat REPOS_PATH PATH_IN_REPOS
Descrio
Mostra o conteudo de um arquivo.
Opes
Exemplos
Isto motra o conteudo de um arquivo em uma transao ax8, localizado no /trunk/README:
Contents:
I. A FEW POINTERS
II. DOCUMENTATION
III. PARTICIPATING IN THE SUBVERSION COMMUNITY
277
Referncia Completa
do Subversion
Nome
svnlook changed Mostra os caminhos que foram mudados.
Sinopse
svnlook changed REPOS_PATH
Descrio
Mostra os caminhos que foram mudados em uma reviso ou transao particular, assim como svn
update-style as letras de estatus nas duas primeiras colunas:
'A '
Item adicionado ao repositrio.
'D '
Item apagado do respostrio.
'U '
Contedo do arquivo foi mudado.
' U'
Propriedades do tem mudados.--FIXME Note the leading space.--
'UU'
Conteudo e propriedades mudados.
Arquivos e diretrios podem ser distinguidos, como os caminhos dos diretrios so mostrados com
caracter '/'.
Opes
Exemplos
Isto mostra a lista de todos os diretrios e arquivos mudados na reviso 39 em um diretrio de teste.
Note que a primeira mudana um diretrio, como evidenciado pela /:
278
Referncia Completa
do Subversion
Nome
svnlook date Mostrar data-hora.
Sinopse
svnlook date REPOS_PATH
Descrio
Mostrar data-hora de uma reviso ou transao em um repositrio.
Opes
Exemplos
Mostra a data da reviso 40 de um repositrio de teste:
279
Referncia Completa
do Subversion
Nome
svnlook diff Mostra diferenas de arquivos e propriedades que foram mudados.
Sinopse
svnlook diff REPOS_PATH
Descrio
Mostra no estilo GNU diferenasde arquivos e propriedades que foram mudados.
Opes
Exemplos
Isto mostra um novo arquivo adicionado, deletado e copiado:
Added: trunk/vendors/deli/soda.txt
==============================================================================
Modified: trunk/vendors/deli/sandwich.txt
==============================================================================
--- trunk/vendors/deli/sandwich.txt (original)
+++ trunk/vendors/deli/sandwich.txt 2003-02-22 17:45:04.000000000 -0600
@@ -0,0 +1 @@
+Don't forget the mayo!
Modified: trunk/vendors/deli/logo.jpg
==============================================================================
(Binary files differ)
Deleted: trunk/vendors/deli/chips.txt
==============================================================================
Deleted: trunk/vendors/deli/pickle.txt
==============================================================================
280
Referncia Completa
do Subversion
Nome
svnlook dirs-changed Mostra os diretrios que foram mudados.
Sinopse
svnlook dirs-changed REPOS_PATH
Descrio
Mostra os diretrios que foram mudados (edio de propriedade) ou tiveram seus filhos mudados.
Opes
Exemplos
Isto mostra os difertrios que foram mudados na reviso 40 no nosso respostrio de exemplo:
281
Referncia Completa
do Subversion
Nome
svnlook help Help!
Sinopses
Tambm svnlook -h e svnlook -?.
Descrio
Mostra a mensagem de ajuda para o svnlook. Este comando, como seu irmo svn help, tambm seu
amigo, mesmo que voc no ligue mais pra ele e tenha esquecido de convida-lo para sua ltima festa.
Nomes alternativos
?, h
282
Referncia Completa
do Subversion
Nome
svnlook history Mostra informes sobre o histrico de um caminhos em um repositrio (ou da raiz
do diretrio se nenhum caminho for informado).
Sinopse
svnlook history REPOS_PATH [PATH_IN_REPOS]
Descrio
Mostra informaes sobre histrico de um caminho em um repositrio (ou da raiz do diretrio se nenhum
caminho for informado).
Opes
Exemplos
Isto mostra o histrico de um caminho /tags/1.0 da reviso 20 no nosso repositrio de exemplo.
283
Referncia Completa
do Subversion
Nome
svnlook info Mostra o autor, data-hora, tamanho da mensagem de log, e a mensagem de log.
Sinopse
svnlook info REPOS_PATH
Descrio
Mostra o autor, data-hora, tamanho da mensagem de log, e a mensagem de log.
Opes
Exemplos
Isto mostra a sada para a reviso 40 no nosso repositrio de exemplo.
284
Referncia Completa
do Subversion
Nome
svnlook lock Se o lock existir no caminho do repositrio, o descreve.
Sinopse
svnlook lock REPOS_PATH PATH_IN_REPOS
Descrio
Mostra todas as informaes disponveis para o lock no PATH_IN_REPOS. Se PATH_IN_REPOS no
estiver lockado, no mostra nada.
Opes
Nada
Exemplos
Descreve o lock do arquivo tree.jpg.
285
Referncia Completa
do Subversion
Nome
svnlook log Mostra a mensagem de log.
Sinopse
svnlook log REPOS_PATH
Descrio
Mostra a mensagem de log.
Opes
Exemplos
Isto mostra o log de sada para a reviso 40 no nosso repositrio de exemplo:
286
Referncia Completa
do Subversion
Nome
svnlook propget Exibe o valor cru de uma propriedade em um caminho no repositrio.
Sinopse
svnlook propget REPOS_PATH PROPNAME [PATH_IN_REPOS]
Descrio
Lista o valor de uma propriedade em um caminho no repositrio.
Nomes Alternativos
pg, pget
Opes
Exemplos
Isto mostra o valor da propriedade seasonings do arquivo /trunk/sandwich na reviso HEAD:
287
Referncia Completa
do Subversion
Nome
svnlook proplist Exibe os nomes e valores de propriedades de arquivos e diretrios versionados.
Sinopse
svnlook proplist REPOS_PATH [PATH_IN_REPOS]
Descrio
Lista as propriedades de um caminho no repositrio. Com --verbose, tambm exibe os valores das
propriedades.
Nomes Alternativos
pl, plist
Opes
Exemplos
Isto mostra os nomes das propriedades definidas para o arquivo /trunk/README na reviso HEAD:
Este o mesmo comando do exemplo anterior, mas desta vez mostrando os valores das propriedades
tambm:
288
Referncia Completa
do Subversion
Nome
svnlook tree Exibe a rvore.
Sinopse
svnlook tree REPOS_PATH [PATH_IN_REPOS]
Descrio
Exibe a rvore, comeando em PATH_IN_REPOS (se informado, ou da raiz da rvore em caso
contrrio), opcionalmente mostra os IDs das revises dos ns.
Opes
Exemplos
Isto mostra a rvore de sada (com os IDs dos ns) para a reviso 40 em nosso repositrio de exemplo:
289
Referncia Completa
do Subversion
Nome
svnlook uuid Exibe o UUID do repositrio.
Sinopse
svnlook uuid REPOS_PATH
Descrio
Exibe o UUID do repositrio. O UUID o identificador universal e nico do repositrio (universal unique
identifier). O cliente do Subversion usa este identificador para diferenciar um repositrio de outro.
Exemplos
290
Referncia Completa
do Subversion
Nome
svnlook youngest Exibe o nmero da reviso mais jovem.
Sinopse
svnlook youngest REPOS_PATH
Descrio
Exibe o nmero da reviso mais jovem de um repositrio.
Exemplos
Isto mostra a reviso mais jovem de nosso repositrio de exemplo:
svnsync
O svnsync uma ferramenta remota para espelhamento de repositrios do Subversion. Colocando de
uma forma simples, ela permite que voc repita as revises de um repositrio em outro.
O processo do svnsync precisa apenas de acesso de leitura ao repositrio de origem; ele nunca
tenta modific-lo. Mas, obviamente, o svnsync precisa de acesso tanto de leitura quanto de escrita
no repositrio espelho.
Opes do svnsync
--config-dir DIR
Instrui o Subversion a ler informaes de configurao de um diretrio especfico ao invs do local
padro (.subversion no diretrio home do usurio).
--no-auth-cache
Evita que o cache de informaes de autenticao (p.ex., nome de usurio e senha) seja feito em
diretrios administrativos do Subversion.
--non-interactive
No caso de uma falha de autenticao, ou de credenciais insuficientes, evita que sejam solicitadas
informaes de credenciais (p.ex., nome de usurio e senha) intereativamente. Isto til se voc
estiver executando o Subversion dentro de um script automatizado e que seja mais adequado fazer
o Subversion falhar do que solicitar por mais informao.
--password PASS
Indica que voc est informando sua senha para autenticao na linha de comandode outra
forma, se necessrio, o Subversion ir solicit-la a voc interativamente.
291
Referncia Completa
do Subversion
--username NAME
Indica que voc est informando o nome de usurio para autenticao na linha de comandode
outra forma, se necessrio, o Subversion ir solicit-lo a voc interativamente.
Subcomandos do svnsync
H vrios subcomandos:
292
Referncia Completa
do Subversion
Nome
svnsync copy-revprops Copia todas as propriedades de reviso para uma dada reviso a partir do
repositrio de origem para o repositrio espelho.
Sinopse
svnsync copy-revprops DEST_URL REV
Descrio
Como as propriedades de reviso do Subversio podem ser modificadas a qualquer momento, possvel
que as propriedades para algumas revises possam ser modificadas depois que a reviso j tenha
sido sincronizada para o outro repositrio. Como o comando svnsync synchronize opera apenas
num conjunto de revises que ainda no tenha sido sincronizado, ele no vai perceber uma mudana
numa propriedade de uma reviso que no esteja no conjunto. Assim, isto pode resultar em diferenas
nos valores de propriedades de reviso entre os repositrios espelho e de origem. O svnsync copy-
revprops a resposta a este problema. Use-o para re-sincronizar as propriedades de reviso para
uma dada reviso.
Nomes Alternativos
Nenhum
Opes
--non-interactive
--no-auth-cache
--username NAME
--password PASS
--config-dir DIR
Exemplos
Re-sincroniza propriedades de reviso para uma nica reviso:
293
Referncia Completa
do Subversion
Nome
svnsync initialize Inicializa um repositrio de destino para sincronizao a partir de outro repositrio.
Sinopse
svnsync initialize DEST_URL SOURCE_URL
Descrio
O svnsync initialize verifica que um repositrio atende aos requisitos de um novo repositrio espelho
ou seja, que no h histrico de verso anterior existente, e que permite mudanas em propriedades de
revisoe registra informao administrativa inicial que associa o repositrio espelho com o repositrio
de origem. Esta a primeira operao do svnsync que voc vai executar naquilo que voc quer tornar
um repositrio espelho.
Nomes Alternativos
init
Opes
--non-interactive
--no-auth-cache
--username NAME
--password PASS
--config-dir DIR
Exemplos
Falha ao inicializar um repositrio espelho devido a impossibilidade de modificar revises de
propriedades:
Inicializa um repositrio como espelho, j tendo criado um script de hook pre-revprop-change que
possibilite todas as mudanas de propriedades:
294
Referncia Completa
do Subversion
Nome
svnsync synchronize Transfere todas as revises pendentes do repositrio de origem para o
repositrio espelho.
Sinopse
svnsync synchronize DEST_URL
Descrio
O comando svnsync synchronize faz todo o trabalho pesado da operao de espelhamento de
repositrio. Depois de verificar o repositrio espelho para ver quais revises j foram copiadas para
ele, e ento comea a copiar quaisquer revises que ainda no tenham sido espelhadas a partir do
repositrio origem.
Nomes Alternativos
sync
Opes
--non-interactive
--no-auth-cache
--username NAME
--password PASS
--config-dir DIR
Exemplos
Copia revises ainda no sincronizadas do repositrio de origem para o repositrio espelho:
svnserve
O svnserve possibilita o acesso a repositrios do Subversion usando o protocolo de rede especfico
do Subversion.
Voc pode executar o svnserve como um processo servidor independente (para clientes que estejam
usando o mtodo de acesso svn://); voc pode deixar com que um daemon tal como o inetd ou
295
Referncia Completa
do Subversion
xinetd execute-o para voc sob demanda (tambm para acesso via svn://), ou voc pode fazer com
que o sshd execute-o sob demanda para o mtodo de acesso svn+ssh://.
Independentemente do mtodo de acesso, uma vez que o cliente tenha selecionado um repositrio
enviando sua URL, o svnserve l um arquivo chamado conf/svnserve.conf no diretrio do
repositrio para determinar configuraes especficas tais como qual base de dados de autenticao
usar e que polticas de autorizao aplicar. Veja svnserve, um servidor especializado para mais
detalhes sobre o arquivo svnserve.conf.
Opes do svnserve
Diferente dos comandos anteriores que descrevemos, o svnserve no possui subcomandoso
svnserve controlado exclusivamente por opes.
--daemon (-d)
Faz com que o svnserve execute em modo daemon. O prprio svnserve se pe em segundo
plano, aceitando e servindo conexes TCP/IP na porta do svn (3690, por padro).
--listen-port=PORT
Faz com que o svnserve escute na porta PORT quando executado em modo daemon. (Por padro,
daemons FreeBSD s escutam em tcp6esta opo tambm faz com que escutem em tcp4.)
--listen-host=HOST
Faz com que o svnserve escute na interface especificada por HOST, que pode ser tanto um nome
de host ou um endereo de IP.
--foreground
Quando usado junto com -d, esta opo faz com que o svnserve permanea em primeiro plano.
Esta opo especialmente til para depurao.
--inetd (-i)
Faz com que o svnserve use os descritores de arquivo stdin/stdout, como apropriado para um
daemon que esteja executando via inetd.
--help (-h)
Exibe um resumo de utilizao do comando e encerra.
--version
Exibe informao de verso, uma lista de mdulos disponveis para repositrio e encerra.
--root=ROOT (-r=ROOT)
Define a raiz virtual para os repositrio servidos pelo svnserve. O caminho nas URLs provido pelo
cliente ser interpretado como relativo a este diretrio raiz, e no ser permitido de l escapar.
--tunnel (-t)
Faz com que o svnserve execute em modo tnel, o que bem parecido com o modo de operao
inetd (ambos os modos disponibilizam uma conexo atravs de stdin/stdout, e ento encerram),
exceto que a conexo considerada como j estando pr-autenticada com o nome do usurio do
uid atual. Esta informao passada automaticamente para voc pelo cliente quando se estiver
executando sobre um agente tnel como o ssh. Isso quer dizer que raramente voc precisar
passar esta opo para o svnserve. Ento se voc se digitar svnserve --tunnel na linha de
comando, e ficar se perguntando o que acontece a seguir, veja Tunelamento sobre SSH.
--tunnel-user NAME
Usado juntamente com a opo --tunnel; instrui para que o svnserve considere que NAME
o usurio autenticado, ao invs daquele do UID do processo svnserve. til para usurios que
querem compartilhar uma nica conta do sistema atravs de SSH mas ainda manter identidades
distintas nos registros de submisso no repositrio.
296
Referncia Completa
do Subversion
--threads (-T)
Quando executado em modo daemon, faz com que o svnserve dispare uma thread ao invs de um
processo para cada conexo (p.ex., para quando estiver executando em um sistema Windows). O
processo svnserve em si ainda permanece em segundo quando iniciado.
--listen-once (-X)
Faz com que o svnserve aceite uma conexo na porta do svn, atenda a requisio, e encerre.
Esta opo til principalmente para depurao.
svnversion
297
Referncia Completa
do Subversion
Nome
svnversion Sumariza reviso(es) locais de uma cpia de trabalho.
Sinopse
svnversion [OPTIONS] [WC_PATH [TRAIL_URL]]
Descrio
O svnversion um programa para sumarizao do conjunto de revises de uma cpia de trabalho. O
nmero de reviso resultante, ou intervalo de revises, escrito na sada padro.
comum usar essa sada em seu processo de compilao e distribuio para definir o nmero de
verso de seu programa.
TRAIL_URL, se estiver presente, a poro final da URL usada para determinar se o WC_PATH em si
foi trocado (deteco de chaves dentro de WC_PATH no depende de TRAIL_URL).
Quando WC_PATH no est definido, o diretrio atual ser usado como caminho da cpia de trabalho
TRAIL_URL no pode ser definido se WC_PATH no for informado explicitamente.
Opes
Como o svnserve, o svnversion no tem subcomandos, mas apenas opes.
--no-newline (-n)
Omite a quebra de linha usual da sada.
--committed (-c)
Usa as revises das ltimas modificaes ao invs da reviso atual (i.e., a mais alta reviso
disponvel localmente).
--help (-h)
Exibe um resumo da ajuda.
--version
Exibe a verso do svnversion e encerra sem nenhum erro.
Exemplos
Se a cpia de trabalho estiver toda na mesma reviso (por exemplo, imediatamente depois de uma
atualizao), ento essa reviso exibida:
$ svnversion
4168
Voc pode adicionar TRAIL_URL para se assegurar que a cpia de trabalho no seja diferente daquela
que voc espera. Note que o WC_PATH requerido neste comando:
$ svnversion . /repos/svn/trunk
4168
Para uma cpia de trabalho que esteja em diversas revises distintas, o intervalo das revises
presentes exibido:
298
Referncia Completa
do Subversion
$ svnversion
4123:4168
$ svnversion
4168M
$ svnversion
4168S
E ainda, aqui est uma cpia de trabalho que foi trocada e que continha algumas modificaes locais:
$ svnversion
4212:4168MS
Se executado em um diretrio que no seja uma cpia de trabalho, o svnversion considera que est
em uma cpia de trabalho exportada e exibe "exported":
$ svnversion
exported
mod_dav_svn
299
Referncia Completa
do Subversion
Nome
Diretivas de Configurao do mod_dav_svn As diretivas de configurao do Apache para servir
repositrios do Subversion atravs de um Servidor HTTP Apache.
Descrio
Esta seo descreve brevemente cada um das diretivas de configurao do Subversion no Apache.
Para uma descrio mais detalhada da configurao do Apache com Subversion, veja httpd, o servidor
HTTP Apache.)
Diretivas
DAV svn
Esta diretiva deve ser includa em qualquer bloco Directory ou Location para um repositrio
do Subversion. Ela diz ao httpd usar o mdulo base do Subversion para que o mod_dav manipule
todas as requisies.
SVNAutoversioning On
Esta diretiva permite que requisies de clientes WebDAV resultem em submisses automticas.
Uma mensagem de log genrica gerada automaticamente e anexada a cada reviso. Se voc
habilitar o Auto-versionamento, provvel que voc queira definir ModMimeUsePathInfo On
de forma que mod_mime pode definir a propriedade svn:mime-type para o mime-type correto
automaticamente (e mod_mime capaz de fazer isto muito bem, naturalmente). Para mais
informaes, veja Apndice C, WebDAV e Autoversionamento
SVNPath
Esta diretiva especifica o local no sistema de arquivo para os arquivos do repositrio do Subversion.
Em um bloco de configurao para um repositrio Subversion, ou esta diretiva ou SVNParentPath
deve estar presente, mas no ambas.
SVNSpecialURI
Especifica o componente URI (espao de nome) para recursos especiais do Subversion. O padro
!svn, e a maioria dos administradores nunca usaro esta diretiva. Somente defina ela se houver
uma necessidade premente de ter um arquivo chamado !svn em seu repositrio. Se voc mudar
ela em um servidor j em uso, ele quebrar todas as cpias de trabalho existentes e seus usurios
caaro voc com garfes e tochas de fogo.
SVNReposName
Especifica o nome de um repositrio Subversion a ser usado nas respostas HTTP GET. Este valor
ser colocado no incio do ttulo de todas as listagens de diretrio (as quais so servidas quando
voc navega em um repositrio Subversion com um navegador web). Esta diretiva opcional.
SVNIndexXSLT
Especifica a URI de uma transformao XSL para os ndices de diretrio. Esta diretiva opcional.
SVNParentPath
Especifica o local no sistema de arquivo de um diretrio pai, cujos diretrios filhos so repositrios
do Subversion. Em um bloco de configurao para um repositrio Subversion, ou esta diretiva ou
SVNPath deve estar presente, mas no ambas.
SVNPathAuthz
Controla a autorizao baseada em caminho ao habilitar ou desabilitar sub-requisies. Veja
Desabilitando Verificao baseada em Caminhos para detalhes.
Propriedades do Subversion
O Subversion permite que os usurios inventem propriedades versionadas com nomes arbitrrios em
arquivos e diretrios, bem como propriedades no-versionadas em revises. A nica restrio est nas
300
Referncia Completa
do Subversion
propriedades cujos nomes iniciam com svn: (esses so reservados para uso do prprio Subversion).
Enquanto estas propriedades podem ser definidas pelos usurios para controlar o comportamento do
Subversion, os usurios no podem inventar novas propriedades svn:.
Propriedades Versionadas
svn:executable
Se presente em um arquivo, o cliente tornar o arquivo executvel em cpias de trabalho
hospedadas em Unix. Veja Executabilidade de Arquivo.
svn:mime-type
Se presente em um arquivo, o valor indica o mime-type do arquivo. Esta propriedade permite ao
cliente decidir se a mesclagem contextual baseada em linhas segura para ser realizada durante
as atualizaes, e tambm pode afetar como o arquivo comporta-se quando renderizado por um
navegador web. Veja Tipo de Contedo do Arquivo.
svn:ignore
Se presente em um diretrio, o valor uma lista de filtros de arquivos no-versionados a serem
ignorados por svn status e outros subcomandos. veja Ignorando Itens No-Versionados
svn:keywords
Se presente em um arquivo, o valor diz ao cliente como expandir determinadas palavras-chave
dentro do arquivo. Veja Substituio de Palavra-Chave.
svn:eol-style
Se presente em um arquivo, o valor diz ao cliente como manipular as quebras de linha do arquivo
na cpia de trabalho e em rvores exportadas. Veja Seqncia de Caracteres de Fim-de-Linha
e svn export.
svn:externals
Se presente em um diretrio, o valor uma lista de vrias linhas com outros caminhos e URLs que
o cliente deve verificar. Veja Definies Externas.
svn:special
Se presente em um arquivo, indica que o arquivo no um arquivo normal, mas uma ligao
1
simblica ou outro objeto especial .
svn:needs-lock
Se presente em um arquivo, diz ao cliente para tornar o arquivo somente de leitura na cpia de
trabalho, como um lembrete de que o arquivo deve ser travado antes de iniciar sua edio. Veja
Comunicao de Travas.
Propriedades No-Versionadas
svn:author
Se presente, contm o nome de usurio autenticado da pessoa que criou a reviso. (Se no
presente, ento a reviso foi submitida anonimamente.)
svn:date
Contm a data e hora em UTC em que a reviso foi criada, no formato ISO 8601. O valor vem do
relgio do computador servidor, no do cliente.
svn:log
Contm a mensagem de log descrevendo a reviso.
svn:autoversioned
Se presente, a reviso foi criada por meio do recurso de autoversionamento. Veja
Autoversionamento.
1
At o momento, ligaes simblicas so, na verdade, apenas objetos especiais. Mas podero existir mais outros em verses
futuras do Subversion.
301
Referncia Completa
do Subversion
Ganchos do Repositrio
302
Referncia Completa
do Subversion
Nome
start-commit Notificao do incio de uma submisso.
Descrio
O gancho start-commit executado antes da transao de submisso ser criada. Isto normalmente
usado para decidir se o usurio possui privilgios de submisso.
Parmetros de Entrada
Os argumentos de linha de comando passados ao programa de gancho, em ordem, so:
1. caminho do repositrio
Usos Comuns
controle de acesso
303
Referncia Completa
do Subversion
Nome
pre-commit Notificao pouco antes da concluso da submisso.
Descrio
O gancho pre-commit executado pouco antes de uma transao de submisso ser promovida
para uma nova reviso. Geralmente, este gancho usado para proteger contra submisses que so
recusadas devido ao contedo ou local (por exemplo, seu site pode requerer que todas submisses
para um certo ramo inclua um nmero de entrada no issue tracker, ou que a mensagem de log recebida
no seja vazia).
Parmetros de Entrada
Os argumentos de linha de comando passados ao programa de gancho, em ordem, so:
1. caminho do repositrio
Usos Comuns
validao e controle de mudanas
304
Referncia Completa
do Subversion
Nome
post-commit Notificao de uma submisso com sucesso.
Descrio
O gancho post-commit executado depois que a transao submetida, e uma nova reviso criada.
Maior parte das pessoas usa este gancho para enviar mensagens eletrnicas com detalhes sobre a
submisso ou para notificar alguma outra ferramenta (tal como um issue tracker) que uma submisso
aconteceu. Algumas configuraes tambm usam este gancho para disparar processos de cpia de
segurana.
A sua sada e o cdigo de sada retornados pelo programa de gancho post-commit so ignorados.
Parmetros de Entrada
Os argumentos de linha de comando passados ao programa de gancho, em ordem, so:
1. caminho do repositrio
Usos Comuns
notificao de submisso, integrao com ferramentas
305
Referncia Completa
do Subversion
Nome
pre-revprop-change Notificao de uma tentativa de mudana de propriedade de uma reviso.
Descrio
O gancho pre-revprop-change executado imediatamente antes da modificao de uma propriedade
de reviso quando realizada fora do escopo de uma submisso normal. Ao contrrio dos outros
ganchos, o estado padro deste gancho negar a ao proposta. O gancho deve existir efetivamente e
retornar um cdigo de sada zero antes de uma modificao de propriedade de reviso possa acontecer.
Parmetros de Entrada
Os argumentos de linha de comando passados ao programa de gancho, em ordem, so:
1. caminho do repositrio
Adicionalmente, o Subversion passa para o programa de gancho por meio da entrada padro o valor
proposto para a propriedade.
Usos Comuns
controle de acesso, validao e controle de mudanas
306
Referncia Completa
do Subversion
Nome
post-revprop-change Notificao de uma mudana de propriedade de uma reviso com sucesso.
Descrio
O gancho post-revprop-change executado imediatamente depois que a modificao de uma
propriedade de reviso quando realizada fora do escopo de uma submisso normal. Como pode ser
derivado da descrio de sua contrapartida, o gancho pre-revprop-change, este gancho no executar
toda vez, a menos que o gancho pre-revprop-change esteja implementado. Ele geralmente usado
para enviar mensagem de notificao da mudana da propriedade.
Parmetros de Entrada
Os argumentos de linha de comando passados ao programa de gancho, em ordem, so:
1. caminho do repositrio
Adicionalmente, o Subversion passa para o programa de gancho, por meio da entrada padro, o valor
anterior da propriedade.
Usos Comuns
notificao de mudana de propriedade de reviso
307
Referncia Completa
do Subversion
Nome
pre-lock Notificao de uma tentativa de travamento de um caminho.
Descrio
O gancho pre-lock hook executado quando algum tenta travar um caminho. Ele pode ser usado para
prevenir travas em conjunto, ou para criar uma poltica mais complexa especificando exatamente quais
usurios so permitidos a travar caminhos determinados. Se o gancho relatar uma trava j existente,
ento ele pode tambm decidir quando um usurio permitido a roubar a trava existente.
Parmetros de Entrada
Os argumentos de linha de comando passados ao programa de gancho, em ordem, so:
1. caminho do repositrio
Usos Comuns
controle de acesso
308
Referncia Completa
do Subversion
Nome
post-lock Notificao de um travamento de caminho com sucesso.
Descrio
O gancho post-lock executado depois que um ou mais caminhos tenham sido travados. Ele
geralmente usado para enviar mensagem de notificao do evento de trava.
A sua sada e o cdigo de sada retornados pelo programa de gancho post-lock so ignorados.
Parmetros de Entrada
Os argumentos de linha de comando passados ao programa de gancho, em ordem, so:
1. caminhos do repositrio
Adicionalmente, a lista de caminhos travados passada para o programa de gancho por meio da
entrada padro, um caminhos por linha.
Usos Comuns
notificao de trava
309
Referncia Completa
do Subversion
Nome
pre-unlock Notificao de uma tentativa de destravamento de caminho.
Descrio
O gancho pre-unlock executado quando algum tenta remover uma trava em um arquivo. Ele pode
ser usado para criar polticas que especifique quais usurios so permitidos para destravar caminhos
determinados. Isto particularmente importante para determinar polticas sobre quebra de travas. Se
o usurio A trava um arquivo, o usurio B permitido a quebrar a trava? E se a trava existe a mais de
uma semana? Estes tipos de coisas podem ser decididas e executadas pelo gancho.
Parmetros de Entrada
Os argumentos de linha de comando passados ao programa de gancho, em ordem, so:
1. caminho do repositrio
Usos Comuns
controle de acesso
310
Referncia Completa
do Subversion
Nome
post-unlock Notificao de um destravamento de caminho com sucesso.
Descrio
O gancho post-unlock executa depois que um ou mais caminhos tenham sido destravados. Isto
geralmente usado para enviar mensagem de notificao do evento de destrava.
A sua sada e o cdigo de sada retornados pelo programa de gancho post-unlock so ignorados.
Parmetros de Entrada
Os argumentos de linha de comando passados ao programa de gancho, em ordem, so:
1. caminho do repositrio
Usos Comuns
notificao de destravamento
311
Apndice A. Guia Rpido de
Introduo ao Subversion
Se voc est ansioso para ter o Subversion configurado e funcionando (e se voc daqueles que
gostam de aprender fazendo), este captulo vai lhe mostrar como criar um repositrio, importar cdigo,
e ento obt-lo de volta como uma cpia de trabalho. Ao longo do caminho, damos referncias aos
captulos relevantes deste livro.
Instalando o Subversion
O Subversion construdo sobre uma camada de portabilidade chamada APRa biblioteca Apache
Portable Runtime. A biblioteca APR prov todas as interfaces de que o Subversion precisa para
funcionar em diferentes sistemas operacionais: acesso a disco, acesso rede, gerncia de memria, e
por a vai. Ainda que o Subversion seja capaz de usar o Apache como um de seus programas servidores
de rede, sua dependncia da APR no significa que o Apache seja um componente requerido. APR
uma biblioteca independente e que pode ser usada por qualquer aplicao. Isso significa, entretanto,
que como o Apache, os clientes Subversion e servidores executam em quaisquer sistemas operacionais
em que o servidor Apache httpd execute: Windows, Linux, todos os tipos de BSD, Mac OS X, Netware,
e outros.
A maneira mais fcil de obter o Subversion fazendo o download do pacote binrio construdo para
seu sistema operacional. O site do Subversion (http://subversion.tigris.org) quase sempre ter estes
pacotes disponveis para download, submetidos por voluntrios. O site comumente contm pacotes de
instaladores grficos para os usurios de sistemas operacionais Microsoft. Se voc tem um sistema
operacional Unix-like, voc pode usar o sistema de pacotes nativo de sua distribuio (RPMs, DEBs,
a rvore de ports, etc.) para obter o Subversion.
Como alternativa, voc tambm pode compilar o Subversion diretamente a partir do cdigo-fonte, ainda
que esta no seja sempre uma tarefa fcil. (Se voc no tem experincia em compilar pacotes de
software de cdigo aberto, ao invs disso, provavelmente seria melhor que voc fizesse o download
da distribuio binria!) Do site do Subversion, baixe a ltima verso do cdigo-fonte. Depois de
descompact-lo, siga as instrues no arquivo INSTALL para compil-lo. Note que um pacote com os
fontes pode no conter tudo o que voc precisa para compilar um cliente de linha de comando capaz
de se comunicar com um repositrio remoto. Desde o Subversion 1.4 e posteriores, as bibliotecas de
que o Subversion depende (apr, apr-util, e neon) so distribudas em um pacote de fontes em separado
com o sufixo -deps. Estas bibliotecas, no entanto, so bastante comuns hoje em dia e possvel que
j estejam instaladas em seu sistema. Se no, voc precisar descompactar o pacote de dependncias
no mesmo diretrio em que descompactou os fontes principais do Subversion. Alm disso, porm,
possvel que voc queira obter outras dependncias opcionais tais como Berkeley DB e possivelmente
o servidor Apache httpd. Se voc quiser uma compilao completa, certifique-se de ter todos os pacotes
relacionados no arquivo INSTALL.
Se voc uma daquelas pessoas que gosta de usar software ainda em desenvolvimento, voc tambm
pode obter o cdigo-fonte do Subversion a partir do repositrio Subversion onde ele se encontra.
Obviamente, voc precisa j ter um cliente Subversion em mos para fazer isso. Mas uma vez que
voc o faa, voc pode obter uma cpia de trabalho do repositrio dos fontes do Subversion em http://
1
svn.collab.net/repos/svn/trunk/:
1
Perceba que a URL mencionada no exemplo acima no termina com svn, mas com um subdiretrio chamado de trunk. Veja
nossa discusso sobre o modelo de ramificao (branching) e rotulagem (branching) para entender as razes por trs disto.
312
Guia Rpido de
Introduo ao Subversion
O comando acima vai criar uma cpia de trabalho da ltima verso (ainda no distribuda) do cdigo-
fonte do Subversion em um diretrio chamado subversion no diretrio de trabalho atual. Voc pode
ajustar o ltimo argumento como quiser. Independentemente de que nome voc d ao diretrio de
sua nova cpia de trabalho, porm, quando esta operao concluir, voc agora ter o cdigo-fonte do
Subversion. claro que voc ainda vai precisar obter algumas poucas bibliotecas auxiliares (apr, apr-
util, etc.)consulte o arquivo INSTALL na raiz de sua cpia de trabalho para mais detalhes.
A seguir, voc confere um breve tutorial que vai lhe conduzir pela configurao e utilizao bsica do
Subversion. Ao final, voc deve ter uma compreenso bsica do uso tpico do Subversion.
Os exemplos usados neste apndice assumem que voc tem o svn, o cliente de linha de
comando do Subversion, e o svnadmin, a ferramenta administrativa, prontas para usar
em um sistema operacional Unix-like. (Este tutorial tambm funciona para o prompt de
comando do Windows, assumindo que voc faa algumas devidas adaptaes.) Tambm
assumimos que voc est usando o Subversion 1.2 ou posterior (execute svn --version
para conferir.)
O Subversion armazena todos os dados versionados em um repositrio central. Para comear, crie
um novo repositrio:
Neste exemplo, assumimos que que voc j tem algum tipo de projeto (um conjunto de arquivos de
diretrios) que voc quer importar para dentro de seu repositrio Subversion recm-criado. Comece
organizando seus dados dentro de um nico diretrio chamado meuprojeto (ou qualquer outro nome
de sua preferncia). Por motivos que ficaro mais claros posteriormente (veja Captulo 4, Fundir e
Ramificar), a estrutura da rvore de seu projeto deve conter trs diretrios internos chamados de
branches, tags, e trunk. O diretrio trunk deve conter todos os seus dados, enquanto que os
diretrios branches e tags so vazios:
313
Guia Rpido de
Introduo ao Subversion
/tmp/meuprojeto/branches/
/tmp/meuprojeto/tags/
/tmp/meuprojeto/trunk/
foo.c
bar.c
Makefile
Uma vez voc sua rvore de dados esteja pronta, importe os dados para dentro do repositrio com o
comando svn import (veja Colocando dados em seu Repositrio):
Committed revision 1.
$
Agora o repositrio contm esta rvore de dados. Como mencionado anteriormente, voc no ver
seus dados ao listar diretamente o contedo do repositrio; os dados esto todos armazenados dentro
de uma base de dados. Mas o sistema de arquivos imaginrio do repositrio agora contm um diretrio
de alto nvel chamado meuprojeto, que por sua vez contm seus dados.
Veja que o diretrio /tmp/meuprojeto original no alterado; o Subversion sequer tem conhecimento
dele. (De fato, voc pode at excluir esse diretrio se quiser.) Para comear a manipular os dados do
repositrio, voc precisa criar uma nova cpia de trabalho dos dados, que so uma espcie de espao
de trabalho particular. Solicite que o Subversion lhe entregue (check out) uma cpia de trabalho do
diretrio meuprojeto/trunk no repositrio:
Agora voc tem uma cpia pessoal de uma parte do repositrio em um novo diretrio chamado
meuprojeto. Voc pode alterar os arquivos em sua cpia de trabalho e ento submeter essas
alteraes de volta para o repositrio.
Execute svn diff para ver uma sada unificada de suas alteraes.
Execute svn commit para submeter a nova verso de seu arquivo ao repositrio.
Execute svn update para deixar sua cpia de trabalho atualizada com o repositrio.
Para conhecer todas as coisas que voc pode fazer com sua cpia de trabalho, leia Captulo 2, Uso
Bsico.
314
Guia Rpido de
Introduo ao Subversion
Neste ponto, voc tem a opo de tornar seu repositrio disponvel a outras pessoas atravs de
uma rede. Consulte Captulo 6, Configurao do Servidor para aprender sobre os diferentes tipos de
processos servidores e sobre como configur-los.
315
Apndice B. Subversion para
Usurios de CVS
Este apndice um guia para usurios de CVS novos no Subversion. essencialmente uma lista
das diferenas entre os dois sistemas como so vistos a 10.000 ps de altura. Em cada seo, ns
fornecemos referncias a captulos relevantes, quando possvel.
Embora o objetivo do Subversion seja assumir a atual e futura base de usurios do CVS, algumas
novas caractersticas e mudanas de projeto foram necessrias para corrigir certos comportamentos
quebrados que o CVS apresentava. Isto significa que, como um usurio de CVS, voc pode precisar
mudar hbitosa comear pelos que voc esqueceu que eram estranhos.
No Subversion, o repositrio parece um sistema de arquivos nico. Cada submisso resulta em uma
rvore de sistema de arquivos inteiramente nova; em essncia, o repositrio um conjunto ordenado
de rvores. Cada uma dessas rvores rotulada com um nmero de reviso nico. Quando algum
fala sobre a reviso 54, est falando sobre uma rvore em particular (e, indiretamente, sobre a forma
que o sistema de arquivos apresentava aps a 54 submisso).
Tecnicamente, no vlido falar sobre a reviso 5 de foo.c. Em vez disso, diria-se foo.c como
aparece na reviso 5. Tambm seja cuidadoso ao fazer suposies sobre a evoluo de um arquivo.
No CVS, as revises 5 e 6 de foo.c so sempre diferentes. No Subversion, mais provvel que foo.c
no tenha mudado entre as revises 5 e 6.
Similarmente, no CVS um rtulo ou ramo uma anotao no arquivo, ou na informao de verso para
aquele arquivo individual, enquanto no Subversion um rtulo ou ramo uma cpia de uma rvore inteira
(por conveno, nos diretrios /branches ou /tags que aparecem no nvel superior do repositrio, ao
lado de /trunk). No repositrio como um todo, muitas verses de cada arquivo podem estar visveis:
a ltima verso em cada ramo, cada verso rotulada, e, claro, a ltima verso no prprio tronco.
Assim, para refinar ainda mais os termos, poderia-se freqentemente dizer foo.c como aparece em
/branches/REL1 na reviso 5.
Verses de Diretrio
O Subversion rastreia estruturas de rvores, e no apenas o contedo dos arquivos. Esta uma das
maiores razes pelas quais o Subversion foi escrito para substituir o CVS.
Aqui est o que isto significa para voc, como antigo usurio de CVS:
Os comandos svn add e svn delete agora funcionam em diretrios, da mesma forma como
funcionam em arquivos. O mesmo vale para svn copy e svn move. Entretanto, estes comandos
no causam nenhum tipo de mudana imediata no repositrio. Em vez disso, os itens de trabalho
so simplesmente marcados para adio ou excluso. Nenhuma mudana no repositrio acontece
at que voc execute svn commit.
Os diretrios no so mais simples contineres; eles tm nmeros de reviso como os arquivos. (Ou,
mais propriamente, correto dizer diretrio foo/ na reviso 5.)
316
Subversion para
Usurios de CVS
Vamos falar mais sobre esse ltimo ponto. O versionamento de diretrios um problema difcil;
como ns queremos permitir cpias de trabalho de revises mistas, h algumas limitaes no quanto
podemos abusar deste modelo.
De um ponto de vista terico, ns definimos que a reviso 5 do diretrio foo significa uma coleo
especfica de entradas de diretrio e propriedades. Agora suponha que comeamos a adicionar e
remover arquivos de foo, e ento submetemos. Seria mentira dizer que ns ainda temos a reviso
5 de foo. Entretanto, se ns mudssemos o nmero de reviso de foo depois da submisso, isso
tambm seria falso; pode haver outras mudanas em foo que ns ainda no recebemos, porque ainda
no atualizamos.
O Subversion lida com este problema rastreando secretamente na rea .svn as adies e excluses
submetidas. Quando voc eventualmente executa svn update, todas as contas so acertadas com
o repositrio, e o novo nmero de reviso do diretrio determinado corretamente. Portanto, apenas
depois de uma atualizao realmente seguro dizer que voc tem uma perfeita reviso de um
diretrio. Na maior parte do tempo, sua cpia de trabalho conter revises de diretrio imperfeitas.
Para mais discusso sobre as limitaes do versionamento de diretrios, veja Revises Locais Mistas.
O diretrio administrativo .svn serve ao mesmo propsito que o diretrio CVS, exceto porque tambm
armazena cpias somente-leitura e intocadas dos seus arquivos. Isto permite que voc faa muitas
coisas desconectado:
svn status
Mostra quaisquer mudanas locais que voc fez (veja Obtendo uma viso geral de suas
alteraes)
svn diff
Mostra os detalhes das suas mudanas (veja Examinando os detalhes de suas alteraes locais)
svn revert
Remove suas mudanas locais (veja Desfazendo Modificaes de Trabalho)
Os arquivos originais guardados tambm permitem que o cliente Subversion envie diferenas ao
submeter, o que o CVS no capaz de fazer.
O ltimo subcomando da lista novo; ele no apenas remover mudanas locais, mas ir desmarcar
operaes agendadas, como adies e excluses. a maneira preferida de reverter um arquivo;
executar rm file; svn update tambm ir funcionar, mas isso mancha o propsito da atualizao. E,
por falar nisso
O comando cvs status tem dois propsitos: primeiro, mostrar ao usurio qualquer modificao local na
cpia de trabalho, e, segundo, mostrar ao usurio quais arquivos esto desatualizados. Infelizmente,
317
Subversion para
Usurios de CVS
devido dificuldade para ler a sada produzida pelo status no CVS, muitos usurios de CVS no tiram
nenhuma vantagem deste comando. Em vez disso, eles desenvolveram um hbito de executar cvs
update ou cvs -n update para ver rapidamente suas mudanas. Se os usurios se esquecem de usar
a opo -n, isto tem o efeito colateral de fundir alteraes no repositrio com as quais eles podem no
estar preparados para lidar.
Com o Subversion, ns tentamos eliminar esta confuso tornando a sada do svn status fcil de
ler tanto para humanos quanto para programas analisadores. Alm disso, svn update s imprime
informao sobre arquivos que esto atualizados, e no modificaes locais.
Status
svn status imprime todos os arquivos que tm modificaes locais. Por padro, o repositrio no
contatado. Embora este subcomando aceite um bom nmero de opes, as seguintes so as mais
comumente usadas:
-u
Contatar o repositrio para determinar, e ento mostrar, informaes sobre desatualizao.
-v
Mostrar todas as entradas sob controle de verso.
-N
Executar no-recursivamente (no descer para os subdiretrios).
O comando status tem dois formatos de sada. No formato curto padro, modificaes locais parecem
com isto:
$ svn status
M foo.c
M bar/baz.c
Se voc especificar a opo --show-updates (-u), um formato mais longo de sada usado:
$ svn status -u
M 1047 foo.c
* 1045 faces.html
* bloo.png
M 1050 bar/baz.c
Status against revision: 1066
Neste caso, duas novas colunas aparecem. A segunda coluna contm um asterisco se o arquivo ou
diretrio est desatualizado. A terceira coluna mostra o nmero de reviso da cpia de trabalho do
item. No exemplo acima, o asterisco indica que faces.html seria alterado se ns atualizssemos, e
que bloo.png um arquivo recm-adicionado ao repositrio. (A falta de qualquer nmero de reviso
prximo a bloo.png significa que ele ainda no existe na cpia de trabalho.)
A esta altura, voc deve dar uma rpida olhada na lista de todos os cdigos de status possveis em
svn status. Aqui esto alguns dos cdigos de status mais comuns que voc ver:
318
Subversion para
Usurios de CVS
Para uma discusso mais detalhada de svn status, veja Obtendo uma viso geral de suas alteraes.
Update
svn update atualiza sua cpia de trabalho, e s imprime informao sobre arquivos que ele atualiza.
O Subversion combinou os cdigos P e U do CVS em apenas U. Quando ocorre uma fuso ou conflito,
o Subversion simplesmente imprime G ou C, em vez de uma sentena inteira.
Para uma discusso mais detalhada de svn update, veja Atualizando Sua Cpia de Trabalho.
Ramos e Rtulos
O Subversion no distingue entre espao do sistema de arquivos e espao do ramo; ramos e rtulos
so diretrios normais dentro do sistema de arquivos. Esta provavelmente o nico maior obstculo
mental que um usurio de CVS precisar escalar. Leia tudo sobre isso em Captulo 4, Fundir e
Ramificar.
Visto que o Subversion trata ramos e rtulos como diretrios normais, sempre se lembre
de efetuar checkout do tronco (http://svn.example.com/repos/calc/trunk/)
do seu projeto, e no do projeto em si (http://svn.example.com/repos/calc/). Se
voc cometer o erro de efetuar checkout do projeto em si, vai terminar com uma cpia de
1
trabalho que contm uma cpia do seu projeto para cada ramo e rtulo que voc tem.
Propriedades de Metadados
Uma nova caracterstica do Subversion que voc pode atribuir um metadado arbitrrio (ou
propriedades) as arquivos e diretrios. Propriedades so pares nome/valor arbitrrios associados com
arquivos e diretrios na sua cpia de trabalho.
Para atribuir ou obter o nome de uma propriedade, use os subcomandos svn propset e svn propget
. Para listar todas as propriedades de um objeto, use svn proplist.
Resoluo de Conflitos
O CVS marca conflitos com marcadores de conflito em linha, e imprime um C durante uma
atualizao. Historicamente, isso tem causado problemas, porque o CVS no est fazendo o suficiente.
Muitos usurios esquecem (ou no vem) o C depois que ele passa correndo pelo terminal. Eles
freqentemente esquecem at mesmo que os marcadores de conflitos esto presentes, e ento
acidentalmente submetem arquivos contendo marcadores de conflitos.
O Subversion resolve este problema tornando os conflitos mais tangveis. Ele se lembra de que um
arquivo encontra-se em um estado de conflito, e no permitir que voc submeta suas mudanas at
que execute svn resolved. Veja Resolvendo Conflitos (Combinando Alteraes de Outros) para mais
detalhes.
319
Subversion para
Usurios de CVS
Os usurios de CVS tm que marcar arquivos binrios com flags -kb, para prevenir que os dados sejam
corrompidos (devido a expanso de palavras-chave e traduo de quebras de linha). Eles algumas
vezes se esquecem de fazer isso.
O Subversion segue a rota mais paranicaprimeiro, nunca realiza nenhum tipo de traduo de
palavra-chave ou de quebra de linha, a menos que voc explicitamente o instrua a faz-lo (veja
Substituio de Palavra-Chave e Seqncia de Caracteres de Fim-de-Linha para mais detalhes).
Por padro, o Subversion trata todos os dados do arquivo como cadeias de bytes literais, e os arquivos
sempre so armazenados no repositrio em estado no-traduzido.
Segundo, o Subversion mantm uma noo interna de se um arquivo contm dados de texto ou
binrios, mas esta noo existe apenas na cpia de trabalho. Durante um svn update, o Subversion
realizar fuses contextuais em arquivos de texto modificados localmente, mas no tentar fazer o
mesmo com arquivos binrios.
Para determinar se uma fuso contextual possvel, o Subversion examina a propriedade svn:mime-
type. Se o arquivo no tem a propriedade svn:mime-type, ou tem um mime-type que textual (por
exemplo, text/*), o Subversion supe que ele texto. Caso contrrio, o Subversion supe que o
arquivo binrio. O Subversion tambm ajuda os usurios executando um algoritmo para detectar
arquivos binrios nos comandos svn import e svn add. Estes comandos faro uma boa suposio e
ento (possivelmente) colocaro uma propriedade svn:mime-type binria no arquivo que est sendo
adicionado. (Se o Subversion fizer uma suposio errada, o usurio sempre pode remover ou editar
manualmente a propriedade.)
O Subversion define mdulos como uma lista de diretrios dentro de uma propriedade de diretrio:
veja Definies Externas.
Autenticao
Com o pserver do CVS, exige-se que voc inicie sesso no servidor antes de qualquer operao de
leitura ou escritas vezes voc tem de iniciar uma sesso at para operaes annimas. Com um
repositrio Subversion usando Apache httpd ou svnserve como servidor, voc no fornece quaisquer
credenciais de autenticao a princpio se uma operao que voc realiza requer autenticao, o
servidor ir pedir suas credenciais (sejam essas credenciais nome de usurio e senha, um certificado
de cliente, ou mesmo ambos). Assim, se o seu repositrio pode ser lido por todo o mundo, no ser
exigido que voc se autentique para operaes de leitura.
Assim como o CVS, o Subversion ainda guarda suas credenciais em disco (em seu diretrio
~/.subversion/auth/), a menos que voc o instrua a no faz-lo, usando a opo --no-auth-
cache.
320
Subversion para
Usurios de CVS
321
Apndice C. WebDAV e
Autoversionamento
WebDAV uma extenso do HTTP, e est se tornando cada vez mais popular como um padro para
compartilhamento de arquivos. Hoje em dia, os sistemas operacionais esto se tornado extremamente
relacionados Web, e muitos agora tm suporte para montar compartilhamentos exportados por
servidores WebDAV.
Se voc usa o Apache como seu servidor de rede para o Subversion, ento para algumas extenses
voc tambm deve estar executando um servidor WebDAV. Este apndice oferece algum suporte
sobre a natureza deste protocolo, como o Subversion o utiliza, e o quo boa a interoperabilidade do
Subversion com outros softwares relacionados com o WebDAV.
O que WebDAV?
DAV uma sigla em ingls para Versionamento e Autorao Distribuda. A RFC 2518 define um
conjunto de conceitos e mtodos de extenso relacionados a HTTP 1.1 que transformam a web em
uma mdia mais universal de leitura e escrita. A idia bsica que um servidor web que siga o
padro WebDAV pode agir como um servidor de arquivos genrico; os clientes podem montar pastas
compartilhadas sobre HTTP que se comportem como qualquer outro sistema de arquivos de rede (como
NFS ou SMB.)
O problema, porm, que apesar do acrnimo, a especificao RFC atualmente no descreve qualquer
forma de controle de verso. Clientes bsicos de WebDAV e servidores assumem apenas uma verso
para cada arquivo ou diretrio existente, e podem ser repetidamente sobrescritos.
Devido a RFC 2518 no contemplar conceitos de versionamento, outro comit tomou para si a
responsabilidade de escrever a RFC 3253 alguns anos depois. A nova RFC adiciona conceitos de
versionamento ao WebDAV, fazendo valer o significado do V em DAVda o termo DeltaV.
Clientes e servidores WebDAV/DeltaV quase sempre so apenas chamados de programas DeltaV,
uma vez que DeltaV implica na existncia de WebDAV bsico.
O padro WebDAV original tem sido largamente usado com sucesso. Cada sistema operacional de
computadores modernos tem uma implementao interna de um cliente WebDAV (mais detalhes a
seguir), e diversas aplicaes independentes populares tambm so capazes de se comunicar em
WebDAVcomo o Microsoft Office, Dreamweaver, e Photoshop para relacionar apenas algumas. No
lado do servidor, o servidor web Apache tem capacidade de oferecer servios WebDAV desde 1998 e
considerado o padro open-source de facto. H outros servidores WebDAV disponveis, incluindo
o prprio IIS da Microsoft.
J o DeltaV, infelizmente, no tem sido to bem sucedido. muito difcil de encontrar clientes ou
servidores DeltaV. Os poucos que existem so produtos comerciais relativamente desconhecidos,
e assim muito difcil testar interoperabilidade. No totalmente claro o porqu de que o DeltaV
permanece estagnado. Alguns argumentam apenas que a especificao muito complexa, j outros
dizem que apesar de os recursos do WebDAV terem apelo macio (ao menos para usurios
tcnicos que apreciem compartilhamento de arquivos em rede), recursos de controle de verso no
so interessantes ou mesmo necessrios para a maioria dos usurios. Finalmente, alguns ainda
consideram que o DeltaV permanece impopular porque ainda no h um servidor como produto open-
source que o implemente to bem.
Ainda que o Subversion ainda esteja em fase de desenvolvimento, parece uma grande idia usar
o Apache como servidor de rede. Ele j possui um mdulo para prover servios WebDAV. DeltaV
era uma especificao relativamente nova. A esperana era que o mdulo servidor do Subversion (o
mod_dav_svn) pudesse eventualmente evoluir para uma implementao open-source de referncia
DeltaV. Infelizmente, o DeltaV tem um modelo de versionamento muito especfico que no
exatamente adequado ao modelo do Subversion. Alguns conceitos foram mapeados, mas outros no.
322
WebDAV e Autoversionamento
Primeiro, o cliente Subversion no uma implementao completa de um cliente DeltaV. Ele precisa
de algumas certas coisas do servidor que o DeltaV em si no pode prover, e assim ele altamente
dependente de diversas requisies HTTP REPORT especficas para o Subversion que apenas o
mod_dav_svn pode entender.
Autoversionamento
Ainda que o cliente Subversion no seja um cliente DeltaV completo, e que nem mesmo o servidor
Subversion serja um servidor DeltaV completo, ainda h um lampejo de interoperabilidade com o
WebDAV com o qual se contentar: o chamado autoversionamento.
Pelo fato de que muitos sistemas operacionais j tm clientes WebDAV integrados, o caso de uso
para este recurso pode ser incrivelmente interessante a administradores que estejam trabalhando
com usurios no-tcnicos: imagine um escritrio de usurios comuns executando Microsoft Windows
ou Mac OS. Cada usurio monta o repositrio Subversion, o qual aparece como uma pasta de
rede normal. Eles usam a pasta compartilhada como esto acostumados: abrem arquivos, fazem
modificaes, salvam. Enquanto isso, o servidor est automaticamente versionando tudo. Qualquer
administrador (ou usurio com conhecimento adequado) ainda pode usar um cliente Subversion para
pesquisar num histrico e obter verses mais antigas dos dados.
Este cenrio no fictcio: real e funciona, sendo o Subversion verso 1.2 ou posterior. Para ativar o
autoversionamento no mod_dav_svn, use a diretiva SVNAutoversioning dentro do bloco Location
no httpd.conf, mais ou menos assim:
<Location /repos>
DAV svn
SVNPath /path/to/repository
SVNAutoversioning on
</Location>
Quando o SVNAutoversioning est ativa, requisies de escrita a partir de clientes WebDAV resultam
em submisses automticas. Uma mensagem de log genrica gerada automaticamente e anexada
a cada reviso.
Antes de ativar este recurso, no entanto, entenda no que voc est se metendo. Clientes WebDAV
tendem a fazer muitas requisies de escrita, resultando em um nmero enorme de revises
323
WebDAV e Autoversionamento
submetidas automaticamente. Por exemplo, ao salvar dados, muitos clientes faro um PUT de um
arquivo de zero bytes (como uma forma de reservar um nome) seguida de outro PUT com os dados
do arquivo real. Um nico salvamento de arquivo resulta em duas submisses em separado. Tambm
considere que muitas aplicaes realizam salvamento automtico em intervalos definidos, resultando
em ainda mais submisses de rede.
Se voc tiver um script de hook post-commit que envie um e-mail, voc pode querer desabilitar a
gerao de e-mail como um todo, ou em certas sees do repositrio; depende de como voc acha que
o fluxo de e-mails resultante ainda sejam notificaes importantes ou no. Ainda, um script de hook
post-commit esperto pode diferenciar entre uma transao criada a partir de autoversionamento e uma
criada a partir de um svn commit normal. O truque olhar para uma propriedade da reviso chamada
svn:autoversioned. Se existir, o commit foi feito por um cliente WebDAV genrico.
Outro recurso que pode ser um til complemento para o SVNAutoversioning vem do mdulo
mod_mime do Apache. Se um cliente WebDAV adicionar um novo arquivo ao repositrio, no haver
uma oportunidade para que o usurio defina a propriedade svn:mime-type. Isto pode fazer com
que o arquivo aparea como um cone genrico quando visto em uma pasta WebDAV compartilhada,
no associado a nenhuma aplicao. Uma soluo ter um administrador de sistema (ou outra
pessoa com conhecimento do Subversion) que obtenha uma cpia de trabalho e defina manualmente a
propriedade svn:mime-type nos arquivos necessrios. Mas potencialmente essas tarefas de limpeza
potencialmente no tm fim. Ao invs disso, voc pode usar a diretiva ModMimeUsePathInfo no bloco
<Location> de seu Subversion:
<Location /repos>
DAV svn
SVNPath /path/to/repository
SVNAutoversioning on
ModMimeUsePathInfo on
</Location>
Esta diretiva permite que o mod_mime para tentar deduzir automaticamente o tipo mime em novos
arquivos adicionados ao repositrio pelo autoversionamento. O mdulo verifica a extenso do nome do
arquivo e possivelmente seu contedo tambm; se o arquivo corresponder a alguns padres comuns,
ento a propriedade svn:mime-type ser definida automaticamente.
324
WebDAV e Autoversionamento
325
WebDAV e Autoversionamento
Veja que ainda que muitos desses programas tambm existam para o Mac OS X, eles no parecem
suportar o WebDAV nativamente nessa plataforma. De fato, no Mac OS X, a caixa de dilogo File-
1
O suporte a WebDAV foi removido do Microsoft Access por algum motivo, mas existe nos demais programas da sute de
escritrio.
326
WebDAV e Autoversionamento
>Open no permite de forma alguma que voc digite um caminho ou uma URL. como se os recursos
para WebDAV tivessem sido deliberadamente removidos das verses Macintosh desses programas,
uma vez que o sistema de arquivos do OS X j prov um excelente suporte de baixo nvel para WebDAV.
Usar o cadaver se parece com usar um programa FTP de linha de comando, sendo assim
extremamente til para depurao bsica de WebDAV. O programa pode ser usado para se fazer
upload ou download de arquivos de uma s vez, e tambm examinar propriedades, alm de copiar,
mover, travar ou destravar arquivos:
$ cadaver http://host/repos
dav:/repos/> ls
Listing collection `/repos/': succeeded.
Coll: > foobar 0 May 10 16:19
> playwright.el 2864 May 4 16:18
> proofbypoem.txt 1461 May 5 15:09
> westcoast.jpg 66737 May 5 15:09
DAV Explorer outro cliente WebDAV independente, escrito em Java. distribudo sob uma licena
livre ao estilo da do Apache e est disponvel em http://www.ics.uci.edu/~webdav/. O DAV Explorer faz
tudo o que o cadaver faz, mas tem as vantagens de ser uma aplicao grfica mais portvel e mais
amigvel. Tambm foi um dos primeiros clientes a dar suporte ao novo protocolo de acesso WebDAV
(RFC 3744).
Obviamente, o suporte a ACL do DAV Explorer intil neste caso, j que o mod_dav_svn no d
suporte a ele. O fato de tanto o Cadaver quanto o DAV Explorer suportarem alguns comandos DeltaV,
particularmente, tambm igualmente intil, uma vez que eles no permitem requisies MKACTIVITY.
Mas de qualquer forma isso tambm no relevante; estamos assumindo que todos esses clientes
trabalham normalmente com um repositrio com autoversionamento.
327
WebDAV e Autoversionamento
O cliente Web Folders original era uma extenso para o Explorer, o principal programa grfico
usado para navegar em sistemas de arquivos. Ele funciona suficientemente bem. No Windows 98, o
recurso precisa ser explicitamente instalado se Web Folders j no estiverem visveis dentro do Meu
Computador. No Windows 2000, simplesmente adicione um novo local de rede, informe a URL, e o
compartilhamento surgir para navegao.
Com o lanamento do Windows XP, a Microsoft comeou a distribuir uma nova implementao do Web
Folders, conhecida como WebDAV mini-redirector. A nova implementao um cliente em nvel de
sistema de arquivos, que permite que compartilhamentos WebDAV sejam montados como letras de
drives. Infelizmente, esta implementao incrivelmente problemtica. O cliente frequentemente tenta
converter URLs http (http://host/repos) para a notao UNC de compartilhamentos (\\host
\repos); ele tambm tenta usar a autenticao de domnio do Windows para responder aos desafios
de autenticao basic do HTTP, enviando nomes de usurios como HOST\username. Estes problemas
de interoperabilidade so crticos e esto documentados em diversos locais pela web, para frustrao
de muitos usurios. Mesmo Greg Stein, o autor original do mdulo WebDAV do Apache, desaconselha
o uso do Web Folders do XP para comunicao com um servidor Apache.
V-se, porm, que a implementao original do Web Folders somente para Windows Explorer no
morreu no XP, mas s est enterrada. Ainda possvel encontr-la usando esta tcnica:
1. V em 'Locais de Rede'.
3. Quando solicitado, informe a URL do repositrio, mas inclua um nmero de porta na URL. Por
exemplo, http://host/repos deveria ser informado como http://host:80/repos.
H alguns outros rumores sobre formas de contornar outros problemas, mas nenhum deles parece
funcionar em todas as verses e com os diferentes patches do Windows XP. Em nossos testes, apenas
estes passos anteriores parecem funcionar consistentemente em cada sistema. consenso geral da
comunidade WebDAV que voc deveria evitar essa nova implementao de Web Folders e usar a
antiga no lugar, e que se voc precisar de um cliente em nvel de sistema de arquivos para o Windows
XP, use ento um programa de terceiros como o WebDrive ou o NetDrive.
Uma ltima dica: se voc estiver tentando usar o XP Web Folders, certifique-se de ter realmente
a sua verso mais recente da Microsoft. Por exemplo, a Microsoft disponibilizou uma verso com
bugs corrigidos em janeiro de 2005, que encontra-se disponvel em http://support.microsoft.com/?
kbid=892211. Em particular, esta verso conhecida por corrigir um problema em que ao se navegar
em um compartilhamento DAV resultava em uma inesperada recurso infinita.
Nautilus, Konqueror
O Nautilus o gerenciador de arquivos/navegador oficial do ambiente GNOME (http://www.gnome.org),
j o Konqueror o gerenciador de arquivos/navegador para o ambiente KDE (http://www.kde.org).
Estas duas aplicaes j possuem nativamente o suporte a WebDAV em nvel de sistema de arquivos,
e trabalham muito bem com repositrios com recurso de autoversionamento.
No Nautilus do GNOME, a partir do menu File, escolha Open location e entre com a URL. O repositrio
dever ser ento exibido como um sistema de arquivos como outro qualquer.
No Konqueror do KDE, voc precisa usar o esquema webdav:// ao informar uma URL na barra
de endereos. Se voc informar uma URL http://, o Konqueror vai se comportar como um
328
WebDAV e Autoversionamento
navegador web comum. Voc provavelmente ver a listagem genrica do diretrio HTML produzida
pelo mod_dav_svn. Ao informar webdav://host/repos ao invs de http://host/repos, faz
com que o Konqueror atue como cliente WebDAV e exiba o repositrio como um sistema de arquivos.
WebDrive, NetDrive
Ambos, WebDrive e NetDrive, so excelentes produtos comerciais que permitem que um
compartilhamento WebDAV seja mapeado como letras de drives no Windows. Nunca tivemos nada
alm de xito com estes produtos. No momento em que este livro estava sendo escrito, o WebDrive
podia ser adquirido junto a South River Technologies (http://www.southrivertech.com). J o NetDrive
vem junto com o Netware, sem custos adicionais, e pode ser encontrado na web procurando-se por
netdrive.exe. Ainda que esteja livremente disponvel na internet, os usurios precisam ter uma licena
do Netware para us-lo. (Se voc acha isso estranho, voc no est sozinho. Veja esta pgina no site
da Novell: http://www.novell.com/coolsolutions/qna/999.html)
Mac OS X
O sistema operacional OS X da Apple tem um cliente WebDAV integrado em nvel de sistema de
arquivos. A partir do Finder, selecione o item Connect to Server a partir do menu Go. Entre com uma
URL WebDAV, e ela aparecer como um disco em sua rea de trabalho, tal como qualquer outro
volume montado. Voc tambm pode montar um compartilhamento WebDAV a partir do terminal do
Darwin usando o tipo de sistema de arquivos webdav com o comando mount:
Note que se seu mod_dav_svn for anterior verso 1.2, o OS X vai se negar a montar o
compartilhamento como leitura-escrita; e ele aparecer como somente-leitura. Isto porque o OS X
insiste em usar travar para o suporte a compartilhamentos leitura-escrita, e o recurso de travas de
arquivos s surgiu no Subversion verso 1.2.
Mais uma palavra de alerta: o cliente WebDAV do OS X algumas vezes pode ser excessivamente
sensvel a redirecionamentos HTTP. Se o OS X no for capaz de montar um repositrio como um todo,
voc pode precisar habilitar a diretiva BrowserMatch no httpd.conf de seu servidor Apache:
Linux davfs2
Linux davfs2 um mdulo de sistema de arquivos para o kernel do Linux, cujo desenvolvimento est
centrado em http://dav.sourceforge.net/. Uma vez instalado este mdulo, um compartilhamento pode
ser montado normalmente com o comando mount do Linux:
329
Apndice D. Ferramentas de
Terceiros
O projeto modular do Subversion (abordado em Projeto da Biblioteca em Camadas) e a disponibilidade
de extenses para outras linguagens (como descrito em Usando Outras Linguagens alm de C e C
++) o tornam um provvel candidato a ser usado como uma extenso ou como suporte (backend)
para outros componentes de software. Para uma listagem de diversas ferramentas de terceiros que
esto elas mesmas fazendo uso de funcionalidades do Subversion, confira a pgina de Links no site
do Subversion (http://subversion.tigris.org/project_links.html).
330
Apndice E. Copyright
Copyright (c) 2002-2007
Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael Pilato.
--------------------------------------------------------------------
Voc pode:
* Para cada novo uso ou distribuio, voc deve deixar claro para
outros os termos da licena desta obra.
====================================================================
Licena
331
Copyright
1. Definies
a. "Obra Coletiva" significa uma obra, tal como uma edio peridica,
antologia ou enciclopdia, na qual a Obra em sua totalidade e de
forma inalterada, em conjunto com um nmero de outras
contribuies, constituindo obras independentes e separadas em si
mesmas, so agregadas em um trabalho coletivo. Uma obra que
constitua uma Obra Coletiva no ser considerada Obra Derivada
(conforme definido abaixo) para os propsitos desta licena.
332
Copyright
e. De modo a tornar claras estas disposies, quando uma Obra for uma
composio musical:
333
Copyright
EXCETO QUANDO FOR DE OUTRA FORMA MUTUAMENTE ACORDADO PELAS PARTES POR
ESCRITO, O LICENCIANTE OFERECE A OBRA NO ESTADO EM QUE SE ENCONTRA (AS
IS) E NO PRESTA QUAISQUER GARANTIAS OU DECLARAES DE QUALQUER ESPCIE
RELATIVAS OBRA, SEJAM ELAS EXPRESSAS OU IMPLCITAS, DECORRENTES DA LEI
OU QUAISQUER OUTRAS, INCLUINDO, SEM LIMITAO, QUAISQUER GARANTIAS SOBRE
A TITULARIDADE DA OBRA, ADEQUAO PARA QUAISQUER PROPSITOS,
NO-VIOLAO DE DIREITOS, OU INEXISTNCIA DE QUAISQUER DEFEITOS LATENTES,
ACURACIDADE, PRESENA OU AUSNCIA DE ERROS, SEJAM ELES APARENTES OU
OCULTOS. EM JURISDIES QUE NO ACEITEM A EXCLUSO DE GARANTIAS
IMPLCITAS, ESTAS EXCLUSES PODEM NO SE APLICAR A VOC.
334
Copyright
7. Terminao
8. Outras Disposies
335
Copyright
====================================================================
336
propget, 240
ndice Remissivo proplist, 241
propset, 243
resolved, 245
B revert, 246
BASE, 35 status, 248
switch, 252
C unlock, 254
COMMITTED, 35 update, 256
Concurrent Versions System (CVS), xii subcomandos
add, 201
H subcommands
HEAD, 35 blame, 203
cat, 204
svnadmin
P subcomando
PREV, 35 create, 259
propriedades, 37 deltify, 260
dump, 261
R help, 263
repositrio hotcopy, 264
ganchos list-dblogs, 265
post-commit, 305 list-unused-dblogs, 266
post-lock, 309 load, 267
post-revprop-change, 307 lslocks, 268
post-unlock, 311 lstxns, 269
pre-commit, 304 recover, 270
pre-lock, 308 rmlocks, 271
pre-revprop-change, 306 rmtxns, 272
pre-unlock, 310 setlog, 273
start-commit, 303 verify, 274
revises svnlook
especificadas como datas, 36 subcomando
termos de reviso, 35 changed, 278
date, 279
S diff, 280
Subversion dirs-changed, 281
histrico do, xvii help, 282
svn history, 283
subcomando info, 284
checkout, 205 lock, 285
cleanup, 207 log, 286
commit, 208 propget, 287
copy, 210 proplist, 288
delete, 212 tree, 289
diff, 214 uuid, 290
export, 217 youngest, 291
help, 219 subcomandos
import, 220 author, 276
info, 222 cat, 277
list, 225 svnsync
lock, 227 subcomando
log, 229 copy-revprops, 293
merge, 233 initialize, 294
mkdir, 235 synchronize, 295
move, 236 svnversion, 298
propdel, 238
propedit, 239
337