Copyright Damien Elmes 2004. This file is licensed under the GNU GPL.
Copyright Damien Elmes, Gustavo De Nardin 2004. Este arquivo está sob a licença GNU GPL.
Usando o Arch em um projeto de um só desenvolvedor.
(Original em inglês) (Tradução russa) (Tradução alemã) (Tradução japonesa)
Este mini-guia apresenta um breve apanhado de algumas das características básicas do Arch. Ele intenta ser complementar ao - pode ser útil ler isto primeiro, então outros mini-guias, e então o tutorial, para aprender mais.
Nota de tradução: as adulterações lingüísticas mais significativas são:
Antes de poder começar a usar o Arch, precisamos configurar um repositório ("archive"). Isto é um simples diretório no qual as revisões de um projeto são armazenadas. Não precisa ser no sistema de arquivos local - você pode fazer um repositório em outra máquina, e acessá-lo via HTTP, FTP, SFTP, etc.. Usemos um repositório local por simplicidade.
Se você já usou algo como o CVS antes, pode pensar no repositório como o "CVSROOT".
Configurar um repositório é bem direto:
john@shell% tla make-archive ~/myarchive john@shell% tla my-default-archive
O que isso faz é associar o nome do repositório com ~/myarchive, e então põe esse repositório como default. Isso também cria ~/myarchive e põe alguns arquivos de controle lá.
Nós podemos verificar que este passo funcionou pedindo ao Arch para listar os repositórios disponíveis:
john@shell% tla archives
http://arch.quackerhead.com/~lord/archives/
/home/john/myarchive
Percebeu como john@doe--myarchive não é o único repositório? O outro listado é um dos quais de onde pode-se pegar a versão mais nova do Arch. Não o usaremos neste tutorial.
O nome de um repositório tem a seguinte forma:
ório
O endereço de email não precisa ser real - ele é apenas um modo de tornar um repositório globalmente único. Nomes de repositórios precisam adotar esta convenção.
Um último passo antes de poder importar seu primeiro projeto - você precisa configurar sua identificação. Se faz isso com o comando my-id:
john@shell% tla my-id "John Doe <>"
O Arch vai lembrar disso (assim como vai lembrar do seu repositório default). A identificação é usada em coisas como mensagens de changelog.
Agora que configurou um repositório, você está pronto para importar seu primeiro projeto. Para isto, comece com um diretório onde estão os fontes - chamado de "diretório de trabalho" ("working directory"), ou "árvore do projeto" ("project tree"). Usaremos um simplório projeto 'hello', como exemplo:
john@shell% cd $wd/hello john@shell% ls hello.py world.py
O primeiro passo para importar um projeto é dar-lhe um nome. Podemos chamar este projeto assim:
hello--dev--1.0
Na verdade isto contém três informações, unidas por duplos-hífens (--).
hello é uma categoria ("category name"). Este é o nome do projeto, sem qualquer informação sobre versões.dev é o ramo-de-desenvolvimento ("branch name"). Aqui, 'dev' indica "em desenvolvimento". Podemos acrescentar um ramo "estável" posteriormente.1.0 é o número-de-versão ("version number"). Tradicionalmente tinha que ser dois números separados por um ponto - agora pode-se ter quantos números se desejar.O Arch impõe este formato de nomenclatura, que pode parecer um tanto estranho a princípio. Ele acaba sendo um modo conveniente de se referir a uma revisão ("revision") específica do programa - você provavelmente acabará gostando.
Para batizar o projeto, nós inicializamos nosso diretório como um diretório de trabalho ("working directory"), com o comando init-tree:
john@shell% tla init-tree hello--dev--1.0
john@shell% ls
hello.py world.py {arch}
Perceba como um diretório '{arch}' foi criado. Ele contém as informações sobre o nome do projeto, qual seu repositório, etc..
Por default, o Arch usa um "método de adição explícito" ("explicit tagging method"). O que isso significa é que você precisa dizer ao Arch explicitamente quais arquivos quer incluir no repositório. Se faz isso marcando ("tagging") os arquivos. No nosso exemplo, queremos incluir todos os arquivos com extensão '.py'.
john@shell% tla add *.py
Podemos verificar que a operação foi bem sucedida pedindo um inventário ("inventory") do projeto.
john@shell% tla inventory S ./hello.py S ./world.py
Se não tivessemos marcado os arquivos, eles seriam identificados como "não-reconhecidos" (U) ("unrecognised"), ao invés de arquivos "fonte" (S) ("source"):
john@shell% tla inventory U ./hello.py U ./world.py
Agora estamos prontos para importar nosso diretório de trabalho no repositório. Na verdade há dois passos necessários para isso - um é criar as categorias, ramos, e revisões no repositório; outra é fazer a importação. Iremos aproveitar uma opção (--setup, -S) existente desde o tla 1.1 para fazer as duas coisas de uma só vez:
john@shell% tla import --setup * creating category /hello * creating branch /hello--dev * creating version /hello--dev--1.0 * imported /hello--dev--1.0
Parabéns! Se acompanhou até aqui, a parte difícil já era. O resto do tutorial lhe mostrará como o Arch pode tornar sua vida mais fácil.
Tendo importado nosso projeto, podemos começar a modificá-lo. Imagine que John Doe modificou o hello.py para acrescentar uma nova opção - mostrar o texto 'hello' 5 vezes, ao invés de uma. Antes de fazer "commit" da sua alteração no repositório, ele quer verificar se está tudo correto, e se por acaso não esqueceu código destinado a testes.
Para isso, o Arch provê um comando chamado what-changed:
john@shell% tla what-changed M ./hello.py
Isto diz a John que o 'hello.py' foi modificado (M). Para ver as alterações em si, John quer ver a diferença entre a versão no repositório e seu diretório de trabalho. Para isso, ele pode passar um argumento ao what-changed:
john@shell% tla what-changed --diffs M ./hello.py * modified files --- orig/hello.py +++ mod/hello.py @@ -1,3 +1,4 @@ #!/usr/bin/env python -print "hello" +for i in range(5): + print "hello"
Isso indica que uma linha foi removida, e duas adicionadas.
Note que esses comandos usaram uma cópia cache da versão mais recente do repositório, chamada de "pristine tree" ("pristine", que quer dizer "limpa", "imaculada", etc., porque é uma versão não modificada, da revisão mais recente). Isto é especialmente útil para operação desconectada - você não tem que acessar o repositório para poder verificar as mudanças.
John, contente por suas alterações estarem como esperava, agora deseja fazer commit de suas mudanças no repositório. Para isso, o Arch provê um comando commit:
john@shell% tla commit -L "print hello 5 times instead of 1"
M ./hello.py
* update pristine tree (/hello--dev--1.0--base-0
=> hello--dev--1.0--patch-1)
* commited /hello--dev--1.0--patch-1
Note o argumento -L. Isto lhe permite especificar uma mensagem de log na linha de comando. Isto é útil para alterações rápidas, mas às vezes você vai querer uma mensagem mais detalhada. Para isso, pode criar uma mensagem antes de fazer o commit.
Para mudanças maiores, as quais exigem uma descrição mais elaborada, pode ser útil criar uma mensagem de log antes de fazer commit. Para isso, pode-se usar o comando make-log:
john@shell% tla make-log /home/john/wd/hello/++ john@shell% cat ++ Summary: Keywords:
Isto cria uma mensagem de log vazia, e mostra o nome do arquivo. Um idioma comum é editar este arquivo assim que é criado, com algo como:
john@shell% $EDITOR $(tla make-log) Warning: not overwriting existing log file <editor opens up>
O campo 'Summary:' do log é usada como uma breve descrição da alteração - geralmente com uns 60 caracteres ou menos. O campo 'Keywords:' não é muito usado. Qualquer texto abaixo do 'Keywords:' é tratado como o corpo da mensagem de log - pode ser tão extenso quanto você queira.
John poderia preencher a mensagem de log assim:
Summary: mostrar hello 5 vezes ao invés de 1 Keywords: Devido ao pedido de um usuário, eu fiz mostrar 'hello' 5 vezes ao invés de 1. Ainda se pode obter a funcionalidade antiga rodando 'hello | tail -1'. Comentários sobre essa alteração são bem-vindos.
Quando John estiver pronto para fazer commit da mudança usando o arquivo de log, ele pode simplesmente omitir o argumento -L:
john@shell% tla commit
M ./hello.py
* update pristine tree (/hello--dev--1.0--base-0
=> hello--dev--1.0--patch-1)
* commited /hello--dev--1.0--patch-1
Para listar as alterações em um repositório ("archive"), pode-se usar o comando revisions. O Arch também tem um comando log-ls, o qual lista as alterações no seu diretório de trabalho ("working directory"). Você pode encontrar menos alterações no seu diretório de trabalho do que no repositório, caso multiplas pessoas estejam trabalhando no mesmo ramo - mas não entraremos nisso aqui.
Estas descrições de alterações estão contidas em "patch logs". Cada "patch log" se parece com uma mensagem de email, e guarda coisas como a descrição da alteração, data, etc.. Os patch logs são armazenados em ambos, o repositório e seu diretório de trabalho, então se você estiver trabalhando em algum código no seu laptop, e não tem acesso ao repositório, ainda pode listar todas as alterações feitas na árvore do projeto.
O comando revisions fica assim:
john@shell% tla revisions --summary
base-0
initial import
patch-1
print hello 5 times instead of 1
Para um ramo com um único desenvolvedor, log-ls sempre vai mostrar o mesmo (que revisions). Agora demonstramos um argumento extra que ambos aceitam:
john@shell% tla log-ls --summary --creator
base-0
John Doe <>
initial import
patch-1
John Doe <>
print hello 5 times instead of 1
Perceba o criador ("creator") - este é o nome que demos ao my-id antes.
Os patch logs que mencionamos anteriormente descrevem mais informações do que podemos ver usando os comandos log-ls or revisions. Para obter essas informações extras, o Arch provê um comando changelog:
john@shell% tla changelog
# do not edit -- automatically generated by arch changelog
# arch-tag: /hello--dev--1.0
#
2003-07-13 09:36:33 GMT John Doe <> patch-1
Summary:
print hello 5 times instead of 1
Revision:
hello--dev--1.0--patch-1
Upon a request from a user, I have made hello print 5 times instead of 1.
You can still obtain the old functionality by running hello | tail -1.
Comments on this change are welcome.
modified files:
./hello.py
2003-07-13 08:58:18 GMT John Doe <> base-0
Summary:
initial import
Revision:
hello--dev--1.0--base-0
(automatically generated log message)
new files:
./hello.py ./world.py
O comando changelog acessa o repositório para prover a lista de alterações - então a lista completa é mostrada mesmo se o seu diretório de trabalho não estiver atualizado.
Suponha que John percebeu que sua nova versão do 'hello' estragou algum outro programa que o utilizava. Para testar se o problema está mesmo na sua atualização, ele quer testar uma versão ("release") anterior.
Ele começa listando as alterações (já que não lembra):
john@shell% cd
john@shell% tla revisions --summary hello--dev--1.0
base-0
initial import
patch-1
print hello 5 times instead of 1
Perceba como o nome do projeto é passado ao comando revisions. Isto é porque nós saímos do diretório de trabalho - então não há projeto associado.
John, olhando a lista, percebe que quer a versão base (ele poderia ter escolhido um patch mais recente, caso houvessem mais a escolher). Para pegar a versão base-0, ele pode rodar o seguinte comando:
john@shell% tla get hello--dev--1.0--base-0 * from import revision: /hello--dev--1.0--base-0 * making pristine copy * tree version set /hello--dev--1.0
Isto cria um diretório chamado hello--dev--1.0--base-0. Pode-se também especificar outro nome:
john@shell% tla get hello--dev--1.0--base-0 mydir
Se você quer a revisão mais recente, há um atalho - pode-se omitir a especificação de versão (base-0, patch-1, etc.):
john@shell% tla get hello--dev--1.0