{"id":138,"date":"2020-03-27T16:01:37","date_gmt":"2020-03-27T19:01:37","guid":{"rendered":"http:\/\/www.inf.ufes.br\/~vitorsouza\/?p=138"},"modified":"2020-04-17T17:40:28","modified_gmt":"2020-04-17T20:40:28","slug":"controle-de-alteracoes-em-latex-usando-git-com-bitbucket-e-sourcetree","status":"publish","type":"post","link":"https:\/\/inf.ufes.br\/~vitorsouza\/controle-de-alteracoes-em-latex-usando-git-com-bitbucket-e-sourcetree\/","title":{"rendered":"Controle de altera\u00e7\u00f5es em LaTeX usando git, com BitBucket e SourceTree"},"content":{"rendered":"\n

Em 2015 escrevi sobre como fazer controle de altera\u00e7\u00f5es em documentos escritos com LaTeX usando Git e SourceTree<\/a>. \u00c0 \u00e9poca, utilizava um reposit\u00f3rio git criado por mim num servidor da UFES, o que depois avaliei que deixou algumas quest\u00f5es complicadas. Por este motivo, recentemente, migrei para o BitBucket<\/a>, o que exige uma atualiza\u00e7\u00e3o das instru\u00e7\u00f5es do post antigo. Este post \u00e9 uma atualiza\u00e7\u00e3o daquele, s\u00f3 com o que interessa agora aos meus alunos orientados. <\/p>\n\n\n\n\n\n\n\n

O que s\u00e3o git, BitBucket e SourceTree?<\/h2>\n\n\n\n

Caso voc\u00ea ainda n\u00e3o saiba (pouco prov\u00e1vel, mas just in case<\/em>), git<\/a> \u00e9 um sistema de controle de vers\u00e3o que tem como caracter\u00edsticas interessantes ser gratuito, open source<\/em> e distribu\u00eddo. Esta \u00faltima caracter\u00edstica permite que voc\u00ea trabalhe com os comandos de controle de vers\u00e3o na sua m\u00e1quina mesmo sem acesso a um reposit\u00f3rio central (ex.: sem conex\u00e3o com a Internet). Para uma discuss\u00e3o sobre porque utilizar uma ferramenta de controle de vers\u00e3o, sugiro ler o in\u00edcio do post antigo<\/a>.<\/p>\n\n\n\n

Para uso compartilhado por mais de uma pessoa, \u00e9 comum a instala\u00e7\u00e3o do git e cria\u00e7\u00e3o de um reposit\u00f3rio num servidor ou, de maneira mais simples, voc\u00ea pode usar um servi\u00e7o gratuito que j\u00e1 disponibiliza um servidor de reposit\u00f3rios git pra voc\u00ea, como GitHub<\/a>, GitLab<\/a>, BitBucket<\/a>, etc. BitBucket, portanto, \u00e9 um servi\u00e7o da Atlassian<\/a> (empresa que oferece outras ferramentas conhecidas, como Jira<\/a> e Trello<\/a>) que, dentre outras coisas, permite que voc\u00ea crie reposit\u00f3rios git e os acesse da sua m\u00e1quina.<\/p>\n\n\n\n

Por fim, para uso do git em sua m\u00e1quina local, ap\u00f3s a instala\u00e7\u00e3o voc\u00ea pode usar diretamente a linha de comando<\/a> no terminal ou adotar um dos v\u00e1rios front-ends<\/em> (clientes GUI<\/a>) que oferecem uma forma mais amig\u00e1vel de manipula\u00e7\u00e3o de reposit\u00f3rios locais e remotos. O SourceTree<\/a>, que por acaso tamb\u00e9m \u00e9 da Atlassian, \u00e9 um desses front-ends<\/em>. Caso voc\u00ea use Linux, a sabedoria das massas<\/a> indica o Giggle<\/a> como uma boa op\u00e7\u00e3o. Em 2017, alguns alunos me sugeriram tamb\u00e9m o GitKraken<\/a>. Nestes casos, ser\u00e1 necess\u00e1rio adaptar algumas instru\u00e7\u00f5es abaixo (caso queira contribuir com instru\u00e7\u00f5es, deixe um coment\u00e1rio por favor).<\/p>\n\n\n\n

Para uma refer\u00eancia geral e r\u00e1pida sobre o git, sugiro os slides preparados por Jorge Ramirez<\/a> para uma disciplina lecionada pela prof\u00aa. Renata Guizzardi<\/a> na Universidade de Trento em 2019.<\/p>\n\n\n\n

Acessando o reposit\u00f3rio<\/h2>\n\n\n\n

O reposit\u00f3rio de cada aluno(a) \u00e9 criado por mim e, utilizando o e-mail que tenho cadastrado, adiciono-o(a) ao reposit\u00f3rio com acesso de escrita ao mesmo. Isso provavelmente dispara um e-mail do BitBucket para o(a) aluno(a) com instru\u00e7\u00f5es para cria\u00e7\u00e3o de sua conta. Se voc\u00ea recebeu um e-mail assim, siga as instru\u00e7\u00f5es do e-mail antes de prosseguir com as instru\u00e7\u00f5es a seguir.<\/p>\n\n\n\n

Assim que tiver acesso ao reposit\u00f3rio, conseguir\u00e1 abri-lo com seu navegador Web e, clicando no bot\u00e3o Clone<\/strong>, conseguir\u00e1 ver a URL do reposit\u00f3rio como par\u00e2metro do comando git clone<\/code> (por exemplo, para o reposit\u00f3rio de modelos LaTeX<\/a> que tamb\u00e9m hospedo no BitBucket, a URL \u00e9: git@bitbucket.org:vitorsouza-ufes\/latex-templates.git<\/code>).<\/p>\n\n\n\n

Por fim, para n\u00e3o ter que ficar usando HTTP e autentica\u00e7\u00e3o a cada acesso, sugere-se o uso de SSH, com a cria\u00e7\u00e3o de uma chave SSH<\/a> em sua m\u00e1quina local e cadastro desta chave SSH na sua conta BitBucket<\/a> (clique no seu \u00edcone de perfil > BitBucket Settings > Security > SSH Keys). Assim ele sempre vai reconhecer voc\u00ea a partir daquela m\u00e1quina (caso troque de m\u00e1quina, \u00e9 preciso fazer de novo).<\/p>\n\n\n\n

\"\"<\/a><\/figure><\/div>\n\n\n\n

Com autentica\u00e7\u00e3o configurada e de posse da URL, abra o SourceTree, clique no bot\u00e3o + New Repository<\/strong> e escolha a op\u00e7\u00e3o Clone from URL<\/strong>. Preencha no campo Source URL<\/strong> a URL do reposit\u00f3rio e escolha um diret\u00f3rio local no seu computador no qual os arquivos ser\u00e3o copiados, conforme mostra a figura \u00e0 direita (clique na figura para ampliar). Note que a captura de tela \u00e9 antiga e usa a URL do reposit\u00f3rio criado no servidor do NEMO, que n\u00e3o existe mais.<\/p>\n\n\n\n

Se tudo estiver certo com seu acesso SSH ao reposit\u00f3rio (configurado anteriormente) o SourceTree ir\u00e1 obter todos os arquivos do servidor e copi\u00e1-los para o diret\u00f3rio que voc\u00ea escolheu no seu computador, por fim adicionando o novo reposit\u00f3rio \u00e0 lista exibida em sua tela inicial. Um duplo-clique no nome do reposit\u00f3rio abre a janela exibida na figura abaixo. Como voc\u00ea acaba de obter os arquivos do servidor e n\u00e3o fez nenhuma altera\u00e7\u00e3o neles, n\u00e3o h\u00e1 nada para fazer commit<\/em>.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Nessa tela voc\u00ea pode ver toda a estrutura do reposit\u00f3rio alterando o filtro atual na parte superior da tela da op\u00e7\u00e3o padr\u00e3o Pending files, sorted by path<\/strong> para All files, sorted by path<\/strong>. \u00c0 direita do campo de filtro, um bot\u00e3o permite alterar a vis\u00e3o para Tree view<\/strong> para ver os arquivos em uma \u00e1rvore de diret\u00f3rios. O resultado \u00e9 mostrado na figura abaixo.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

No exemplo acima h\u00e1 um artigo no reposit\u00f3rio. A estrutura de diret\u00f3rios antiga tinha uma pasta para cada aluno, com seus artigos dentro. A partir da raiz, a pasta bfmartins<\/code> 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<\/strong>, para a confer\u00eancia WISE 2015<\/a><\/strong>, da\u00ed a pasta 2015-wise-frameweb2<\/code> (ano \u2013 sigla confer\u00eancia \u2013 assunto do artigo). Mais adiante explico sobre a estrutura de pastas usada atualmente, j\u00e1 que agora cada aluno tem o seu reposit\u00f3rio.<\/p>\n\n\n\n

Selecionando um arquivo mostra seu conte\u00fado atual. Clicando com o bot\u00e3o direito em um arquivo \u00e9 poss\u00edvel abri-lo (no editor padr\u00e3o configurado no sistema operacional) escolhendo a op\u00e7\u00e3o Open<\/strong>.<\/p>\n\n\n\n

Enviando modifica\u00e7\u00f5es para o reposit\u00f3rio<\/h2>\n\n\n\n

Tendo o reposit\u00f3rio atualizado em seu computador, voc\u00ea pode trabalhar nos arquivos localmente para depois enviar as altera\u00e7\u00f5es para o servidor. Al\u00e9m disso, como estamos usando o git, \u00e9 criado um reposit\u00f3rio local no seu computador, de modo que voc\u00ea pode fazer commits<\/em> de suas altera\u00e7\u00f5es mesmo estando offline<\/em>. Depois basta enviar (push<\/em>) os commits<\/em> para o servidor.<\/p>\n\n\n\n

\u00c9 importante<\/strong> entender que s\u00e3o dois passos separados! Eles podem ser feitos de uma vez s\u00f3, mas muitas vezes o(a) aluno(a) se confunde, faz o commit local, n\u00e3o envia (push<\/em>) para o reposit\u00f3rio e eu n\u00e3o consigo revisar as altera\u00e7\u00f5es!<\/p>\n\n\n\n

Ao alterar algum arquivo do reposit\u00f3rio, ele muda o \u00edcone do arquivo na \u00e1rvore de diret\u00f3rios do SourceTree, como mostra a figura abaixo. Clicando no arquivo, o SourceTree mostra a diferen\u00e7a (diff<\/em>) entre o arquivo anterior e o atual (considerando seu reposit\u00f3rio local).<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

A ferramenta de diff<\/em> do SourceTree n\u00e3o possui suporte a quebra de linhas. Se voc\u00ea quiser ver exatamente o que mudou na linha de forma mais f\u00e1cil, 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\u00e3o direito no arquivo e selecionando External diff<\/strong>, ele abre as duas vers\u00f5es do arquivo no FileMerge, como mostra a figura abaixo.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Ap\u00f3s ter trabalhado num trecho do artigo, pode-se fazer o commit<\/em>, em dois passos. Primeiro, \u00e9 preciso indicar o que vai entrar no commit<\/em>. Isso \u00e9 feito clicando na caixa de marca\u00e7\u00e3o que fica \u00e0 esquerda dos arquivos. Se quiser selecionar todos os arquivos, basta clicar na caixa de marca\u00e7\u00e3o \u00e0 esquerda do t\u00edtulo Unstaged files<\/strong>. Os arquivos selecionados passam para a listagem superior, chamada Staged files<\/strong>.<\/p>\n\n\n\n

O segundo passo consiste em clicar no bot\u00e3o Commit<\/strong> na barra de ferramentas do topo da janela, inserir uma descri\u00e7\u00e3o breve do que voc\u00ea fez desde o \u00faltimo commit<\/em> e enviar suas altera\u00e7\u00f5es para seu reposit\u00f3rio local. Caso queira envi\u00e1-las diretamente ao reposit\u00f3rio remoto, marque a op\u00e7\u00e3o Push changes immediately to origin\/master<\/strong> antes de enviar. A figura abaixo mostra o SourceTree momentos antes do commit<\/em> ser efetuado.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Se voc\u00ea fez apenas commits<\/em> locais, sem enviar ao servidor, o n\u00famero de commits<\/em> pendentes ser\u00e1 exibido acima do bot\u00e3o Push<\/strong> da barra de ferramentas no topo da janela. Basta clicar nele para enviar as modifica\u00e7\u00f5es para o servidor. Quando mais de um autor trabalha no mesmo artigo, \u00e9 importante enviar as altera\u00e7\u00f5es para o servidor com frequ\u00eancia (ao menos no final do dia ou cada vez que voc\u00ea fizer uma pausa na sua tarefa de escrita, por exemplo para o almo\u00e7o). Isso evita que dois ou mais autores modifiquem o mesmo artigo e causem conflito ao tentarem envi\u00e1-lo ao servidor. \u00c9 poss\u00edvel resolver eventuais conflitos, mas deixarei esse assunto para outro momento.<\/p>\n\n\n\n

Obtendo altera\u00e7\u00f5es do reposit\u00f3rio<\/h2>\n\n\n\n

O SourceTree verifica de tempos em tempos o reposit\u00f3rio remoto (voc\u00ea pode for\u00e7ar a verifica\u00e7\u00e3o clicando no menu Repository<\/em>, item Refresh Remote Status<\/em>). Quando algum colega efetua altera\u00e7\u00f5es nos arquivos e os envia ao servidor, notifica\u00e7\u00f5es aparecer\u00e3o tanto na tela inicial quanto na \u00e1rea de trabalho do reposit\u00f3rio espec\u00edfico. A figura abaixo mostra um exemplo para o reposit\u00f3rio konangelop-papers<\/strong> que eu compartilhava com um colega<\/a> da Universidade de Trento<\/a>.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Como pode ser visto na figura, a tela inicial mostra dois n\u00fameros ao lado de master<\/strong> (que \u00e9 o nome do ramo, ou branch<\/em>, que estamos trabalhando): 8<\/strong> arquivos sofreram modifica\u00e7\u00f5es ao longo de 20<\/strong> commits<\/em>. Na \u00e1rea de trabalho do reposit\u00f3rio o n\u00famero de commits<\/em> aguardando no servidor tamb\u00e9m s\u00e3o mostrados acima do bot\u00e3o Pull<\/strong> na barra de ferramentas no topo da janela. E, intuitivamente, \u00e9 clicando neste bot\u00e3o que voc\u00ea traz os commits<\/em> do servidor para seu reposit\u00f3rio local, atualizando assim seus arquivos.<\/p>\n\n\n\n

Enfim, controle de altera\u00e7\u00f5es no LaTeX<\/h2>\n\n\n\n

Com a infraestrutura pronta e as ferramentas adequadas, enfim podemos chegar a um processo de controle de altera\u00e7\u00f5es em documentos LaTeX (por mais primitivo que ele possa parecer para usu\u00e1rios de Word\/Writer). O controle do que foi alterado pelo colega \u00e9 feito usando o diff<\/em>, conforme j\u00e1 exemplificado acima. Falta, ent\u00e3o, uma maneira de deixar notas e respond\u00ea-las.<\/p>\n\n\n\n

A solu\u00e7\u00e3o envolve um pacote LaTeX chamado colorinlistoftodos<\/strong>, que permite adicionar texto em caixas coloridas, semelhantes \u00e0s usadas nos coment\u00e1rios de Word\/Writer (por\u00e9m ficam no corpo do texto e n\u00e3o numa coluna lateral). Para us\u00e1-lo, \u00e9 preciso incluir algumas defini\u00e7\u00f5es no in\u00edcio do arquivo (que j\u00e1 est\u00e3o inclu\u00eddas em todos os modelos do meu reposit\u00f3rio de modelos LaTeX<\/a>):<\/p>\n\n\n\n

% Colorinlistoftodos package: to insert colored comments so authors can collaborate on the content.\n\\usepackage[colorinlistoftodos, textwidth=20mm, textsize=footnotesize]{todonotes}\n\\newcommand{\\aluno}[1]{\\todo[author=\\textbf{Aluno},color=green!30,caption={},inline]{#1}}\n\\newcommand{\\vitor}[1]{\\todo[author=\\textbf{V\u00edtor},color=red!30,caption={},inline]{#1}}<\/code><\/pre>\n\n\n\n
Feitas as defini\u00e7\u00f5es, eu incluo notas ao longo do documento usando a macro \\vitor{}<\/code> e o(a) aluno(a) responde com \\aluno{}<\/code> (trocar aluno<\/code> e Aluno<\/code> pelo nome do(a) aluno(a)). Na configura\u00e7\u00e3o acima, o(a) aluno(a) comenta usando caixas verdes e eu respondo com caixas vermelhas. A figura abaixo mostra uma simula\u00e7\u00e3o de uma discuss\u00e3o sobre o primeiro par\u00e1grafo de um artigo de exemplo.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
No exemplo, eu questiono uma afirma\u00e7\u00e3o do aluno (ou porque eu n\u00e3o tenho certeza ou porque acho que deve ser modificado, mas quero que o aluno reflita sobre a quest\u00e3o). Ap\u00f3s efetuar o pull<\/em> da nova vers\u00e3o do reposit\u00f3rio e ver o coment\u00e1rio, o aluno responde, justificando seu texto original. Caso o aluno tivesse concordado com a mudan\u00e7a da frase, faria a modifica\u00e7\u00e3o do texto e adicionaria um coment\u00e1rio diferente abaixo do coment\u00e1rio do professor: \\aluno{OK. Alterado.}<\/code>.<\/p>\n\n\n\n
Isso ilustra a import\u00e2ncia de sempre continuar a discuss\u00e3o at\u00e9 o fim. Apenas quando n\u00e3o houver mais nada a responder que eu irei excluir<\/strong> todos os coment\u00e1rios, encerrando a quest\u00e3o. De qualquer forma, o aparecimento e desaparecimento de coment\u00e1rios nas vers\u00f5es do artigo ficar\u00e3o vis\u00edveis no diff<\/em>.<\/p>\n\n\n\n
Outra coisa importante \u00e9 usar um bom editor LaTeX que permita navega\u00e7\u00e3o entre c\u00f3digo fonte e PDF. O TeXstudio<\/a>, mostrado na figura acima, tem esta funcionalidade. Se o usu\u00e1rio segurar a tecla Command (no Mac) ou Ctrl (Windows\/Linux) e clicar em um par\u00e1grafo do c\u00f3digo-fonte, o mesmo \u00e9 exibido no PDF \u00e0 direita e vice-versa (Command+click ou Ctrl+click no PDF \u00e0 direita leva ao trecho no c\u00f3digo-fonte).<\/p>\n\n\n\n
Considerando coment\u00e1rios de bancas e revisores<\/h2>\n\n\n\n
Quando um documento precisar ser alterado por ter sido revisado por uma banca (ex.: vers\u00e3o final de PG, de disserta\u00e7\u00e3o ou tese) ou revisores de confer\u00eancias\/peri\u00f3dicos (ex.: vers\u00f5es camera-ready<\/em>), pe\u00e7o aos meus alunos(as) que sigam o seguinte protocolo:<\/p>\n\n\n\n
  1. Corre\u00e7\u00f5es simples (ex.: erros de grafia) podem ser feitas diretamente;<\/li>
  2. Para as demais corre\u00e7\u00f5es, crie uma macro \\banca{}<\/code> ou \\revisor{}<\/code> com uma cor diferente (se preferir, uma para cada membro da banca\/para cada revisor) e adicione todos os coment\u00e1rios no documento;<\/li>
  3. Antes de come\u00e7ar a modificar seu texto, fa\u00e7a um commit<\/em> s\u00f3 com os coment\u00e1rios;<\/li>
  4. Em seguida, comece a modificar seu texto para atender aos coment\u00e1rios ou, caso n\u00e3o concorde com algum coment\u00e1rio ou n\u00e3o tenha certeza de como atend\u00ea-lo, insira uma resposta utilizando um coment\u00e1rio seu (\\aluno{}<\/code> ou seu nome) para que possamos discutir nas rodadas de revis\u00e3o;<\/li>
  5. Fa\u00e7a commits<\/em> e solicite minha revis\u00e3o por cap\u00edtulo\/se\u00e7\u00e3o ou do documento todo, como preferir e de acordo com os prazos que tiver pra cumprir.<\/li><\/ol>\n\n\n\n
    Estrutura dos reposit\u00f3rios<\/h2>\n\n\n\n
    Reposit\u00f3rios de alunos envolvidos em pesquisa (IC, mestrado, doutorado) tem o seguinte formato:<\/p>\n\n\n\n