Controle de Versão com Subversion

Todos os sistemas de controle de versão têm de resolver o mesmo problema fundamental: como o sistema irá permitir que os usuários compartilhem informação, e como ele irá prevenir que eles acidentalmente tropecem uns nos pés dos outros? É muito fácil para os usuários acidentalmente sobrescrever as mudanças feitas pelos outros no repositório.

Considere o cenário mostrado em Figura 1.2, “O problema para evitar”. Vamos supor que nós temos dois colegas de trabalho, Harry e Sally. Cada um deles decide editar o mesmo arquivo no repositório ao mesmo tempo. Se Harry salvar suas alterações no repositório primeiro, então é possível que (poucos momentos depois) Sally possa acidentalmente sobrescrevê-lo com a sua própria nova versão do arquivo. Embora a versão de Harry não seja perdida para sempre (porque o sistema se lembra de cada mudança), todas as mudanças feitas por Harry não vão estar presentes na versão mais recente do arquivo de Sally, porque ela nunca viu as mudanças de Harry's para começar. O trabalho de Harry efetivamente se perdeu - ou pelo menos desapareceu da última versão do arquivo - e provavelmente por acidente. Trata-se definitivamente de uma situação que queremos evitar!

Figura 1.2. O problema para evitar

Muitos sistemas de controle de versão usam o modelo lock-modify-unlock (travar-modificar-destravar) para resolver o problema de vários autores destruírem o trabalho uns dos outros. Neste modelo, o repositório permite que apenas uma pessoa de cada vez altere o arquivo. Essa política de exclusividade é gerenciada usando locks (travas). Harry precisa “travar ” (lock) um arquivo antes que possa fazer alterações nele. Se Harry tiver travado o arquivo, então Sally não poderá travá-lo também, e portanto, não poderá fazer nenhuma alteração nele. Tudo que ela pode fazer é ler o arquivo, e esperar que Harry termine suas alterações 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 solução lock-modify-unlock” demonstra essa solução simples.

Figura 1.3. A solução lock-modify-unlock

O problema com o modelo lock-modify-unlock é que ele é um pouco restritivo, muitas vezes se torna um obstáculo para os usuários:

O Subversion, CVS, e muitos outros sistemas de controle de versão usam um modelo de copy-modify-merge (copiar-modificar-fundir) como uma alternativa ao locking. Nesse modelo, cada usuário se conecta ao repositório do projeto e cria uma cópia de trabalho pessoal (personal working copy, ou cópia local) - um espelho local dos arquivos e diretórios do repositório. Os usuários então trabalham simultaneamente e independentemente, modificando suas cópias privadas. Finalmente, as cópias privadas são fundidas (merged) numa nova versão final. O sistema de controle de versão freqüentemente ajuda com a fusão, mas, no final, a intervenção humana é a única capaz de garantir que as mudanças foram realizadas de forma correta.

Aqui vai um exemplo. Digamos que Harry e Sally criaram cada um a sua cópia de trabalho de um mesmo projeto, copiadas do repositório. Eles trabalharam simultaneamente fazendo alterações no arquivo A nas suas próprias cópias. Sally salva suas alterações no repositório primeiro. Quando Harry tentar salvar suas alterações mais tarde, o repositório vai informá-lo que seu arquivo A está desatualizado (out-of-date). Em outras palavras, o arquivo A do repositório foi de alguma forma alterado desde a última vez que ele foi copiado. Então Harry pede a seu programa cliente para ajudá-lo a fundir (merge) todas as alterações do repositório na sua cópia de trabalho do arquivo A. Provavelmente, as mudanças de Sally não se sobrepõem com as suas próprias; então, uma vez que ele tiver ambos os conjuntos de alterações integrados, ele salva sua cópia de trabalho de volta no repositório. As figuras Figura 1.4, “A solução copy-modify-merge” e Figura 1.5, “A solução copy-modify-merge (continuando)” mostram este processo.

Figura 1.4. A solução copy-modify-merge

Figura 1.5. A solução copy-modify-merge (continuando)

Mas e se as alterações de Sally sobrescreverem as de Harry? E então? Essa situação é chamada de conflito , e normalmente não é um problema. Quando Harry pedir a seu cliente para fundir as últimas alterações do repositório em sua cópia de trabalho local, sua cópia do arquivo A estará de alguma forma sinalizada como estando numa situação de conflito: ele será capaz de ver ambos os conjuntos de alterações conflitantes e manualmente escolher entre elas. Note que o software não tem como resolver os conflitos automaticamente; apenas pessoas são capazes de compreender e fazer as escolhas inteligentes. Uma vez que Harry tenha resolvido manualmente as alterações conflitantes - talvez depois de uma conversa com Sally - ele poderá tranqüilamente salvar o arquivo fundido no repositório.

O modelo copy-modify-merge pode soar um pouco caótico, mas, na prática, ele funciona de forma bastante suave. Os usuários podem trabalhar em paralelo, nunca esperando uns pelos outros. Quando eles trabalham nos mesmos arquivos, verifica-se que a maioria de suas alterações simultâneas não se sobrepõe afinal; conflitos não são muito freqüentes. 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 crítico: a comunicação entre os usuários. Quando os usuários se comunicam mal, tanto conflitos sintáticos como semânticos aumentam. Nenhum sistema pode forçar os usuários a se comunicarem perfeitamente, e nenhum sistema pode detectar conflitos semânticos. Portanto, não há como confiar nessa falsa sensação de segurança de que o sistema de locking vai prevenir conflitos; na prática, o lock parece inibir a produtividade mais do que qualquer outra coisa.

Ao longo de todo este livro, o Subversion utiliza URLs para identificar arquivos e diretórios versionados nos repositórios. Na maior parte, essas URLs usam a sintaxe padrão, permitindo nomes de servidor e números de porta serem especificados como parte da URL:

$ svn checkout http://svn.example.com:9834/repos
...

Mas existem algumas nuances no manuseio de URLs pelo Subversion que são notáveis. Por exemplo, URLs contendo o método de acesso file:// (usado para repositórios locais) precisam, de acordo com a convenção, ter como nome do servidor localhost ou nenhum nome de servidor:

$ svn checkout file:///path/to/repos
...
$ svn checkout file://localhost/path/to/repos
...

Além disso, usuários do esquema file:// em plataformas Windows precisarão utilizar um padrão de sintaxe “não-oficial” para acessar repositórios que estão na mesma máquina, mas em um drive diferente do atual drive de trabalho. Qualquer uma das seguintes sintaxes de URLs funcionarão, sendo X o drive onde o repositório reside:

C:\> svn checkout file:///X:/path/to/repos
...
C:\> svn checkout "file:///X|/path/to/repos"
...

Na segunda sintaxe, você precisa colocar a URL entre aspas de modo que o caractere de barra vertical não seja interpretado como um pipe. Além disso, note que a URL utiliza barras normais, enquanto no Windows os caminhos (não URLs) utilizam barra invertida.

Por último, convém notar que o cliente Subversion vai automaticamente codificar as URLs conforme necessário, de forma semelhante a um browser. Por exemplo, se a URL contiver espaços ou algum caractere não-ASCII:

$ svn checkout "http://host/path with space/project/españa"

...então o Subversion irá aplicar "escape" aos caracteres inseguros e se comportar como se você tivesse digitado:

$ svn checkout http://host/path%20with%20space/project/espa%C3%B1a

Se a URL contiver espaços, certifique-se de colocá-la entre aspas, de forma que o seu shell trate-a inteiramente como um único argumento do programa svn.

Você já leu sobre as cópias de trabalho; agora vamos demonstrar como o cliente do Subversion as cria e usa.

Uma cópia de trabalho do Subversion é uma árvore de diretórios comum no seu sistema de arquivos local, contendo uma coleção de arquivos. Você pode editar esses arquivos conforme desejar, e se eles são arquivos de código fonte, você pode compilar o seu programa a partir deles da maneira usual. Sua cópia de local é sua área de trabalho privada: O Subversion jamais incorporará as mudanças de terceiros ou tornará as suas próprias alterações disponíveis para os outros, até que você explicitamente o diga para fazer isso. Você pode ter múltiplas cópias de trabalho do o mesmo projeto.

Após você ter feito algumas alterações nos arquivos de sua cópia de trabalho e verificado que elas funcionam corretamente, o Subversion lhe disponibiliza comandos para “publicar” (commit) suas alterações para as outras pessoas que estão trabalhando com você no mesmo projeto (gravando no repositório). Se outras pessoas publicarem alterações, o Subversion disponibiliza comandos para fundir (merge) essas alterações em sua cópia de trabalho (lendo do repositório).

Uma cópia de trabalho também contém alguns arquivos extras, criados e mantidos pelo Subversion, para ajudá-lo a executar esse comandos. Em particular, cada diretório em sua cópia local contém um subdiretório chamado .svn, também conhecido como o diretório administrativo da cópia de local. Os arquivos em cada diretório administrativo ajudam o Subversion a reconhecer quais arquivos possuem alterações não-publicadas, e quais estão desatualizados em relação ao trabalho dos outros.

Um típico repositório Subversion freqüentemente detém os arquivos (ou código fonte) para vários projetos, geralmente, cada projeto é um subdiretório na árvore de arquivos do repositório. Desse modo, uma cópia de trabalho de um normalmente corresponderá a uma sub-árvore particular do repositório.

Por exemplo, suponha que você tenha um repositório que contenha dois projetos de software, paint e calc. Cada projeto reside em seu próprio subdiretório, como é mostrado em Figura 1.6, “O Sistema de Arquivos do Repositório”.

Figura 1.6. O Sistema de Arquivos do Repositório

Para obter uma cópia local, você deve fazer check out de alguma sub-árvore do repositório. (O termo “check out” pode soar como algo que tem a ver com locking ou com reserva de recursos, o que não é verdade; ele simplesmente cria uma cópia privada do projeto para você.) Por exemplo, se você fizer check out de /calc, você receberá uma cópia de trabalho como esta:

$ svn checkout http://svn.example.com/repos/calc
A    calc/Makefile
A    calc/integer.c
A    calc/button.c
Checked out revision 56.

$ 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 número de itens à sua cópia de trabalho. Você tem agora uma cópia pessoal do diretório /calc do repositório, com uma entrada adicional - .svn - a qual detém as informações extras que o Subversion precisa, conforme mencionado anteriormente.

Suponha que você faça alterações no arquivo button.c. Visto que o diretório .svn se lembra da data de modificação e conteúdo do arquivo original, o Subversion tem como saber que você modificou o arquivo. Entretanto o Subversion não torna as suas alterações públicas até você explicitamente lhe dizer para fazer isto. O ato de publicar as suas alterações é conhecido como committing (ou checking in) no repositório.

Para publicar as suas alterações para os outros, você deve usar o comando commit do Subversion.

$ svn commit button.c -m "Fixed a typo in button.c."
Sending        button.c
Transmitting file data .
Committed revision 57.

Agora as suas alterações no arquivo button.c foram “submetidas” no repositório, com uma nota descrevendo as suas alterações (especificamente você corrigiu um erro de digitação). Se outros usuários fizerem check out de /calc, eles verão suas alterações na última versão 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 alterações em button.c, a cópia de trabalho de Sally será deixada intacta; o Subversion somente modifica as cópias locais quando o usuário requisita.

Para atualizar o seu projeto, Sally pede ao Subversion para realizar um update na cópia de trabalho dela, usando o comando update do Subversion. Isto irá incorporar as suas alterações na cópia local dela, bem como as alterações 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 saída do comando svn update indica que o Subversion atualizou o conteúdo de button.c. Note que Sally não precisou especificar quais arquivos seriam atualizados; o Subversion usou as informações no diretório .svn, e mais algumas no repositório, para decidir quais arquivos precisariam ser atualizados.

Uma operação svn commit publica as alterações feitas em qualquer número de arquivos o diretórios como uma única transação atômica. Em sua cópia de trabalho, você pode alterar o conteúdo de arquivos; criar, deletar, renomear e copiar arquivos e diretórios; e então submeter um conjunto completo de alterações em uma transação atômica.

Por “transação atômica”, nos entendemos simplesmente isto: Ou são efetivadas todas as alterações no repositório, 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 ações de usuários.

Cada vez que o repositório aceita um commit, isto cria um novo estado na árvore de arquivos, chamado revisão. Cada revisão é assinalada com um único número natural, incrementado de um em relação à revisão anterior. A revisão inicial de um repositório recém criado é numerada com zero, e consiste em nada além de um diretório raiz vazio.

A figura Figura 1.7, “O Repositório” ilustra uma forma simples para visualizar o repositório. Imagine um array de números de revisões, iniciando em zero, alongando-se da esquerda para a direita. Cada número de revisão tem uma árvore de arquivos pendurada abaixo dela, e cada árvore é um “snapshot” da forma como o repositório podia ser visto após um commit.

Figura 1.7. O Repositório

É importante notar que nem sempre as cópias de trabalho correspondem a uma única revisão do repositório; elas podem conter arquivos de várias revisões diferentes. Por exemplo, suponha que você faça checkout de uma cópia de trabalho cuja revisão mais recente seja 4:

calc/Makefile:4
     integer.c:4
     button.c:4

Neste momento, este diretório de trabalho corresponde exatamente à revisão número 4 no repositório. Contudo, suponha que você faça uma alteração no arquivo button.c, e publique essa alteração. Assumindo que nenhum outro commit tenha sido feito, o seu commit irá criar a revisão 5 no repositório, e sua cópia de trabalho agora irá parecer com isto:

calc/Makefile:4
     integer.c:4
     button.c:5

Suponha que neste ponto, Sally publique uma alteração no arquivo integer.c, criando a revisão 6. Se você usar o comando svn update para atualizar a sua cópia de trabalho, então ela irá parecer com isto:

calc/Makefile:6
     integer.c:6
     button.c:6

A alteração de Sally no arquivo integer.c irá aparecer em sua cópia de trabalho, e a sua alteração no arquivo button.c ainda estará presente. Neste exemplo, o texto do arquivo Makefile é idêntico nas revisões 4, 5, e 6, mas o Subversion irá marcar a sua cópia do arquivo Makefile com a revisão 6 para indicar que a mesma é a corrente. Então, depois de você fazer uma atualização completa na sua cópia de trabalho, ela geralmente corresponderá exatamente a uma revisão do repositório.

Para cada arquivo em um diretório de trabalho, o Subversion registra duas peças de informações essenciais na área administrativa .svn/:

Dadas estas informações, conversando com o repositório, o Subversion pode dizer em qual dos seguintes quatro estados um arquivo local está:

Isto pode soar como muito para acompanhar, mas o comando svn status mostrará para você o estado de qualquer item em seu diretório local. Para maiores informações sobre este comando, veja “Obtendo uma visão geral de suas alterações”.

Como um princípio geral, o Subversion tenta ser tão flexível quanto possível. Um tipo especial de flexibilidade é a capacidade de ter uma cópia local contendo arquivos e diretórios com uma mistura de diferentes revisões. Infelizmente esta flexibilidade tende a confundir inúmeros novos usuários. Se o exemplo anterior mostrando revisões mistas deixou você perplexo, aqui está um exemplo mostrando tanto a razão pela qual o funcionalidade existe, quanto como fazer para usá-la.

O comando svn import é um modo rápido para copiar uma árvore de arquivos não versionada em um repositório, criando diretórios intermediários quando necessário. svn import não requer uma cópia de trabalho, e seus arquivos são imediatamente submetidos ao repositório. Isto é tipicamente usado quando você tem uma árvore de arquivos existente que você quer monitorar em seu repositório Subversion. Por exemplo:

$ svnadmin create /usr/local/svn/newrepos
$ svn import mytree file:///usr/local/svn/newrepos/some/project \
             -m "Importação inicial"
Adicionando    mytree/foo.c
Adicionando    mytree/bar.c
Adicionando    mytree/subdir
Adicionando    mytree/subdir/quux.h

Commit da revisão 1.

O exemplo anterior copiou o conteúdo do diretório mytree no diretório some/project no repositório:

$ svn list file:///usr/local/svn/newrepos/some/project
bar.c
foo.c
subdir/

Note que após a importação terminar, a árvore inicial não está convertida em uma cópia de trabalho. Para começar a trabalhar, você ainda precisa obter(svn checkout) uma nova cópia de trabalho da árvore.

Enquanto a flexibilidade do Subversion permite que você organize seu repositório da forma que você escolher, nós recomendamos que você crie um diretório trunk para armazenar a “linha principal” de desenvolvimento, um diretório branches para conter cópias ramificadas, e um diretório tags para conter cópias rotuladas, por exemplo:

$ svn list file:///usr/local/svn/repos
/trunk
/branches
/tags

Você aprenderá mais sobre tags e branches no Capítulo 4, Fundir e Ramificar. Para detalhes e como configurar múltiplos projetos, veja “Estrutura de Repositório” e “Planejando a Organização do Repositório” para ler mais sobre “raízes dos projetos”.

Quando você realiza uma operação no Subversion que requer autenticação, por padrão o Subversion mantém suas credenciais de autenticação num cache em disco. Isto é feito por conveniência, para que você não precise continuamente ficar redigitando sua senha em operações futuras. Se você estiver preocupado com o fato de o Subversion manter um cache de suas senhas, ^[3] você pode desabilitar o cache de forma permanente ou analisando caso a caso.

Para desabilitar o cache de senhas para um comando específico uma vez, passe a opção --no-auth-cache na linha de comando. Para desabilitar permanentemente o cache, você pode adicionar a linha store-passwords = no no arquivo de configuração local do seu Subversion. Veja “Armazenando Credenciais no Cliente” para maiores detalhes.

Uma vez que por padrão o Subversion mantém um cache com as credenciais de autenticação (tanto usuário quanto senha), ele convenientemente se lembra que era você estava ali na última vez que você modificou sua cópia de trabalho. Mas algumas vezes isto não é útil — particularmente se você estava trabalhando numa cópia de trabalho compartilhada, como um diretório de configuração do sistema ou o documento raiz de um servidor web. Neste caso, apenas passe a opção --username na linha de comando e o Subversion tentará autenticar como aquele usuário, pedindo uma senha se necessário.

Ao trabalhar num projeto em equipe, você vai querer atualizar sua cópia de trabalho para receber quaisquer alterações feitas por outros desenvolvedores do projeto desde sua última atualização. Use svn update para deixar sua cópia de trabalho em sincronia com a última revisão no repositório.

$ svn update
U  foo.c
U  bar.c
Updated to revision 2.

Neste caso, alguém submeteu modificações em foo.c e bar.c desde a última vez que você atualizou, e o Subversion atualizou sua cópia de trabalho para incluir estas modificações.

Quando o servidor envia as alterações para sua cópia de trabalho por meio do svn update, uma letra é exibida como código próximo de cada item para que você saiba que ações o Subversion executou para deixar sua cópia de trabalho atualizada. Para conferir o que essas letras significam, veja svn update.

Agora você já pode trabalhar e fazer alterações em sua cópia de trabalho. É comumente mais conveniente optar por fazer uma alteração (ou conjunto de alterações) discreta, como escrever um novo recurso, corrigir um bug, etc. Os comandos do Subversion que você usará aqui são svn add, svn delete, svn copy, svn move, e svn mkdir. No entanto, se você está meramente editando arquivos que já se encontram no Subversion, você pode não precisar usar nenhum destes comandos para registrar suas alterações.

Há dois tipos de alterações que você pode fazer em sua cópia de trabalho: alterações nos arquivos e alterações na árvore. Você não precisa avisar ao Subversion que você pretende modificar um arquivo; apenas faça suas alterações usando seu editor de texto, suite de escritório, programa gráfico, ou qualquer outra ferramenta que você use normalmente. O Subversion automaticamente irá identificar que arquivos foram modificados, ele também vai manipular arquivos binários da mesma forma que manipula arquivos de texto—e tão eficientemente quanto. Para alterações na árvore, você pode solicitar ao Subversion que “marque” os arquivos e diretórios para remoção, adição, cópia ou movimentação agendada. Estas alterações terão efeito imediatamente em sua cópia de trabalho, mas nenhuma adição ou remoção vai acontecer no repositório até que você registre tais alterações.

Aqui está uma visão geral dos cinco subcomandos do Subversion que você vai usar mais frequentemente para fazer alterações na árvore.

Tendo terminado de fazer suas alterações, você precisa registrá-las no repositório, mas antes de fazer isso, é quase sempre uma boa idéia conferir exatamente que alterações você fez. Ao verificar suas alterações antes de dar commit, você pode criar uma mensagem de log bem mais adequada. Você também pode descobrir se não modificou um arquivo inadvertidamente, e então ter a oportunidade de reverter essas modificações antes de dar commit. Você pode ter uma visão geral das alterações que você fez usando svn status, e obter os detalhes sobre essas alterações usando svn diff.

O Subversion está sendo otimizado para ajudar você com esta tarefa e é capaz de fazer muitas coisas sem se comunicar com o repositório. Em particular, sua cópia de trabalho contém um cache escondido com uma cópia “intacta” de cada arquivo sob controle de versão 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 alterações sem contactar o repositório.

A       stuff/loot/bloo.h   # arquivo agendado para adição
C       stuff/loot/lump.c   # arquivo em conflito a partir de um update
D       stuff/fish.c        # arquivo agendado para exclusão
M       bar.c               # conteúdo em bar.c tem alterações locais 

$ svn status stuff/fish.c
D      stuff/fish.c

$ 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

$ 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

$ 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) {
-  printf("Sixty-four slices of American Cheese...\n");
+  printf("Sixty-five slices of American Cheese...\n");
 return 0;
 }

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.

$ svn diff > patchfile

Suponha que ao ver a saída do svn diff você decida que todas as modificações que você fez em um certo arquivo foram equivocadas. Talvez você não tivesse que ter modificado o arquivo como um todo, ou talvez você veja que acabará sendo mais fácil fazer outras modificações começando tudo de novo.

Esta é uma oportunidade perfeita para usar o comando svn revert:

$ svn revert README
Reverted 'README'

O Subversion reverte o arquivo para seu estado antes da alteração sobrescrevendo-o com a cópia “intacta” que está na área .svn. Mas atente também que svn revert pode desfazer quaisquer operações agendadas—por exemplo, você pode decidir que você não quer mais adicionar um novo arquivo:

$ svn status foo
?      foo

$ svn add foo
A         foo

$ svn revert foo
Reverted 'foo'

$ svn status foo
?      foo

Ou talvez você tenha removido um arquivo do controle de versão por engano:

$ svn status README
       README

$ svn delete README
D         README

$ svn revert README
Reverted 'README'

$ svn status README
       README

Já vimos como o svn status -u pode prever conflitos. Suponha que você execute svn update e aconteça algo interessante:

$ svn update
U  INSTALL
G  README
C  bar.c
Updated to revision 46.

Os códigos U e G não são motivo de preocupação; esses arquivos absorveram as alterações do repositório normalmente. O arquivo marcado com U não continha modificações locais mas foi atualizado (Updated) com as modificações do repositório. O G vem de merGed, o que significa que o arquivo local continha alterações inicialmente, e que também houve alterações vindas do repositório, que no entanto não se sobrepuseram às alterações locais.

Já o C significa Conflito. Isto quer dizer que as modificações do servidor se sobrepõem com as suas próprias, e que agora você precisa escolher entre elas manualmente.

Sempre que um conflito ocorre, normalmente acontecem três coisas para ajudar você a compreender e resolver este conflito:

Como exemplo, Sally faz modificações no arquivo sandwich.txt no repositório. Harry acabou de alterar o arquivo em sua cópia de trabalho e o submeteu. Sally atualiza sua cópia 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 não vai deixar que você submeta o arquivo sandwich.txt até que os três arquivos temporários sejam removidos.

$ svn commit -m "Add a few more things"
svn: Commit failed (details follow):
svn: Aborting commit: '/home/sally/svn-work/sandwich.txt' remains in conflict

Se você tiver um conflito, você precisa fazer uma dessas três coisas:

Uma vez que você tenha resolvido o conflito, você precisa informar isto ao Subversion executando svn resolved. Isso remove os três arquivos temporários e o Subversion não mais considera o arquivo como estando em conflito.^[6]

$ svn resolved sandwich.txt
Resolved conflicted state of 'sandwich.txt'

$ 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
=======

=======
Sauerkraut
Grilled Chicken
>>>>>>> .r2

Top piece of bread
Mayonnaise
Lettuce
Tomato
Provolone
Salami
Mortadella
Prosciutto
Creole Mustard
Bottom piece of bread

$ svn resolved sandwich.txt
$ svn commit -m "Go ahead and use my sandwich, discarding Sally's edits."

$ 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

$ svn revert sandwich.txt
Reverted 'sandwich.txt'
$ ls sandwich.*
sandwich.txt

Finalmente! Suas edições estão concluídas, você mesclou todas as alterações do servidor, e agora está pronto para registrar suas alterações no repositório.

O comando svn commit envia todas as suas modificações para o servidor. Quando você registra uma alteração, você precisa informar uma mensagem de log, descrevendo sua alteração. Sua mensagem de log será anexada à nova revisão que você criar. Se sua mensagem de log for breve, você pode querer escrevê-la na própria linha de comando usando a opção --message (ou -m):

$ svn commit -m "Corrected number of cheese slices."
Sending        sandwich.txt
Transmitting file data .
Committed revision 3.

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 opção --file (-F):

$ svn commit -F logmsg
Sending        sandwich.txt
Transmitting file data .
Committed revision 4.

Se você não especificar a opção --message nem a --file, o Subversion vai abrir automaticamente seu editor de texto preferido (veja a seção editor-cmd em “Configuração”) para compor a mensagem de log.

$ svn commit
Waiting for Emacs...Done

Log message unchanged or not specified
a)bort, c)ontinue, e)dit
a
$

O repositório não sabe nem mesmo se importa se suas modificações sequer fazem sentido como um todo; ele apenas garante que ninguém mais tenha modificado nada dos mesmos arquivos que você enquanto você não estava olhando. Se alguém tiver feito isso, o commit todo irá falhar com uma mensagem informando a você que um ou mais de seus arquivos está desatualizado:

$ svn commit -m "Add another rule"
Sending        rules.txt
svn: Commit failed (details follow):
svn: Your file or directory 'sandwich.txt' is probably out-of-date
…

(Os dizeres exatos desta mensagem de erro dependem de qual protocolo de rede e qual servidor você está usando, mas a idéia é 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 básico de trabalho no uso do Subversion. Há muitos outros recursos no Subversion que você pode usar para gerenciar seu repositório e sua cópia de trabalho, mas muito de seu uso cotidiano do Subversion vai envolver apenas os comandos que discutimos neste capítulo. Vamos, entretanto, abordar mais uns poucos comandos que você também pode usar bastante.

Para encontrar informação acerca do histórico de um arquivo ou diretório, use o comando svn log. O svn log vai lhe dar um registro de quem fez alterações em um arquivo ou diretório, em qual revisão houve a mudança, a data e hora daquela revisão, e, se for informada, a mensagem de log associada a esse registro.

$ svn log
------------------------------------------------------------------------
r3 | sally | Mon, 15 Jul 2002 18:03:46 -0500 | 1 line

Added include lines and corrected # of cheese slices.
------------------------------------------------------------------------
r2 | harry | Mon, 15 Jul 2002 17:47:57 -0500 | 1 line

Added main() methods.
------------------------------------------------------------------------
r1 | sally | Mon, 15 Jul 2002 17:40:08 -0500 | 1 line

Initial import
------------------------------------------------------------------------

Veja que as mensagens de log são exibidas em ordem cronológica inversa por padrão. Se você quiser ver um intervalo de revisões em uma ordem específica, ou apenas uma única revisão, utilize a opção --revision (-r):

$ svn log -r 5:19    # exibe os logs de 5 a 19 em ordem cronológica

$ svn log -r 19:5    # exibe os logs de 5 a 19 na order inversa

$ svn log -r 8       # mostra o log para a revisão 8

Você também pode examinar o histórico de logs de um único arquivo ou diretório. Por exemplo:

$ svn log foo.c
…
$ svn log http://foo.com/svn/trunk/code/foo.c
…

Isto vai exibir as mensagens de log apenas para aquelas revisões nas quais o arquivo de trabalho (ou a URL) mudaram.

Se você quiser ainda mais informação sobre um arquivo ou diretório, o svn log também aceita uma opção --verbose (-v). Como o Subversion lhe permite mover e copiar arquivos e diretórios, é importante ser capaz de rastrear alterações de caminhos no sistema de arquivos, então no modo verboso, o svn log vai incluir na sua saída uma lista dos caminhos alterados em uma revisão:

$ 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

Frozzled the sub-space winch.

------------------------------------------------------------------------

O svn log também aceita uma opção --quiet (-q), que suprime o corpo da mensagem de log. Quando combinada com a opção --verbose, ela apresentará apenas os nomes dos arquivos mudados.

$ svn log -r 2
------------------------------------------------------------------------
$

Nós já vimos o svn diff antes—ele exibe as diferenças de arquivo no formato diff unificado; ele foi usado para mostrar as modificações locais feitas em nossa cópia de trabalho antes de serem registradas no repositório.

Na realidade, tem-se que existem três 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
$

$ svn diff -r 3 rules.txt
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
$

$ svn diff -r 2:3 rules.txt
Index: rules.txt
===================================================================
--- rules.txt	(revision 2)
+++ rules.txt	(revision 3)
@@ -1,4 +1,4 @@
 Be kind to others
-Freedom = Chocolate Ice Cream
+Freedom = Responsibility
 Everything in moderation
 Chew with your mouth open
$

$ svn diff -c 3 rules.txt
Index: rules.txt
===================================================================
--- rules.txt	(revision 2)
+++ rules.txt	(revision 3)
@@ -1,4 +1,4 @@
 Be kind to others
-Freedom = Chocolate Ice Cream
+Freedom = Responsibility
 Everything in moderation
 Chew with your mouth open
$

$ svn diff -c 5 http://svn.example.com/repos/example/trunk/text/rules.txt
…
$

Usando svn cat e svn list, você pode ver várias revisões de arquivos e diretórios sem precisar mexer nas alterações que estiver fazendo em sua cópia de trabalho. De fato, você nem mesmo precisa de uma cópia de trabalho para usar esses comandos.

$ svn cat -r 2 rules.txt
Be kind to others
Freedom = Chocolate Ice Cream
Everything in moderation
Chew with your mouth open
$

$ svn cat -r 2 rules.txt > rules.txt.v2
$

$ svn list http://svn.collab.net/repos/svn
README
branches/
clients/
tags/
trunk/

$ svn list -v http://svn.collab.net/repos/svn
  20620 harry            1084 Jul 13  2006 README
  23339 harry                 Feb 04 01:40 branches/
  21282 sally                 Aug 27 09:41 developer-resources/
  23198 harry                 Jan 23 17:17 tags/
  23351 sally                 Feb 05 13:26 trunk/

Além de todos os comandos acima, você pode usar o svn update e o svn checkout com a opção --revision para fazer com que toda a sua cópia de trabalho “volte no tempo” ^[8]:

$ svn checkout -r 1729 # Obtém uma nova cópia de trabalho em r1729
…
$ svn update -r 1729 # Atualiza a cópia de trabalho existente para r1729
…

Finalmente, se você estiver criando uma versão final e quiser empacotar seus arquivos do Subversion mas não gostaria de incluir os incômodos diretórios .svn de forma nenhuma, então você pode usar o comando svn export para criar uma cópia local de todo o conteúdo de seu repositório mas sem os diretórios .svn. Da mesma forma que com o svn update e svn checkout, você também pode incluir a opção --revision ao svn export:

$ svn export http://svn.example.com/svn/repos1 # Exports latest revision
…
$ svn export http://svn.example.com/svn/repos1 -r 1729
# Exports revision r1729
…

O cliente Subversion entende um conjunto de termos de revisão. Estes termos podem ser usados no lugar dos argumentos inteiros para a opção --revision (-r), e são resolvidos para números de revisão específicos pelo Subversion:

Como pode ser deduzido de suas descrições, os termos de revisão PREV, BASE, e COMMITTED são usados apenas quando se referirem a um caminho numa cópia de trabalho—eles não se aplicam a URLs do repositório. HEAD, por outro lado, pode ser usado em conjunto para qualquer um desses tipos de caminho.

Aqui estão alguns exemplos da utilização de termos de revisão:

$ svn diff -r PREV:COMMITTED foo.c
# exibe a última alteração submetida em foo.c

$ svn log -r HEAD
# mostra a mensagem de log do último registro no repositório

$ svn diff -r HEAD
# compara sua cópia de trabalho (com todas suas alterações locais) com a 
# última versão na árvore do diretório

$ svn diff -r BASE:HEAD foo.c
# compara a versão inalterada de foo.c com a última versão de
# foo.c no repositório

$ svn log -r BASE:HEAD
# mostra todos os logs das submissões para o diretório atual versionado
# desde a última atualização que você fez em sua cópia de trabalho

$ svn update -r PREV foo.c
# retorna à última alteração feita em foo.c, reduzindo o número de
# revisão de foo.c

$ svn diff -r BASE:14 foo.c
# compara a versão inalterada de foo.c com o conteúdo que foo.c tinha na
# revisão 14

Números de revisão não revelam nada sobre o mundo fora do sistema de controle de versão, mas algumas vezes você precisa correlacionar um momento em tempo real com um momento no histórico de revisões. Para facilitar isto, a opção --revision (-r) também pode aceitar especificadores de data delimitados por chaves ({ e }) como entrada. O Subversion aceita datas e horas no padrão ISO-8601, além de alguns poucos outros. Aqui estão alguns exemplos. (Lembre-se de usar aspas para delimitar quaisquer datas que contenham espaços.)

$ svn checkout -r {2006-02-17}
$ svn checkout -r {15:30}
$ svn checkout -r {15:30:00.200000}
$ svn checkout -r {"2006-02-17 15:30"}
$ svn checkout -r {"2006-02-17 15:30 +0230"}
$ svn checkout -r {2006-02-17T15:30}
$ svn checkout -r {2006-02-17T15:30Z}
$ svn checkout -r {2006-02-17T15:30-04:00}
$ svn checkout -r {20060217T1530}
$ svn checkout -r {20060217T1530Z}
$ svn checkout -r {20060217T1530-0500}
…

Quando você especifica uma data, o Subversion resolve aquela data para a revisão mais recente do repositório com aquela data, e então continua a operação usando o número de revisão obtido:

$ svn log -r {2006-11-28}
------------------------------------------------------------------------
r12 | ira | 2006-11-27 12:31:51 -0600 (Mon, 27 Nov 2006) | 6 lines
…

Você também pode usar intervalos de datas. O Subversion vai encontrar todas as revisões entre as datas, inclusive:

$ svn log -r {2006-11-20}:{2006-11-29}
…

Como o Subversion usa propriedades para armazenar informações extras sobre arquivos, diretórios, e revisões que as contém, você também pode usar propriedades de forma semelhante. Você poderia achar útil ter um lugar próximo de seus dados versionados para pendurar metadados personalizados sobre estes dados.

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 possível. Estas fotos podem ser um pouco grandes, então, como muito comum em sites desse tipo, você quer disponibilizar prévias 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 diretório. Ou se você quiser manter os mesmos nomes de arquivos, você poderia ter suas miniaturas em um diretório diferente, como thumbnails/image123.jpg. Você também pode armazenar suas legendas e datas e horários de forma parecida, também separadas do arquivo da foto original. Mas o problema aqui é que o conjunto de arquivos aumenta aos múltiplos para cada nova foto adicionada ao site.

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 então propriedades definidas neste arquivo chamadas caption, datestamp, ou mesmo thumbnail (respectivamente para a legenda, data e hora, e miniatura da imagem). Agora sua cópia de trabalho parece muito mais gerenciável—de fato, numa primeira visualização, não parece haver nada mais além dos arquivos de imagem lá dentro. Mas seus scripts de automação sabem mais. Eles sabes que podem usar o svn (ou melhor ainda, eles podem usar a linguagem incorporada ao Subversion—veja “Usando as APIs”) para para extrair as informações 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.

As propriedades personalizadas de revisões também são freqüentemente usadas. Um de seus usos comuns é uma propriedades cujo valor contém um recurso de ID de rastreamento ao qual a revisão está associada, talvez pelo fato de a alteração feita nesta revisão corrigir um problema relatado externamente com aquele ID. Outros usos incluem a inserção de nomes mais amigáveis à revisão—pode ser difícil lembrar que a revisão 1935 foi uma revisão testada completamente. Mas se houver, digamos, uma propriedade resultado-dos-testes nesta revisão com o valor todos passaram, esta á uma informação bem mais significativa de se ter.

Issue(s): IZ2376, IZ1919
Reviewed by:  sally

Isto corrige um erro de falha de segmentação no gerenciador de processos
…

O comando svn oferece algumas poucas maneiras de se adicionar ou modificar propriedades de arquivos e diretórios. Para propriedades com valores pequenos, legíveis 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.

$ svn propset copyright '(c) 2006 Red-Bean Software' calc/button.c
property 'copyright' set on 'calc/button.c'
$

Mas sempre podemos contar com a flexibilidade que o Subversion oferece para seus valores de propriedades. E se você está planejando ter texto com múltiplas linhas, ou mesmo valores binários para o valor da propriedade, você provavelmente não vai informar este valor pela linha de comando. Então, o subcomando propset leva uma opção --file (-F) para especificar o nome de um arquivo que contém o valor para a nova propriedade.

$ svn propset license -F /path/to/LICENSE calc/button.c
property 'license' set on 'calc/button.c'
$

Há algumas restrições sobre os nomes que você pode usar para propriedades. Um nome de propriedade deve começar com uma letra, dois-pontos (:), ou um caractere sublinha (_); e depois disso, você também pode usar dígitos, hifens (-), e pontos (.). ^[9]

Além do propset, o programa svn também oferece comando propedit. Este comando usa o editor de texto configurado (veja “Configuração”) para adicionar ou modificar propriedades. Quando você executa este comando, o svn chama seu programa editor em um arquivo temporário que contém o valor atual da propriedade (ou o qual é vazio, se você estiver adicionando uma nova propriedade). Então, 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 alteração, nenhuma modificação 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 são 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, nós poderíamos ter feito:

$ svn propset copyright '(c) 2006 Red-Bean Software' calc/*
property 'copyright' set on 'calc/Makefile'
property 'copyright' set on 'calc/button.c'
property 'copyright' set on 'calc/integer.c'
…
$

Toda esta adição e alteração de propriedades não é realmente muito útil se você não puder obter facilmente o valor armazenado da propriedade. Então o programa svn dispõe de dois subcomando para exibição dos nomes e valores das propriedades armazenadas nos arquivos e diretórios. 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 saída padrão.

$ svn proplist calc/button.c
Properties on 'calc/button.c':
  copyright
  license
$ svn propget copyright calc/button.c
(c) 2006 Red-Bean Software

Há ainda uma variação do comando proplist que lista tanto o nome quanto o valor de todas as propriedades. Apenas informe a opção --verbose (-v).

$ svn proplist -v calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2006 Red-Bean Software
  license : ================================================================
Copyright (c) 2006 Red-Bean Software.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions 
are met:

1. Redistributions of source code must retain the above copyright
notice, this list of conditions, and the recipe for Fitz's famous
red-beans-and-rice.
…

O último subcomando relacionado a propriedades é o propdel. Como o Subversion permite armazenar propriedades com valores vazios, você não pode remover uma propriedade usando propedit ou propset. Por exemplo, este comando não vai surtir o efeito desejado:

$ svn propset license '' calc/button.c
property 'license' set on 'calc/button.c'
$ svn proplist -v calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2006 Red-Bean Software
  license : 
$

Você precisa usar o subcomando propdel para remover propriedades completamente. A sintaxe é semelhante a dos outros comandos de propriedades:

$ svn propdel license calc/button.c
property 'license' deleted from 'calc/button.c'.
$ svn proplist -v calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2006 Red-Bean Software
$

Lembra das propriedades não-versionadas de revisões? Você pode modificá-las, também, usando os mesmo subcomandos do svn que acabamos de descrever. Apenas adicione o parâmetro --revprop na linha de comando, e especifique a revisão cujas propriedades você quer modificar. Como as revisões são globais, você não precisa especificar um caminho para para estes comandos relacionados a propriedades enquanto estiver em uma cópia de trabalho do repositório cuja propriedade de revisão você queira alterar. Por outro lado, você pode apenas especificar a URL de qualquer caminho de seu interesse no repositório (incluindo a URL raiz do repositório). Por exemplo, você pode querer trocar a mensagem de log de um registro de alteração de uma revisão existente. ^[10] Se seu diretório atual for parte da cópia de trabalho de seu repositório, 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ê não tenha criado uma cópia de trabalho a partir do repositório, você ainda assim pode proceder com modificação de propriedades informando a URL raiz do repositório:

$ 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 permissão para se alterar estas propriedades não-versionadas deve ser explicitamente concedida pelo administrador do repositório (veja “Corrigindo Mensagens de Log Submetidas”). Isto é porque as propriedades não são versionadas, então você corre o risco de perder informação se não for cuidadoso com suas alterações. O administrador do repositório pode definir formas de proteção contra perda de dados, e por padrão, além de que as modificações de propriedades não-versionadas são desabilitadas por padrão.

Agora que você está familiarizado com todos os subcomandos svn relacionados a propriedades, vamos ver como as modificações de propriedades afetam o fluxo de trabalho usual do Subversion. Como mencionado anteriormente, as propriedades de arquivos e diretórios são versionadas, tal como os conteúdos de arquivos. Como resultado, o Subversion dispõe dos mesmos recursos para mesclar—de forma limpa ou com conflitos—alterações de terceiros às nossas próprias.

E como com conteúdos de arquivos, suas mudanças de propriedades são modificações locais, que são tornadas permanentes apenas quando submetidas ao repositório com o comando svn commit. Suas alterações de propriedades também podem ser facilmente desfeitas—o comando svn revert vai restaurar seus arquivos e diretórios para seus estados inalterados—conteúdos, propriedades, e tudo. Também, você pode obter informações interessantes sobre o estado de suas propriedades de arquivos e diretórios usando os comandos svn status e svn diff.

$ svn status calc/button.c
 M     calc/button.c
$ svn diff calc/button.c
Property changes on: calc/button.c
___________________________________________________________________
Name: copyright
   + (c) 2006 Red-Bean Software

$

Note como o subcomando status exibe M na segunda coluna ao invés de na primeira. Isto é porque modificamos as propriedades de calc/button.c, mas não seu conteúdo textual. Se tivéssemos modificado ambos, deveríamos ver um M na primeira coluna também (veja “Obtendo uma visão geral de suas alterações”).

% svn update calc
M  calc/Makefile.in
 C calc/button.c
Updated to revision 143.
$ 

$ svn status calc
 C     calc/button.c
?      calc/button.c.prej
$ cat calc/button.c.prej 
prop 'linecount': user set to '1256', but update set to '1301'.
$

Você também deve ter notado a forma não-padrão como o Subversion atualmente exibe diferenças de propriedades. Você ainda pode executar svn diff e redirecionar a saída para criar um arquivo de patch usável. O programa patch vai ignorar patches de propriedades—como regra, ele ignora qualquer coisa que não consiga entender. Isso significa, infelizmente, que para aplicar completamente um patch gerado pelo svn diff, quaisquer alterações em propriedades precisarão ser aplicadas manualmente.

Propriedades são um poderoso recurso do Subversion, agindo como componentes chave em muitos outros recursos apresentados neste e em outros capítulos—suporte a diferenciação e mesclagem textual, substituição de palavras-chave, conversão de delimitadores de linha, etc. Mas para aproveitar plenamente as propriedades, elas devem ser definidas nos arquivos e diretórios certos. Infelizmente, este passo é facilmente esquecido na rotina de ações de usuário, especialmente pelo fato de que a não atribuição de uma propriedade normalmente não resulta em nenhum erro óbvio (ao menos quando comparado a, digamos, esquecer de adicionar um arquivo ao controle de versão). Para ajudar que suas propriedades sejam aplicadas em seus devidos locais, o Subversion dispõem de uma porção de recursos simples e poderosos.

Sempre que você inclui um arquivo ao controle de versão 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 permissão de execução, o Subversion automaticamente vai definir a propriedade svn:executable nos arquivos recém adicionados ou importados nos quais o bit de execução esteja ativo. (Veja “Executabilidade de Arquivo” para mais sobre esta propriedade.) Em segundo lugar, ele executa uma heurística bem básica para identificar se o arquivo contém algum conteúdo que seja legível por humanos. Se não, o Subversion automaticamente vai definir a propriedade svn:mime-type naquele arquivo para application/octet-stream (o tipo MIME genérico para “isto é um conjunto de bytes”). Claro que se o Subversion identificou corretamente, ou se você quiser definir a propriedade svn:mime-type para algo mais preciso—talvez image/png ou application/x-shockwave-flash—você sempre pode remover ou editar esta propriedade. (Para mais sobre como o Subversion faz uso dos tipos MIME, veja “Tipo de Conteúdo do Arquivo”.)

O Subversion também oferece, através de seu sistema de configuração em tempo de execução (veja “Área de Configuração do Tempo de Execução”), um mecanismo mais flexível de definição automática de propriedades que permite a você criar mapeamentos de padrões de nome de arquivos para nomes de propriedades e valores. Novamente, estes mapeamentos afetam adições e importações e não apenas podem sobrescrever a identificação sobre o tipo MIME padrão feita pelo Subversion durante suas operações, como pode definir propriedades do Subversion adicionais e personalizadas também. Por exemplo, você poderia criar um mapeamento que dissesse que sempre que você adicionar arquivos JPEG—aqueles cujos nomes casem com o padrão *.jpg—o Subversion deveria automaticamente definir a propriedade svn:mime-type destes arquivos para image/jpeg. Ou talvez quaisquer arquivos que correspondam ao padrão *.cpp deveriam ter a propriedade svn:eol-style definida para native, e svn:keywords atribuída para Id. Suporte a propriedades automáticas talvez seja a ferramenta mais prática no conjunto de ferramentas do Subversion. Veja “Configuração” para mais sobre a configuração deste recurso.

O Subversion combina a qualidade das muitas aplicações que reconhecem e fazem uso dos tipos de conteúdo do Multipurpose Internet Mail Extensions (MIME). Além de ser um local de armazenamento de propósito geral para um tipo de conteúdo do arquivo, o valor da propriedade de arquivo svn:mime-type determina algumas características comportamentais do próprio Subversion.

Por exemplo, um dos benefícios que o Subversion tipicamente fornece é a fusão contextual, baseada nas linhas, das mudanças recebidas do servidor durante uma atualização em seu arquivo de trabalho. Mas, para arquivos contendo dados não-textuais, muitas vezes não existe o conceito de “linha”. Assim, para os arquivos versionados cuja propriedade svn:mime-type é definida com um tipo MIME não-textual (geralmente, algo que não inicie com text/, embora existam exceções), o Subversion não tenta executar fusões contextuais durante as atualizações. Em vez disso, quando você modifica localmente um arquivo binário em sua cópia de trabalho, na momento da atualização, seu arquivo não é mexido, pois o Subversion cria dois novos arquivos. Um deles tem a extensão .oldrev e contém a revisão BASE do arquivo. O outro arquivo tem uma extensão .newrev e contém o conteúdo da revisão atualizada do arquivo. Este comportamento serve de proteção ao usuário contra falhas na tentativa de executar fusões contextuais nos arquivos que simplesmente não podem ser contextualmente fundidos.

Além disso, se a propriedade svn:mime-type estiver definida, então o módulo Apache do Subversion usará seu valor para preencher o cabeçalho HTTP Content-type: quando responder a solicitações GET. Isto oferece ao navegador web uma dica crucial sobre como exibir um arquivo quando você o utiliza para examinar o conteúdo de seu repositório Subversion.

Em muitos sistemas operacionais, a capacidade de executar um arquivo como um comando é comandada pela presença de um bit de permissão para execução. Este bit, usualmente, vem desabilitado por padrão, e deve ser explicitamente habilitado pelo usuário em cada arquivo que seja necessário. Mas seria um grande incômodo ter que lembrar, exatamente, quais arquivos de uma cópia de trabalho verificada recentemente estavam com seus bits de execução habilitados, e, então, ter que trocá-los. Por esta razão, o Subversion oferece a propriedade svn:executable, que é um modo de especificar que o bit de execução para o arquivo no qual esta propriedade está definida deve ser habilitado, e o Subversion honra esta solicitação ao popular cópias de trabalho com tais arquivos.

Esta propriedade não tem efeito em sistemas de arquivo que não possuem o conceito de bit de permissão para executável, como, por exemplo, FAT32 e NTFS. ^[12] Além disso, quando não houver valor definido, o Subversion forçará o valor * ao definir esta propriedade. Por fim, esta propriedade só é válido em arquivos, não em diretórios.

A não você ser que esteja usando a propriedade svn:mime-type em um arquivo sob controle de versão, o Subversion assume que o arquivo contém dados humanamente legíveis. De uma forma geral, o Subversion somente usa esse conhecimento para determinar se os relatórios de diferenças contextuais para este arquivo são possíveis. Ao contrário, para o Subversion, bytes são bytes.

Isto significa que, por padrão, o Subversion não presta qualquer atenção para o tipo de marcadores de fim-de-linha, ou end-of-line (EOL) usados em seus arquivos. Infelizmente, diferentes sistemas operacionais possuem diferentes convenções sobre qual seqüência de caracteres representa o fim de uma linha de texto em um arquivo. Por exemplo, a marca usual de término de linha usada por softwares na plataforma Windows é um par de caracteres de controle ASCII—um retorno de carro (CR) seguido por um avanço de linha (LF). Os softwares em Unix, entretanto, utilizam apenas o caracter LF para definir o término de uma linha.

Nem todas as ferramentas nestes sistemas operacionais compreendem arquivos que contêm terminações de linha em um formato que difere do estilo nativo de terminação de linha do sistema operacional no qual estão 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 combinação dos caracteres de retorno de carro e avanço de linha (ou CRLF) foi encontrada para determinar os términos 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 código-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 término de linha do arquivo, nenhum problema ocorrerá.

Mas na prática, muitas ferramentas comuns, ou falham ao ler um arquivo com marcadores EOL externos, ou convertem as terminações de linha do arquivo para o estilo nativo quando o arquivo é salvo. Se o precedente é verdadeiro para um desenvolvedor, ele deve usar um utilitário de conversão externo (tal como dos2unix ou seu similar, unix2dos) para preparar o arquivo para edição. O caso posterior não requer nenhuma preparação extra. Mas ambos os casos resultam em um arquivo que difere do original literalmente em cada uma das linhas! Antes de submeter suas alterações, o usuário tem duas opções. Ou ele pode utilizar um utilitário de conversão para restaurar o arquivo modificado para o mesmo estilo de término de linha utilizado antes de suas edições serem feitas. Ou ele pode simplesmente submeter o arquivo—as novas marcas EOL e tudo mais.

O resultado de cenários como estes incluem perda de tempo e modificações desnecessárias aos arquivos submetidos. A perda de tempo é suficientemente dolorosa. Mas quando submissões mudam cada uma das linhas em um arquivo, isso dificulta o trabalho de determinar quais dessas linhas foram modificadas de uma forma não trivial. Onde o bug foi realmente corrigido? Em qual linha estava o erro de sintaxe introduzido?

A solução para este problema é a propriedade svn:eol-style. Quando esta propriedade é definida com um valor válido, o Subversion a utiliza para determinar que tratamento especial realizar sobre o arquivo de modo que o estilo de término de linha do arquivo não fique alternando a cada submissão vinda de um sistema operacional diferente. Os valores válidos são:

No repositório Subversion, uma trava é um pedaço de metadados que concede acesso exclusivo para um usuário modificar um arquivo. Este usuário é chamado de proprietário da trava. Cada trava também tem um identificador único, tipicamente uma longa cadeia de caracteres, conhecida como o sinal de trava. O repositório gerencia as travas, basicamente manipulando sua criação, aplicação e remoção. Se qualquer transação de submissão tenta modificar ou excluir um arquivo travado (ou excluir um dos diretórios pais do arquivo), o repositório exigirá dois pedaços de informação—que o cliente executante da submissão esteja autenticado como o proprietário da trava, e que o sinal de trava tenha sido fornecido como parte do processo de submissão como um tipo de prova que o cliente conhece qual trava ele está usando.

Para demonstrar a criação de uma trava, vamos voltar ao nosso exemplo de múltiplos desenhistas gráficos trabalhando sobre os mesmos arquivos binários de imagem. Harry decidiu modificar uma imagem JPEG. Para prevenir que outras pessoas submetessem mudanças no arquivo enquanto ele está modificando-o (bem como alertando-os que ele está prestes a mudá-lo), ele trava o arquivo no repositório usando o comando svn lock.

$ svn lock banana.jpg -m "Editando arquivo para a liberação de amanhã."
'banana.jpg' locked by user 'harry'.
$

Existe uma série de novas coisas demonstradas no exemplo anterior. Primeiro, note que Harry passou a opção --message (-m) para o comando svn lock. Similar ao svn commit, o comando svn lock pode receber comentários (seja via --message (-m) ou --file (-F)) para descrever a razão do travamento do arquivo. Ao contrário do svn commit, entretanto, o svn lock não exigirá uma mensagem executando seu editor de texto preferido. Os comentários de trava são opcionais, mas ainda recomendados para ajudar na comunicação.

Em segundo lugar, a trava foi bem sucedida. Isto significa que o arquivo não estava travado, e que Harry tinha a mais recente versão do arquivo. Se o arquivo da cópia de trabalho de Harry estivesse desatualizado, o repositório teria rejeitado a requisição, forçando Harry a executar svn update e tentar o comando de travamento novamente. O comando de travamento também teria falhado se o arquivo já estivesse travado por outro usuário.

Como você pode ver, o comando svn lock imprime a confirmação do sucesso no travamento. A partir deste ponto, o fato de que o arquivo está travado torna-se aparente na saída dos relatórios dos subcomandos svn status e svn info.

$ svn status
     K banana.jpg

$ svn info banana.jpg
Path: banana.jpg
Name: banana.jpg
URL: http://svn.example.com/repos/project/banana.jpg
Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec
Revision: 2198
Node Kind: file
Schedule: normal
Last Changed Author: frank
Last Changed Rev: 1950
Last Changed Date: 2006-03-15 12:43:04 -0600 (Wed, 15 Mar 2006)
Text Last Updated: 2006-06-08 19:23:07 -0500 (Thu, 08 Jun 2006)
Properties Last Updated: 2006-06-08 19:23:07 -0500 (Thu, 08 Jun 2006)
Checksum: 3b110d3b10638f5d1f4fe0f436a5a2a5
Lock Token: opaquelocktoken:0c0f600b-88f9-0310-9e48-355b44d4a58e
Lock Owner: harry
Lock Created: 2006-06-14 17:20:31 -0500 (Wed, 14 Jun 2006)
Lock Comment (1 line):
Editando arquivo para a liberação de amanhã.

$

O comando svn info, o qual não consulta o repositório quando executa sobre caminhos de uma cópia de trabalho, pode mostrar o sinal de trava e revela um importante fato sobre o sinal de trava—que eles são colocados em cache na cópia de trabalho. A presença do sinal de trava é crítica. Ele dá à cópia de trabalho a autorização para fazer uso da trava mais tarde. Além disso, o comando svn status mostra um K próximo ao arquivo (abreviação para locKed), indicando que o sinal de trava está presente.

Agora que Harry tem o arquivo banana.jpg travado, Sally não poderá modificar ou excluir esse arquivo:

$ svn delete banana.jpg
D         banana.jpg
$ svn commit -m "Excluir arquivo sem uso."
Deleting       banana.jpg
svn: Commit failed (details follow):
svn: DELETE of
'/repos/project/!svn/wrk/64bad3a9-96f9-0310-818a-df4224ddc35d/banana.jpg':
423 Locked (http://svn.example.com)
$

Porém Harry, após retocar a tonalidade amarela da banana, é capaz de submeter suas mudanças no arquivo. Isso porque ele se autenticou como o proprietário da trava, e também porque sua cópia 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 após a submissão ser concluída, svn status mostra que o sinal de trava não está mais presente na cópia de trabalho. Este é o comportamento padrão de svn commit—ele procura na cópia de trabalho (ou lista de alvos, se você fornecer uma lista desse tipo) por modificações locais, e envia todos os sinalizadores de trava encontrados durante esta caminhada para o servidor como parte da transação de submissão. Após a submissão concluir com sucesso, todas as travas do repositório que forem mencionadas são liberadas—até mesmo em arquivos que não foram submetidos. Isto é utilizado para que os usuários não sejam desleixados com os travamentos, ou segurem travas por muito tempo. Se Harry trava de forma desorganizada trinta arquivos em um diretório nomeado images porque não 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 opção --no-unlock ao comando svn commit. Isso tem melhor uso para aqueles casos quando você quer submeter mudanças, mas ainda planeja fazer mais mudanças e, portanto, precisa conservar as travas existentes. Você também pode fazer este seu comportamento padrão configurando a opção no-unlock do seu ambiente de execução (veja “Área de Configuração do Tempo de Execução”).

Evidentemente, travar um arquivo não o obriga a submeter uma mudança para ele. A trava pode ser liberada a qualquer tempo com um simples comando svn unlock:

$ svn unlock banana.c
'banana.c' unlocked.

Quando uma submissão falha devido a um trava que outra pessoa criou, é bastante fácil ver os detalhes sobre ela. A forma mais fácil 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 não somente que sua cópia de foo.h está desatualizada, mas que um dos dois arquivos modificados que ela planeja submeter está travado no repositório. O símbolo O corresponde a “Other”, significando que existe uma trava sobre o arquivo, e foi criada por outra pessoa. Se ela vier a tentar uma submissão, 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:

$ svn info http://svn.example.com/repos/project/raisin.jpg
Path: raisin.jpg
Name: raisin.jpg
URL: http://svn.example.com/repos/project/raisin.jpg
Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec
Revision: 105
Node Kind: file
Last Changed Author: sally
Last Changed Rev: 32
Last Changed Date: 2006-01-25 12:43:04 -0600 (Sun, 25 Jan 2006)
Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
Lock Owner: harry
Lock Created: 2006-02-16 13:29:18 -0500 (Thu, 16 Feb 2006)
Lock Comment (1 line):
Necessidade de fazer um ajuste rápido nesta imagem.
$

Assim como svn info pode ser usado para examinar objetos na cópia de trabalho, ele também pode ser usado para examinar objetos no repositório. Se o argumento principal para svn info é um caminho de uma cópia de trabalho, então todas informações em cache da cópia de trabalho são exibidas; qualquer menção a uma trava significa que a cópia de trabalho está mantendo um sinal de trava (se um arquivo é travado por outro usuário ou em outra cópia de trabalho, svn info em um caminho de cópia de trabalho não mostrará qualquer informação da trava). Se o argumento principal para svn info é uma URL, então as informações refletem a mais recente versão de um objeto no repositório, e qualquer menção 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 rápido”. 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 indisponível, ela poderá tentar quebrar a trava a força ou solicitar um administrador para o fazer.

Uma trava no repositório não é algo sagrado—na configuração padrão do Subversion, as travas podem ser liberadas não somente pela pessoa que a criou, mas por qualquer outra também. Quando alguém que são seja o criador original da trava a destrói, referimos a isto como quebrar a trava.

Para o administrador é simples quebrar travas. Os programas svnlook e svnadmin possuem a habilidade de mostrar e remover travas diretamente do repositório. (Para mais informações sobre estas ferramentas, veja “Um Kit de Ferramentas do Administrador”.)

$ svnadmin lslocks /usr/local/svn/repos
Path: /project2/images/banana.jpg
UUID Token: opaquelocktoken:c32b4d88-e8fb-2310-abb3-153ff1236923
Owner: frank
Created: 2006-06-15 13:29:18 -0500 (Thu, 15 Jun 2006)
Expires: 
Comment (1 line):
Ainda melhorando a cor amarela.

Path: /project/raisin.jpg
UUID Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
Owner: harry
Created: 2006-02-16 13:29:18 -0500 (Thu, 16 Feb 2006)
Expires: 
Comment (1 line):
Necessidade de fazer um ajuste rápido nesta imagem.

$ svnadmin rmlocks /usr/local/svn/repos /project/raisin.jpg
Removed lock on '/project/raisin.jpg'.
$

Uma opção mais interessante é permitir que usuários quebrem as travas de outros através da rede. Para fazer isto, Sally simplesmente precisa passar a opção --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 cópia de trabalho do arquivo, e nenhum sinal de trava estava presente. Para remover a trava diretamente do repositório, ela precisa passar uma URL para svn unlock. Sua primeira tentativa para destravar a URL falhou, porque ela não pode autenticar como a proprietária da trava (nem ela possui o sinal de trava). Mas quando ela passa --force, os requisitos de autenticação e autorização são ignorados, e a trava remota agora está quebrada.

Simplesmente quebrar uma trava pode não ser suficiente. No exemplo atual, Sally pode não somente querer quebrar a trava esquecida a longo prazo por Harry, mas também retravar o arquivo para seu próprio uso. Ela pode realizar isto executando svn unlock --force e então 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 atômico. Para fazer isto, Sally passa a opção --force para svn lock:

$ svn lock raisin.jpg
svn: Lock request failed: 423 Locked (http://svn.example.com)
$ svn lock --force raisin.jpg
'raisin.jpg' locked by user 'sally'.
$

Em qualquer caso, se a trava é quebrada ou roubada, Harry terá uma surpresa. A cópia de trabalho de Harry ainda contém o sinal original da trava, mas esta trava não existe mais. O sinal da trava está agora extinto. A trava representada pelo sinal de trava, ou terá sido quebrada (não está mais no repositório), ou roubada (substituída por uma trava diferente). De qualquer forma, Harry pode ver isto pedindo para svn status verificar o repositório:

$ svn status
     K raisin.jpg
$ svn status -u
     B         32   raisin.jpg
$ svn update
  B  raisin.jpg
$ svn status
$

Se a trava foi quebrada no repositório, então svn status --show-updates exibe um símbolo B (Broken) próximo ao arquivo. Se uma nova trava existe no lugar da anterior, então um símbolo T (sTolen) é mostrado. Finalmente, svn update relata os sinais de trava existentes e os remove da cópia de trabalho.

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 submissões de um arquivo. Mas o que aconteceu com o maior problema da prevenção de perda de tempo?

Por exemplo, suponha que Harry trave um arquivo de imagem e, em seguida, inicie sua edição. Entretanto, a milhas de distância, Sally deseja fazer a mesma coisa. Ela não pensa em executar svn status --show-updates, portanto ele não tem idéia de que Harry já tenha travado o arquivo. Ela gasta horas editando o arquivo, e quando ela tenta submeter sua mudança, ela descobre que ou o arquivo está travado ou que ela está desatualizada. Indiferente disso, suas alterações não são mescláveis com as de Harry. Uma destas duas pessoas tem que jogar fora seu trabalho, e um monte de tempo foi perdido.

A solução do Subversion para este problema é oferecer um mecanismo para avisar aos usuários que um arquivo deve ser travado antes de iniciar sua edição. O mecanismo é uma propriedade especial, svn:needs-lock. Se esta propriedade está anexada a um arquivo (indiferente de seu valor, o qual é irrelevante), então o Subversion tentará utilizar permissões a nível de sistema de arquivo para tornar o arquivo somente leitura—exceto, claro, o usuário 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, então, é que se o arquivo de imagem tem esta propriedade anexada, então Sally iria verificar imediatamente que alguma coisa está estranho quando ela abrir o arquivo para edição: muitas aplicações avisam os usuários imediatamente quando um arquivo somente leitura é aberto para edição, e quase todos impedem que alterações sejam salvas no arquivo. Isto lembra ela para travar o arquivo antes de editá-lo, e então ela descobre a trava já existente:

$ /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 próximas duas horas.
$

Note que esta propriedade é um instrumento de comunicação que trabalha independentemente do sistema de travamento. Em outras palavras, qualquer arquivo pode ser travado, estando esta propriedade presente ou não. E reciprocamente, a presença desta propriedade não faz com que o repositório requeira uma trava quando for submeter as mudanças.

Infelizmente, o sistema não é perfeito. É possível que mesmo quando um arquivo possua a propriedade, a advertência de somente leitura nem sempre funcione. Algumas vezes as aplicações comportam-se mal e “adulteram” o arquivo somente leitura, silenciosamente permitindo aos usuários editar e salvar o arquivo de qualquer forma. Não há muito que o Subversion possa fazer nesta situação—de qualquer maneira, simplesmente não há substituição para uma boa comunicação entre as pessoas. ^[17]

O cliente Subversion passa a maior parte de seu tempo gerenciando cópias de trabalho. Quando ele precisa de informações de um repositório remoto, entretanto, ele efetua uma solicitação de rede, e o servidor responde com uma resposta apropriada. Os detalhes do protocolo de rede estão escondidos do usuário—o cliente tenta acessar uma URL, e dependendo do esquema na URL, um protocolo específico é usado para comunicar com o servidor (veja URLs do Repositório).

Quando o processo servidor recebe uma requisição do cliente, ele quase sempre solicita que o cliente se identifique. Ele lança um desafio de autenticação para o cliente, e o cliente responde enviando de volta suas credenciais ao servidor. Quando a autenticação for concluída, o servidor responde com a informação 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 requisição. No Subversion, o servidor é que “pega” as credenciais desafiando o cliente no momento adequado, ao invés de o cliente ter de “inserí-las”. Isto torna certas operações mais elegantes. Por exemplo, se um servidor estiver configurado para permitir globalmente que qualquer um leia o repositório, então o servidor nunca vai emitir um desafio de autenticação quando o cliente executar um svn checkout.

Se uma dada requisição de rede feita pelo cliente resultar em uma nova revisão sendo criada no repositório (p.ex. svn commit), então o Subversion usa o nome de usuário autenticado associado a essas requisições como autor da revisão. Isto é, o nome do usuário autenticado é armazenado como o valor da propriedade svn:author na nova revisão (veja “Propriedades do Subversion”). Se o cliente não estava autenticado (em outras palavras, se o servidor nunca lançara um desafio de autenticação), então a propriedade svn:author será vazia.

Muitos servidores estão configurados para exigir autenticação em todas solicitações. Isto seria um grande incomodo para os usuários, se eles forem forçados a digitar suas senhas várias vezes. Felizmente, o cliente Subversion possui um remédio para isto—um sistema embutido para armazenamento das credenciais de autenticação em disco. Por padrão, se o cliente de linha de comando responde com sucesso a um desafio de autenticação do servidor, ele salva as credenciais na área privada de configuração de execução do usuário (~/.subversion/auth/ em sistemas baseado em Unix ou %APPDATA%/Subversion/auth/ em Windows; veja “Área de Configuração do Tempo de Execução” para maiores detalhes sobre o sistema de configuração de execução). As credenciais aprovadas são armazenadas em disco, chaveadas com uma combinação do nome do servidor, porta, e o domínio de autenticação.

Quando o cliente recebe um desafio de autenticação, ele primeiro procura pelas credenciais apropriadas na cache em disco do usuário. Se aparentemente nenhuma credencial apta está presente, ou se em último caso a credencial armazenada falhar ao autenticar, então o cliente, por padrão, voltará a solicitar ao usuário pela informação necessária.

O leitor consciente de segurança suspeitará imediatamente que há motivo para preocupação aqui. “Armazenar senhas em disco? Isto é terrível! Você nunca deve fazer isto!”

Os desenvolvedores do Subversion reconhecem a legitimidade de tais preocupações, e por esta razão o Subversion trabalha com os mecanismos disponíveis fornecidos pelo sistema e ambiente operacional para tentar minimizar o risco de vazamento destas informações. Aqui está uma descrição de que isto significa para os usuários nas plataformas mais comuns:

Claro que, para o paranóico de verdade, nenhum destes mecanismos satisfaz o teste de perfeição. Então, para aqueles dispostos a sacrificar a conveniência pela segurança extrema, o Subversion oferece vários meios de desabilitar seu sistema de armazenamento de credenciais completamente.

Para desabilitar o armazenamento para um único comando, passe a opção --no-auth-cache:

$ svn commit -F log_msg.txt --no-auth-cache
Authentication realm: <svn://host.example.com:3690> example realm
Username:  joe
Password for 'joe':

Adding         newfile
Transmitting file data .
Committed revision 2324.

# password was not cached, so a second commit still prompts us

$ svn delete newfile
$ svn commit -F new_msg.txt
Authentication realm: <svn://host.example.com:3690> example realm
Username:  joe
…

Ou, se você quiser desabilitar o armazenamento de credencial permanentemente, você pode editar o arquivo config em sua área de configuração do ambiente de execução, e defina a opção store-auth-creds para no. Isso evitará o armazenamento de credenciais usadas em qualquer interação que você efetuar com o Subversion no computador afetado. Isso pode ser estendido a todos os usuários no computador, também, ao modificar a área de configuração do sistema como um todo (descrito em “Estrutura da Área de Configuração”).

[auth]
store-auth-creds = no

Algumas vezes os usuários poderão querer remover credenciais específicas da cache em disco. Para fazer isso, você precisa ir até a área auth/ e excluir manualmente o arquivo de cache apropriado. As credenciais são armazenadas em arquivos individuais; se você olhar dentro de cada arquivo, você verá chaves e valores. A chave svn:realmstring descreve o domínio do servidor específico 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

Assim que você localizar o respectivo arquivo de cache, apenas o exclua.

Uma última palavra sobre o comportamento de autenticação do svn, especificamente em relação às opções --username e --password. Muitos dos subcomandos do cliente aceitam estas opções, mas é importante entender que o uso dessas opções não envia as credenciais automaticamente ao servidor. Conforme discutido anteriormente, o servidor “puxa” as credenciais do cliente quando julgar necessário; o cliente não pode “empurrá”-las à vontade. Se um nome de usuário e/ou senha são passados como opções, elas somente serão apresentadas ao servidor se o servidor solicitar elas. ^[21] Estas opções são normalmente utilizadas para autenticar como um usuário diferente daquele que o Subversion teria optado por padrão (como seu nome de usuário 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 autenticação.

Se o cliente autentica-se com sucesso por qualquer dos métodos listados acima, ele tentará armazenar as credenciais em disco (a menos que o usuário tenha desabilitado este comportamento, como mencionado anteriormente).

Criar um ramo é realmente simples— você faz uma cópia do projeto no repositório usando o comando svn copy. O Subversion copia não somente arquivos mas também diretórios completos. Neste caso, você quer fazer a cópia do diretório /calc/trunk. Onde deve ficar a nova cópia? Onde você quiser— isso depende da "política" do projeto. Digamos que sua equipe tem a política de criar novos ramos na área /calc/branches do repositório, e você quer chamar o seu ramo de my-calc-branch. Você vai querer criar um novo diretório, /calc/branches/my-calc-branch, que inicia sua vida como cópia de /calc/trunk.

Há duas maneiras diferentes de fazer uma cópia. Vamos mostrar primeiro a maneira complicada, apenas para deixar claro o conceito. Para começar, faça um checkout do diretório raiz do projeto, /calc:

$ svn checkout http://svn.example.com/repos/calc bigwc
A  bigwc/trunk/
A  bigwc/trunk/Makefile
A  bigwc/trunk/integer.c
A  bigwc/trunk/button.c
A  bigwc/branches/
Checked out revision 340.

Agora para fazer uma cópia basta passar dois caminhos de cópia 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 cópia recursiva do diretório trunk para um novo diretório de trabalho, branches/my-calc-branch. Como você pode ver pelo comando svn status, o novo diretório está agendado para ser adicionado ao repositório. Note também o sinal “+” próximo à letra A. Isso indica o item adicionado é uma cópia de algo e não um item novo. Quando você realizar o Commit das modificações, o Subversion vai criar o diretório /calc/branches/my-calc-branch no repositório copiando /calc/trunk, ao invés de reenviar todos os dados da cópia de trabalho pela rede:

$ svn commit -m "Criando um ramo do diretório /calc/trunk."
Adding         branches/my-calc-branch
Committed revision 341.

E aqui está o método mais fácil de criar um ramo, o qual nós deveríamos ter lhe mostrado desde o início: o comando svn copy é capaz de copiar diretamente duas URLs.

$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/branches/my-calc-branch \
      -m "Criando um ramo do diretório /calc/trunk."

Committed revision 341.

Do ponto de vista do diretório, não há diferença entre estes dois métodos. Ambos os processos criam um novo diretório na revisão 341, e o novo diretório é uma cópia de /calc/trunk. Isso é mostrado em Figura 4.3, “Repositório com uma nova cópia”. Note que o segundo método, entretanto, faz um commit imediato em tempo constante. ^[22] Este é um procedimento mais fácil, uma vez que você não precisa fazer o checkout de uma grande parte do repositório. Na verdade, para usar esta técnica você não precisa se quer ter uma cópia de trabalho. Esta é a maneira que a maioria dos usuários criam ramos.

Figura 4.3. Repositório com uma nova cópia

Agora que você criou um ramo do projeto, você pode fazer um Checkout para uma nova cópia de trabalho e usá-la.

$ svn checkout http://svn.example.com/repos/calc/branches/my-calc-branch
A  my-calc-branch/Makefile
A  my-calc-branch/integer.c
A  my-calc-branch/button.c
Checked out revision 341.

Não tem nada de especial nessa cópia de trabalho; ela simplesmente aponta para um diretório diferente no repositório. Entretanto, quando você faz o commit de modificações, essas não ficarão visíveis para Sally quando ela fizer Update, porque a cópia de trabalho dela aponta para /calc/trunk. (Leia “Atravessando Ramos” logo à frente neste capítulo: o comando svn switch é uma forma alternativa de se criar uma cópia 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, “Ramificação do histórico de um arquivo”, afetando integer.c.

Figura 4.4. Ramificação do histórico de um arquivo

As coisas ficam interessantes quando você olha o histórico das alterações feitas na sua cópia de integer.c:

$ pwd
/home/user/my-calc-branch

$ svn log -v integer.c
------------------------------------------------------------------------
r343 | user | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
   M /calc/branches/my-calc-branch/integer.c

* integer.c:  frozzled the wazjub.

------------------------------------------------------------------------
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)

Creating a private branch of /calc/trunk.

------------------------------------------------------------------------
r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  changed a docstring.

------------------------------------------------------------------------
r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  adding this file to the project.

------------------------------------------------------------------------

Note que o Subversion está traçando o histórico 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 histórico, 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 cópia do arquivo:

$ pwd
/home/sally/calc

$ svn log -v integer.c
------------------------------------------------------------------------
r344 | sally | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  fix a bunch of spelling errors.

------------------------------------------------------------------------
r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  changed a docstring.

------------------------------------------------------------------------
r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  adding this file to the project.

------------------------------------------------------------------------

Sally vê suas próprias modificações na revisão 344, e não as modificações que você fez na revisão 343. Até onde o Subversion sabe, esses dois commits afetaram arquivos diferentes em locais distintos no repositório. Entretanto o Subversion mostra que os dois arquivos têm um histórico em comum. Antes de ser feita a cópia/ramo na revisão 341, eles eram o mesmo arquivo. É por isso que você e Sally podem ver as alterações feitas nas revisões 303 e 98.

Há duas lições importantes que você deve se lembrar desta seção. Primeiro, o Subversion não tem um conceito interno de ramos—ele apenas sabe fazer cópias. Quando você copia um diretório, o diretório resultante somente é um “ramo” porque você atribui esse significado a ele. Você pode pensar de forma diferente sobre esse diretório, ou tratá-lo de forma diferente, mas para o Subversion é apenas um diretório comum que carrega uma informação extra de histórico. Segundo, devido a este mecanismo de cópia, os ramos no Subversion existem como diretórios normais do sistema de arquivos no repositório. Isso é diferente de outros sistemas de controle de versão, onde ramos são criados ao adicionar “rótulos” extra-dimensionais aos arquivos.

Na seção anterior, nos comentamos que tanto você quanto Sally fizeram alterações em integer.c em ramos distintos.Se você olhar a mensagem de log de Sally na revisão 344, você verá que ela corrigiu alguns erros de escrita. Sem duvida alguma, a sua cópia deste arquivo tem os mesmo erros de escrita. É provável que suas futuras modificações a este arquivo vão afetar as mesmas áreas onde foram feitas as correções de escrita, então você tem grandes chances de ter vários conflitos quando for fundir o seu ramo, eventualmente. Portanto, é melhor receber as modificações de Sally agora, antes de você começar a trabalhar de forma massiva nessas áreas.

É hora de usar o comando svn merge. Esse comando é um primo muito próximo do comando svn diff (que você viu em Capítulo 2, Uso Básico). Os dois comando comparam dois objetos no repositório e mostram as diferenças. Por exemplo, você pode pedir com o comando svn diff para ver com exatidão as mudanças feitas por Sally na revisão 344:

$ svn diff -c 344 http://svn.example.com/repos/calc/trunk

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 */

     info->extra_header = (unsigned char *) my_malloc(total);
     fread(info->extra_header, total, 1, gzfile);
@@ -241,7 +241,7 @@
      Store the offset with ftell() ! */

   if ((info->data_offset = ftell(gzfile))== -1) {
-    printf("error: ftell() retturned -1.\n");
+    printf("error: ftell() returned -1.\n");
     exit(1);
   }

@@ -249,7 +249,7 @@
   printf("I believe start of compressed data is %u\n", info->data_offset);
   #endif

-  /* Set postion eight bytes from the end of the file. */
+  /* Set position eight bytes from the end of the file. */

   if (fseek(gzfile, -8, SEEK_END)) {
     printf("error: fseek() returned non-zero\n");

O comando svn merge é quase que o mesmo. Ao invés de imprimir as diferenças no terminal, ele as aplica diretamente à cópia de trabalho classificando como local modifications:

$ svn merge -c 344 http://svn.example.com/repos/calc/trunk
U  integer.c

$ svn status
M  integer.c

A saída do comando svn merge mostra a sua cópia de integer.c sofreu uma correção. Agora ele contém as modificações feitas por Sally— essas modificações foram “copiadas” do tronco do repositório para a cópia de trabalho do seu ramo privado, e agora existe como uma modificação local. A esta altura, depende de você revisar essa modificação local e ter certeza de funciona.

Em outra simulação, é possível que as coisas não tenham ocorrido tão bem assim, e o arquivo integer.c tenha entrado em estado de conflito. Pode ser que você precise resolver o conflito usando procedimentos padrão (veja Capítulo 2, Uso Básico), ou se você decidir que fazer a fusão dos arquivos tenha sido uma má idéia, desista e rode o comando svn revert para retirar as modificações locais.

Partindo do pressuposto que você revisou as modificações do processo de fusão , então você pode fazer o svn commit como de costume. A este ponto, a mudança foi fusionada ao seu ramo no repositório. Em tecnologias de controle de versão, esse ato de copiar mudanças entre ramos recebe o nome de portar mudanças.

Quando você fizer o commit das modificações locais, não esqueça de colocar na mensagem de log que você está portando uma modificação especifica de um ramo para outro.Por exemplo:

$ svn commit -m "integer.c: ported r344 (spelling fixes) from trunk."
Sending        integer.c
Transmitting file data .
Committed revision 360.

Como você verá nas próximas seções, essa é uma “boa pratica” importantíssima a ser seguida.

$ svn diff -c 344 http://svn.example.com/repos/calc/trunk > patchfile
$ patch -p0  < patchfile
Patching file integer.c using Plan A...
Hunk #1 succeeded at 147.
Hunk #2 succeeded at 164.
Hunk #3 succeeded at 241.
Hunk #4 succeeded at 249.
done

Um aviso: ainda que o comando svn diff e o svn merge tem conceitos similares, eles apresentam sintaxe diferente em vários casos. Leia sobre isso em Capítulo 9, Referência Completa do Subversion para mais detalhes, ou peça ajuda ao comando svn help. Por exemplo, o comando svn merge precisa de uma cópia de trabalho com destino, isto é, um local onde aplicar as modificações. Se um destino não for especificado, ele assume que você está tentando uma dessas operações:

Se você esta fundindo um diretório e não especificou um destino, svn merge assume o primeiro caso acima e tenta aplicar as modificações no seu diretório atual. Se você está fundindo um arquivo, e este arquivo (ou arquivo de mesmo nome) existe no diretório atual, o svn merge assume o segundo caso, e tenta aplicar as modificações no arquivo local de mesmo nome.

Se você quer que as modificações seja aplicadas em outro local, você vai precisar avisar. Por exemplo, se você está no diretório pai de sua cópia de trabalho, você vai precisar especificar o diretório de destino a receber as modificações:

$ svn merge -c 344 http://svn.example.com/repos/calc/trunk my-calc-branch
U   my-calc-branch/integer.c

Agora você viu um exemplo do comando svn merge, e você está prestes a ver vários outros. Se você está se sentindo confuso sobre como a fusão funciona, saiba que você não está sozinho. Vários usuários ( especial os novos em controle de versão) ficam perplexos com a sintaxe do comando, e sobre como e quando deve ser usado. Mas não temas, esse comando é muito mais simples do que você imagina! Existe uma técnica muito simples para entender exatamente o comportamento do comando svn merge.

O principal motivo de confusão é o nome do comando. O termo “fundir” de alguma forma denota que se junta ramos, ou que existe uma mistura misteriosa de código ocorrendo. Este não é o caso. O nome mais apropriado para o comando deveria ter sido svn diff-and-apply , porque isso é o que acontece: duas árvores de repositório são comparadas, e a diferença é aplicada a uma cópia de trabalho.

O comando recebe três argumentos:

Uma vez especificados estes três argumentos, as duas árvores são comparadas, e o resultado das diferenças são aplicadas sobre a cópia de trabalho de destino, como modificações locais. Uma vez executado o comando, o resultado não é diferente do que se você tivesse editado manualmente os arquivos, ou rodados vários comandos svn add ou svn delete. Se você gostar do resultado você pode fazer o commit dele. Se você não gostar do resultado, você pode simplesmente reverter as mudanças com o comando svn revert.

A sintaxe do comando svn merge lhe permite especificar os três argumentos necessários de forma flexível. Veja aqui alguns exemplos:

$ svn merge http://svn.example.com/repos/branch1@150 \
            http://svn.example.com/repos/branch2@212 \
            my-working-copy

$ svn merge -r 100:200 http://svn.example.com/repos/trunk my-working-copy

$ svn merge -r 100:200 http://svn.example.com/repos/trunk

A primeira sintaxe usa explicitamente os três argumentos, nomeando cada árvore na forma URL@REV e nomeando a cópia de trabalho de destino. A segunda sintaxe pode ser usada como um atalho em situações onde você esteja comparando duas revisões distintas de uma mesma URL. A ultima sintaxe mostra como o argumento da cópia de trabalho de destino é opcional; se omitido, assume como padrão o diretório atual.

Para completar nosso exemplo de execução, vamos avançar no tempo. Suponha que vários dias tenham se passado, e que muitas alterações tenham acontecido tanto no tronco quanto em seu ramo particular. Suponha que você tenha terminado de trabalhar seu ramo particular; e que o recurso ou correção de bug tenha finalmente terminado, e que agora você quer mesclar todas as modificações de seu ramo de volta para o tronco principal para que os outros usufruam.

Então como usamos o svn merge neste cenário? Lembre-se de que este comando compara duas árvores, e aplica as diferenças em uma cópia de trabalho. Então para receber as modificações, você precisa ter uma cópia de trabalho do tronco. Vamos assumir que você ainda possua uma cópia original (completamente atualizada), ou que você recentemente tenha obtido uma nova cópia 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 cuidado—esta suposição está errada, e isso costuma confundir muito os novos usuários! Como o svn merge opera como o svn diff, comparar as últimas versões das árvores do tronco e do ramo não descreve apenas o conjunto de modificações que você fez em seu ramo. Tal comparação exibe muito mais mudanças: ele não apenas exibe o efeito das modificações de seu ramo, mas também todas as alterações de removação que nunca aconteceram em seu ramo.

Para expressar apenas as modificações 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 revisão 341. E o estado final de seu ramo é simplesmente uma dada forma de uso da revisão HEAD. Isso significa que você deve comparar as revisões 341 e HEAD do seu diretório branch, e aplicar estas diferenças na cópia de trabalho de trunk.

$ svn log -v --stop-on-copy \
          http://svn.example.com/repos/calc/branches/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)

$

E então, aqui está o último procedimento para mesclagem:

$ cd calc/trunk
$ svn update
At revision 405.

$ svn merge -r 341:405 http://svn.example.com/repos/calc/branches/my-calc-branch
U   integer.c
U   button.c
U   Makefile

$ svn status
M   integer.c
M   button.c
M   Makefile

# ...examine os diffs, compilações, testes, etc...

$ svn commit -m "Merged my-calc-branch changes r341:405 into the trunk."
Sending        integer.c
Sending        button.c
Sending        Makefile
Transmitting file data ...
Committed revision 406.

Novamente, perceba que a mensagem de log do commit menciona bem especificamente o intervalo de modificações que foram mescladas para o tronco. Sempre se lembre de fazer isso, pois é uma informação crítica 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 correção de bug. A revisão HEAD do repositório 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 práticas sobre Fusão”, você não quer mesclar as modificações 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 são 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

Merged my-calc-branch changes r341:405 into the trunk.
------------------------------------------------------------------------
…

Aha! Como todas as modificações no ramo que aconteceram entre as revisões 341 e 408 já foram previamente mescladas para o tronco gerando a revisão 406, você agora sabe que deve mesclar apenas as alterações feitas depois disso—comparando as revisões HEAD.

$ cd calc/trunk
$ svn update
At revision 480.

# Percebemos que atualmente HEAD está em 480, então usamos isso para fazer a mesclagem:

$ svn merge -r 406:480 http://svn.example.com/repos/calc/branches/my-calc-branch
U   integer.c
U   button.c
U   Makefile

$ svn commit -m "Merged my-calc-branch changes r406:480 into the trunk."
Sending        integer.c
Sending        button.c
Sending        Makefile
Transmitting file data ...
Committed revision 481.

Agora o tronco contém a segunda leva completa de modificações 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.

Outro uso comum do svn merge é para desfazer uma modificação que já foi submetida ao repositório. Suponha que você esteja trabalhando alegremente na cópia de trabalho de /calc/trunk, e você descobre que a modificação que havia sido feita na revisão 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 modificação em cópia de trabalho, e então submeter a modificação local para o repositório. Tudo o que você precisa fazer é especificar uma diferença reversa. (Você pode fazer isto especificando --revision 303:302, ou também o equivalente --change -303.)

$ svn merge -c -303 http://svn.example.com/repos/calc/trunk
U  integer.c

$ svn status
M  integer.c

$ svn diff
…
# verify that the change is removed
…

$ svn commit -m "Undoing change committed in r303."
Sending        integer.c
Transmitting file data .
Committed revision 350.

Uma maneira de pensar o repositório é como um grupo específico de modificações (alguns sistemas de controle de versão chamam a isto de conjuntos de mudanças ou changesets). Usando a opção -r, você pode solicitar que o svn merge aplique um conjunto de mudanças, ou um intervalo inteiro de conjuntos de mudanças, à sua cópia de trabalho. Em nosso caso em questão, como queremos desfazer uma mudança, estamos solicitando que o svn merge aplique o conjunto de mudanças #303 retrospectivamente de volta à nossa cópia de trabalho.

Tenha em mente que voltar uma mudança como neste caso é uma operação de svn merge como outra qualquer, então você deveria usar svn status e svn diff para confirmar que seu trabalho esteja no estado em que você quer que esteja, e então usar svn commit para enviar a versão final para o repositório. Depois de submetido, este conjunto de mudanças em particular não estará mais refletido na revisão HEAD.

Novamente, você pode estar pensando: bem, isto não desfaz exatamente a submissão, não é? A modificação ainda existe na revisão 303. Se alguém obtiver uma versão do projeto calc entre as revisões 303 e 349, elas ainda conterão a tal modificação incorreta, certo?

Sim, isto é verdade. Quando nós falamos sobre “remover” uma modificação, estávamos realmente falando sobre removê-la da revisão HEAD. A modificação original ainda existirá no histórico do repositório. Na maioria das situações, isto é o suficiente. Afinal, a maioria das pessoas estão apenas interessadas em rastrear a revisão HEAD de um projeto. Porém, há alguns casos especiais onde você realmente pode querer destruir todas as evidências da submissão errônea. (Talvez alguém submetido acidentalmente um documento confidencial.) Isto não é tão fácil de se fazer, pois o Subversion foi desenvolvido deliberadamente para nunca perder informação. As revisões são árvores imutáveis as quais são construídas umas a partir das outras. Remover uma revisão do histórico deveria causar um efeito dominó, criando o caos em todas as revisões subsequentes e possivelmente invalidando todas as cópias de trabalho. ^[24]

O grande ponto sobre sistemas de controle de versão é que a informação nunca é perdida. Mesmo quando você exclui um arquivo ou diretório, ele pode até não estar mais presente na revisão HEAD, mas o objeto ainda existe nas revisões mais antigas. Uma das questões mais comuns que novos usuários se perguntam é, “Como eu faço para obter meu arquivo ou diretório antigo de volta?”.

O primeiro passo é definir exatamente qual ítem você está tentando ressucitar. Aqui há uma metáfora útil: você pode pensar como se cada objeto no repositório existisse em uma espécie de sistema bi-dimensional. A primeira coordenada é uma determinada árvore de revisão, e a segunda coordenada é o caminho dentro daquela árvore. Assim cada versão de seu arquivo ou diretório pode ser definida por um dado par de coordenadas. (Lembre-se da sintaxe de “revisões marcadoras”—foo.c@224—apresentada em “Revisões Marcadoras e Revisões Operativas”.)

Primeiramente, você pode precisar usar um svn log para descobrir o par de coordenadas exato que você quer ressucitar. Uma boa estratégia é executar svn log --verbose em um diretório onde seu item excluído costumava estar. A opção --verbose (-v) exibe uma lista de todos os itens que mudaram em cada revisão; tudo que você precisa fazer é encontrar a revisão na qual você excluir o arquivo ou diretório. Você pode fazer isto visualmente, ou usando outra ferramenta para examinar a saída 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

Added fast fourier transform functions to integer.c.
Removed real.c because code now in double.c.
…

No exemplo, estamos assumindo que você está procurando um arquivo excluído chamado real.c. Olhando os logs de um diretório-pai, você percebeu que este arquivo foi excluído na revisão 808. Portanto, a última versão do arquivo existia na revisão imediatamente anterior a essa. Conclusão: você quer ressucitar o caminho /calc/trunk/real.c a partir da revisão 807.

Esta foi a parte difícil—a pesquisa. Agora que você sabe o que você quer restaurar, você tem duas diferentes escolhas.

Uma opção é usar svn merge para aplicar a revisão 808 “ao contrário”. (Nós já falamos sobre como desfazer modificações, veja “Desfazendo Alterações”.) Isto teria o efeito de re-adicionar o arquivo real.c como uma modificação local. O arquivo deveria ser agendado para adição, e após ser submetido, o arquivo deve estar novamente presente na revisão HEAD.

Neste exemplo em particular, no entanto, esta provavelmente não é a melhor estratégia. A aplicação reversa da revisão 808 não apenas agenda real.c para adição, mas a mensagem de log indica que ele também deve desfazer certas alterações em integer.c, o que você não quer. Certamente, você poderia fazer uma mesclagem reversa da revisão 808 e então executar um svn revert nas modificações locais em integer.c, mas esta técnica não é bem escalável. E se tivéssemos 90 arquivos modificados na revisão 808?

Uma segunda, e mais precisa estratégia envolve não usar o svn merge, mas o comando svn copy em seu lugar. Simplesmente copie a revisão exata e o caminho como “par de coordenadas” do repositório para sua cópia de trabalho:

$ svn copy -r 807 \
           http://svn.example.com/repos/calc/trunk/real.c ./real.c

$ svn status
A  +   real.c

$ svn commit -m "Resurrected real.c from revision 807, /calc/trunk/real.c."
Adding         real.c
Transmitting file data .
Committed revision 1390.

O sinal de mais na saída do comando status indica que o item não está meramente agendado para adição, mas agendado para adição “com histórico”. O Subversion lembra de onde ele foi copiado. No futuro, executar svn log neste arquivo irá percorrer até o arquivo ressucitado e através do histórico que ele tinha antes da revisão 807. Em outras palavras, este novo real.c não é realmente novo; é um descendente direto do arquivo original que fora excluído.

Apesar de nosso exemplo nos mostrar uma ressurreição de arquivo, veja que estas mesmas técnicas funcionam muito bem também para ressucitar diretórios excluídos.

Controle de versão é muito usado para desenvolvimento de software, então aqui está uma rápida mostra de dois dos padrões mais comuns de ramificação/fusão usados por equipes de programadores. Se você não estiver usando o Subversion para desenvolvimento de software, fique à vontade para pular esta seção. Mas se você for um desenvolvedor de software usando controle de versão pela primeira vez, preste bastante atenção, já que estes padrões são frequentemente considerados como melhores práticas por pessoas mais experientes. Estes procedimentos não são específicos para o Subversion; sendo aplicáveis a qualquer sistema de controle de versão. Além do que pode ajudar ver tais padrões aplicados ao ambiente do Subversion.

$ cd trunk-working-copy

$ svn update
At revision 1910.

$ svn merge http://svn.example.com/repos/calc/trunk@1910 \
            http://svn.example.com/repos/calc/branches/mybranch@1910
U  real.c
U  integer.c
A  newdirectory
A  newdirectory/newfile
…

Mais uma vez, snv copy vem para nos socorrer. Se você quer criar uma foto do /calc/trunk exatamente como ele está na revisão HEAD, fazendo uma copia dela:

$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/tags/release-1.0 \
      -m "Rótulando a versão 1.0 do projeto 'calc'."

Committed revision 351.

Este exemplo assume que o diretório /calc/tags já existe. (Se ele não existir, você pode criá-lo usando svn mkdir.) Depois da copia completar, o novo diretório versão-1.0 será para sempre uma foto de como o projeto estava na revisão HEAD no momento que a copia foi feita. Claro que você pode querer mais precisão em saber qual revisão a copia foi feita, em caso de alguém ter feito commit no projeto quando você não estava vendo. Então se você sabe que a revisão 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: não é essa criação do rótulo o mesmo procedimento para criar um ramo? Sim, de fato, é. No Subversion, não há diferença entre um rótulo e um ramo. Assim como com ramos, a única razão uma cópia é um “rótulo” é porque humanos decidiram tratar isso desse jeito: desde que ninguém nunca faça commit para esse diretório, ele permanecerá para sempre uma foto. Se as pessoas começarem a fazer commit para ele, ele se transoforma num ramo.

Se você está administrando um repositório, existe duas maneiras para gerenciar rótulos. A primeira é “não toque”: como uma política do projeto, decida onde os rótulos vão morar, e garanta que todos os usuários saibam como tratar os diretórios que eles vão copiar para lá. (Isso quer dizer, garanta que eles saibam que não devem fazer neles.) A segunda é mais paranóica: você pode usar um dos scripts de controle de acesso providos com o Subversion para previnir que alguém faça algo além de apenas criar novas copias na área de rótulos (Veja Capítulo 6, Configuração do Servidor.) A maneira paranoica, entrentanto, não é necessária. Se algum usuário acidentalmente fizer commit de alguam mudança para o diretório de rótulo, você pode simplesmente desfazer a mudança como discutido na revisção anterior. É um controle de versão apesar de tudo.

Algumas vezes você que sua “foto” seja mais complicada que um simples diretório de uma única revisão.

Por exemplo, pense que seu projeto é muito maior que nosso exemplo calc: suponha que contém um número de sub-diretórios e muitos outros arquivos. No curso do seu trabalho, você pode decidir que você precisa criar um cópia de trabalho que é destinado para novos recursos e correções de erros. Você pode conseguir isso selecionando arquivos e diretórios com datas anteriores em uma revisão particular (usando svn update -r livremente), ou mudando arquivos e diretórios para um ramo em particular (fazendo uso do svn switch). Quando estiver pronto, sua cópia de trabalho será uma mistura de diferentes revisões. Mas depois de testes, você saberá que é exatamente a combinação que você precisa.

Hora de fazer a foto. Copiar uma URL para outra não vai funcionar aqui. Nesse caso, você quer fazer uma foto exata da cópia de trabalho que você organizou e armazenar no repositório. Felizmente, svn copy na verdade tem quatro diferentes maneiras de ser usado (você pode ler sobre em Capítulo 9, Referência Completa do Subversion), incluindo a habilidade de copiar uma árvore de cópia de trablho para o respositório:

$ ls
my-working-copy/

$ svn copy my-working-copy http://svn.example.com/repos/calc/tags/mytag

Committed revision 352.

Agora existe um novo diretório no respositório /calc/tags/mytag, que é uma foto exata da sua cópia de trabalho—combinado revisões, URLs, e tudo mais.

Outros usuários tem encontrado usos interessantes para esse recurso. Algumas vezes existe situações onde você tem um monte de mudanças locais na sua cópia de trabalho, e você gostaria que um colega de trabalho as visse. Ao invés de usar svn diff e enviar o arquivo patch (que não irá ter as informações de mudança na árvore de diretórios, em symlink e mudanças nas propriedades), você pode usar svn copy para “subir” sua cópia local para uma