Em 2015 escrevi sobre como fazer controle de alterações em documentos escritos com LaTeX usando Git e SourceTree. À época, utilizava um repositório git criado por mim num servidor da UFES, o que depois avaliei que deixou algumas questões complicadas. Por este motivo, recentemente, migrei para o BitBucket, o que exige uma atualização das instruções do post antigo. Este post é uma atualização daquele, só com o que interessa agora aos meus alunos orientados.

O que são git, BitBucket e SourceTree?

Caso você ainda não saiba (pouco provável, mas just in case), git é um sistema de controle de versão que tem como características interessantes ser gratuito, open source e distribuído. Esta última característica permite que você trabalhe com os comandos de controle de versão na sua máquina mesmo sem acesso a um repositório central (ex.: sem conexão com a Internet). Para uma discussão sobre porque utilizar uma ferramenta de controle de versão, sugiro ler o início do post antigo.

Para uso compartilhado por mais de uma pessoa, é comum a instalação do git e criação de um repositório num servidor ou, de maneira mais simples, você pode usar um serviço gratuito que já disponibiliza um servidor de repositórios git pra você, como GitHub, GitLab, BitBucket, etc. BitBucket, portanto, é um serviço da Atlassian (empresa que oferece outras ferramentas conhecidas, como Jira e Trello) que, dentre outras coisas, permite que você crie repositórios git e os acesse da sua máquina.

Por fim, para uso do git em sua máquina local, após a instalação você pode usar diretamente a linha de comando no terminal ou adotar um dos vários front-ends (clientes GUI) que oferecem uma forma mais amigável de manipulação de repositórios locais e remotos. O SourceTree, que por acaso também é da Atlassian, é um desses front-ends. Caso você use Linux, a sabedoria das massas indica o Giggle como uma boa opção. Em 2017, alguns alunos me sugeriram também o GitKraken. Nestes casos, será necessário adaptar algumas instruções abaixo (caso queira contribuir com instruções, deixe um comentário por favor).

Para uma referência geral e rápida sobre o git, sugiro os slides preparados por Jorge Ramirez para uma disciplina lecionada pela profª. Renata Guizzardi na Universidade de Trento em 2019.

Acessando o repositório

O repositório de cada aluno(a) é criado por mim e, utilizando o e-mail que tenho cadastrado, adiciono-o(a) ao repositório com acesso de escrita ao mesmo. Isso provavelmente dispara um e-mail do BitBucket para o(a) aluno(a) com instruções para criação de sua conta. Se você recebeu um e-mail assim, siga as instruções do e-mail antes de prosseguir com as instruções a seguir.

Assim que tiver acesso ao repositório, conseguirá abri-lo com seu navegador Web e, clicando no botão Clone, conseguirá ver a URL do repositório como parâmetro do comando git clone (por exemplo, para o repositório de modelos LaTeX que também hospedo no BitBucket, a URL é: git@bitbucket.org:vitorsouza-ufes/latex-templates.git).

Por fim, para não ter que ficar usando HTTP e autenticação a cada acesso, sugere-se o uso de SSH, com a criação de uma chave SSH em sua máquina local e cadastro desta chave SSH na sua conta BitBucket (clique no seu ícone de perfil > BitBucket Settings > Security > SSH Keys). Assim ele sempre vai reconhecer você a partir daquela máquina (caso troque de máquina, é preciso fazer de novo).

Com autenticação configurada e de posse da URL, abra o SourceTree, clique no botão + New Repository e escolha a opção Clone from URL. Preencha no campo Source URL a URL do repositório e escolha um diretório local no seu computador no qual os arquivos serão copiados, conforme mostra a figura à direita (clique na figura para ampliar). Note que a captura de tela é antiga e usa a URL do repositório criado no servidor do NEMO, que não existe mais.

Se tudo estiver certo com seu acesso SSH ao repositório (configurado anteriormente) o SourceTree irá obter todos os arquivos do servidor e copiá-los para o diretório que você escolheu no seu computador, por fim adicionando o novo repositório à lista exibida em sua tela inicial. Um duplo-clique no nome do repositório abre a janela exibida na figura abaixo. Como você acaba de obter os arquivos do servidor e não fez nenhuma alteração neles, não há nada para fazer commit.

Nessa tela você pode ver toda a estrutura do repositório alterando o filtro atual na parte superior da tela da opção padrão Pending files, sorted by path para All files, sorted by path. À direita do campo de filtro, um botão permite alterar a visão para Tree view para ver os arquivos em uma árvore de diretórios. O resultado é mostrado na figura abaixo.

No exemplo acima há um artigo no repositório. A estrutura de diretórios antiga tinha uma pasta para cada aluno, com seus artigos dentro. A partir da raiz, a pasta bfmartins representa uma aluna de mestrado. Dentro de sua pasta encontram-se os artigos em que ela for a primeira autora. Nesse momento, ela estava trabalhando em um artigo sobre FrameWeb 2.0, para a conferência WISE 2015, daí a pasta 2015-wise-frameweb2 (ano – sigla conferência – assunto do artigo). Mais adiante explico sobre a estrutura de pastas usada atualmente, já que agora cada aluno tem o seu repositório.

Selecionando um arquivo mostra seu conteúdo atual. Clicando com o botão direito em um arquivo é possível abri-lo (no editor padrão configurado no sistema operacional) escolhendo a opção Open.

Enviando modificações para o repositório

Tendo o repositório atualizado em seu computador, você pode trabalhar nos arquivos localmente para depois enviar as alterações para o servidor. Além disso, como estamos usando o git, é criado um repositório local no seu computador, de modo que você pode fazer commits de suas alterações mesmo estando offline. Depois basta enviar (push) os commits para o servidor.

É importante entender que são dois passos separados! Eles podem ser feitos de uma vez só, mas muitas vezes o(a) aluno(a) se confunde, faz o commit local, não envia (push) para o repositório e eu não consigo revisar as alterações!

Ao alterar algum arquivo do repositório, ele muda o ícone do arquivo na árvore de diretórios do SourceTree, como mostra a figura abaixo. Clicando no arquivo, o SourceTree mostra a diferença (diff) entre o arquivo anterior e o atual (considerando seu repositório local).

A ferramenta de diff do SourceTree não possui suporte a quebra de linhas. Se você quiser ver exatamente o que mudou na linha de forma mais fácil, pode usar alguma ferramenta externa. No Mac o SourceTree vem configurado pra usar o FileMerge (ferramenta instalada junto com o Xcode). Clicando com o botão direito no arquivo e selecionando External diff, ele abre as duas versões do arquivo no FileMerge, como mostra a figura abaixo.

Após ter trabalhado num trecho do artigo, pode-se fazer o commit, em dois passos. Primeiro, é preciso indicar o que vai entrar no commit. Isso é feito clicando na caixa de marcação que fica à esquerda dos arquivos. Se quiser selecionar todos os arquivos, basta clicar na caixa de marcação à esquerda do título Unstaged files. Os arquivos selecionados passam para a listagem superior, chamada Staged files.

O segundo passo consiste em clicar no botão Commit na barra de ferramentas do topo da janela, inserir uma descrição breve do que você fez desde o último commit e enviar suas alterações para seu repositório local. Caso queira enviá-las diretamente ao repositório remoto, marque a opção Push changes immediately to origin/master antes de enviar. A figura abaixo mostra o SourceTree momentos antes do commit ser efetuado.

Se você fez apenas commits locais, sem enviar ao servidor, o número de commits pendentes será exibido acima do botão Push da barra de ferramentas no topo da janela. Basta clicar nele para enviar as modificações para o servidor. Quando mais de um autor trabalha no mesmo artigo, é importante enviar as alterações para o servidor com frequência (ao menos no final do dia ou cada vez que você fizer uma pausa na sua tarefa de escrita, por exemplo para o almoço). Isso evita que dois ou mais autores modifiquem o mesmo artigo e causem conflito ao tentarem enviá-lo ao servidor. É possível resolver eventuais conflitos, mas deixarei esse assunto para outro momento.

Obtendo alterações do repositório

O SourceTree verifica de tempos em tempos o repositório remoto (você pode forçar a verificação clicando no menu Repository, item Refresh Remote Status). Quando algum colega efetua alterações nos arquivos e os envia ao servidor, notificações aparecerão tanto na tela inicial quanto na área de trabalho do repositório específico. A figura abaixo mostra um exemplo para o repositório konangelop-papers que eu compartilhava com um colega da Universidade de Trento.

Como pode ser visto na figura, a tela inicial mostra dois números ao lado de master (que é o nome do ramo, ou branch, que estamos trabalhando): 8 arquivos sofreram modificações ao longo de 20 commits. Na área de trabalho do repositório o número de commits aguardando no servidor também são mostrados acima do botão Pull na barra de ferramentas no topo da janela. E, intuitivamente, é clicando neste botão que você traz os commits do servidor para seu repositório local, atualizando assim seus arquivos.

Enfim, controle de alterações no LaTeX

Com a infraestrutura pronta e as ferramentas adequadas, enfim podemos chegar a um processo de controle de alterações em documentos LaTeX (por mais primitivo que ele possa parecer para usuários de Word/Writer). O controle do que foi alterado pelo colega é feito usando o diff, conforme já exemplificado acima. Falta, então, uma maneira de deixar notas e respondê-las.

A solução envolve um pacote LaTeX chamado colorinlistoftodos, que permite adicionar texto em caixas coloridas, semelhantes às usadas nos comentários de Word/Writer (porém ficam no corpo do texto e não numa coluna lateral). Para usá-lo, é preciso incluir algumas definições no início do arquivo (que já estão incluídas em todos os modelos do meu repositório de modelos LaTeX):

% Colorinlistoftodos package: to insert colored comments so authors can collaborate on the content.
\usepackage[colorinlistoftodos, textwidth=20mm, textsize=footnotesize]{todonotes}
\newcommand{\aluno}[1]{\todo[author=\textbf{Aluno},color=green!30,caption={},inline]{#1}}
\newcommand{\vitor}[1]{\todo[author=\textbf{Vítor},color=red!30,caption={},inline]{#1}}

Feitas as definições, eu incluo notas ao longo do documento usando a macro \vitor{} e o(a) aluno(a) responde com \aluno{} (trocar aluno e Aluno pelo nome do(a) aluno(a)). Na configuração acima, o(a) aluno(a) comenta usando caixas verdes e eu respondo com caixas vermelhas. A figura abaixo mostra uma simulação de uma discussão sobre o primeiro parágrafo de um artigo de exemplo.

No exemplo, eu questiono uma afirmação do aluno (ou porque eu não tenho certeza ou porque acho que deve ser modificado, mas quero que o aluno reflita sobre a questão). Após efetuar o pull da nova versão do repositório e ver o comentário, o aluno responde, justificando seu texto original. Caso o aluno tivesse concordado com a mudança da frase, faria a modificação do texto e adicionaria um comentário diferente abaixo do comentário do professor: \aluno{OK. Alterado.}.

Isso ilustra a importância de sempre continuar a discussão até o fim. Apenas quando não houver mais nada a responder que eu irei excluir todos os comentários, encerrando a questão. De qualquer forma, o aparecimento e desaparecimento de comentários nas versões do artigo ficarão visíveis no diff.

Outra coisa importante é usar um bom editor LaTeX que permita navegação entre código fonte e PDF. O TeXstudio, mostrado na figura acima, tem esta funcionalidade. Se o usuário segurar a tecla Command (no Mac) ou Ctrl (Windows/Linux) e clicar em um parágrafo do código-fonte, o mesmo é exibido no PDF à direita e vice-versa (Command+click ou Ctrl+click no PDF à direita leva ao trecho no código-fonte).

Considerando comentários de bancas e revisores

Quando um documento precisar ser alterado por ter sido revisado por uma banca (ex.: versão final de PG, de dissertação ou tese) ou revisores de conferências/periódicos (ex.: versões camera-ready), peço aos meus alunos(as) que sigam o seguinte protocolo:

1. Correções simples (ex.: erros de grafia) podem ser feitas diretamente;
2. Para as demais correções, crie uma macro \banca{} ou \revisor{} com uma cor diferente (se preferir, uma para cada membro da banca/para cada revisor) e adicione todos os comentários no documento;
3. Antes de começar a modificar seu texto, faça um commit só com os comentários;
4. Em seguida, comece a modificar seu texto para atender aos comentários ou, caso não concorde com algum comentário ou não tenha certeza de como atendê-lo, insira uma resposta utilizando um comentário seu (\aluno{} ou seu nome) para que possamos discutir nas rodadas de revisão;
5. Faça commits e solicite minha revisão por capítulo/seção ou do documento todo, como preferir e de acordo com os prazos que tiver pra cumprir.

Estrutura dos repositórios

Repositórios de alunos envolvidos em pesquisa (IC, mestrado, doutorado) tem o seguinte formato:

• graylit: diretório para monografias e relatórios. Exemplos:
  • bsc-nome-aluno: diretório para documentos produzidos durante a graduação. Exemplos:
    • ic-subprojeto: subprojeto de iniciação científica;
    • ic-relatorio-parcial: relatório parcial de iniciação científica;
    • ic-relatorio-final: relatório final de iniciação científica;
    • pg-anteprojeto: anteprojeto de graduação;
    • pg-monografia: monografia de projeto de graduação
  • msc-nome-aluno: dissertação de mestrado;
  • dsc-projeto-nome-aluno: pré-projeto de doutorado;
  • dsc-proposta-nome-aluno: proposta de tese de doutorado;
  • dsc-tese-nome-aluno: tese de doutorado;
• papers: diretório para artigos submetidos para revisão;
  • ano-veiculo-assunto: subdiretórios seguem este padrão, indicando ano da publicação, veículo (sigla do periódico ou da conferência) para a qual será submetido e assunto do artigo. Ex.: 2019-er-ooco — artigo sobre a OOC-O submetido ao ER 2019. Dentro dele, os subdiretórios:
    • submitted: versão enviada para avaliação;
    • x-camera-ready: versão camera ready caso artigo seja aprovado (revisão solicitada pela conferência);
    • x-review-01: no caso de artigos de periódicos que exigem múltiplas rodadas de revisão, usar diretórios numerados como este;
    • x-typeset: em alguns casos, há ainda uma revisão por parte da editora, produzindo a versão que efetivamente será publicada.

Alunos envolvidos apenas em projeto de graduação possuem um repositório simplificado:

• code: código-fonte do software desenvolvido, caso o PG envolva desenvolvimento de um software;
• pg-anteprojeto: anteprojeto de graduação;
• pg-engsoft-especificacao-projeto: documento de especificação de projeto de software, caso o PG envolva desenvolvimento de um software;
• pg-engsoft-especificacao-requisitos: documento de especificação de requisitos de software, caso o PG envolva desenvolvimento de um software;
• pg-monografia: monografia de projeto de graduação.

Em resumo: passo a passo da escrita colaborativa em LaTeX para meus alunos

1 – Para o primeiro acesso, eu crio o repositório e dou acesso a você;

2 – Se for primeiro acesso, você configura a autenticação e clona o repositório em sua máquina local usando o SourceTree;

3 – Se você for escrever alguma monografia ou relatório, muitas vezes eu já incluo o template no repositório ao criá-lo. Do contrário, obtenha-o no repositório de modelos LaTeX. Se você for escrever um artigo, obtenha o template no site da conferência ou do periódico. Lembre-se de seguir as regras descritas na seção anterior;

4 – Assim que tiver escrito o suficiente para sofrer revisão, assegure-se de que não há erros ortográficos no documento (use um revisor ortográfico!) e de ter enviado todos os commits para o servidor. Então, me envie um e-mail solicitando que faça a revisão do documento. Pode-se solicitar a revisão apenas quando tudo estiver pronto ou capítulo por capítulo (seção por seção). Neste último caso, é melhor se os capítulos/seções estiverem em arquivos separados para evitar conflitos;

5 – Eu faço o pull do documento e sua revisão, corrigindo diretamente o que achar apropriado e adicionado comentários com \vitor{} (fundo vermelho) quando tiver dúvidas ou quiser dar explicações. Ao final da revisão, aviso o aluno (também por e-mail) que a revisão foi feita;

6 – Ao obter uma versão revisada do repositório, você deve:

1. Fazer o diff entre sua versão anterior e a nova versão revisada por mim para ver o que foi alterado. No caso de eu ter feito alguma alteração que você não concorde, adicione uma nota (\aluno{}, fundo verde) questionando a alteração;
2. Responder todos os meus comentários antes de enviar uma nova versão para revisão, seja efetuando as alterações pedidas (e comentando “OK”), seja respondendo com um questionamento, discordando, argumentando, etc.
3. Passar novamente o corretor ortográfico caso tenha escrito novos parágrafos.

7 – Produzindo uma nova versão e enviando-a ao repositório no servidor, me avise novamente (preferencialmente na mesma thread de e-mail) e o ciclo continua até a versão final do artigo.