Organizando minha pesquisa (parte 2)

Concluí a primeira parte deste texto decidindo usar o git como ferramenta de software para organizar os documentos da minha pesquisa, e decidindo hospedar a minha pesquisa no GitLab. Nesta segunda parte, vamos ver mais detalhes de como estou fazendo isso.

É importante notar que eu vou usar aqui alguns termos específicos do git, mas nao vou explicá-los em detalhes. Recomendo procurar e ler documentação sobre este software; meu objetivo aqui é sugerir usos do git como ferramenta auxiliar em uma pesquisa, e não oferecer um tutorial completo sobre o seu uso.

A nuvem e os tipos de arquivos

Antes de mais nada, uma distinção técnica muito importante. Muitos dos arquivos de trabalho em sua pesquisa serão documentos escritos. Mas o formato destes arquivos tem um impacto direto sobre a maneira de armazená-los e editá-los em seu repositório.

Especificamente, em computação existem arquivos formato texto e arquivos em formatos binários. Os formatos binários atendem a muitos tipos diferentes de documentos: planilhas, vídeos, imagens, sons, … e alguns tipos de documentos escritos.

Por exemplo, um arquivo gravado em formato .txt (texto), .md (markdown) ou .tex (LaTeX) é um arquivo modo texto. Já um arquivo gravado em formato .doc, .docx (ambos da Microsoft Word) ou .pdf (Adobe) é um arquivo binário.

Todos os tipos de arquivos podem ser colocados em um repositório. Mas esta distinção se torna importante quando você decidir se vai trabalhar com seus arquivos diretamente na nuvem ou fora dela.

Manter arquivos de seu projeto em um repositório git oferece a possibilidade de trabalhar com eles no próprio repositório (diretamente no GitLab), ou em seu computador pessoal (sincronizando as mudanças).

Trabalhar diretamente no repositório é bastante simples, desde que você esteja trabalhando com arquivos modo texto. Este tipo de arquivo pode ser editado diretamente no GitLab; basta clicar o nome do arquivo e, a seguir, clicar no botão Edit.

Já arquivos binários podem ser armazenados no GitLab, mas não podem ser editados diretamente nele. Neste caso, é necessário fazer a edição fora da nuvem, e enviar a versão editada para o repositório. Não importa se é uma imagem .jpg ou um documento .docx; o GitLab não vai conseguir editá-los.

Para fazer o trabalho fora da nuvem – ou offline – há algumas operações do git que são relevantes, como mostro a seguir.

Operações comuns do git

Há um conjunto básico de operações do git, implementadas em todas as suas versões. Estas operações definem o fluxo de trabalho (workflow) com os repositórios. Vejamos:

clone serve para fazer uma cópia local (ou “clone”) do repositório em um computador pessoal

pull examina o repositório e atualiza uma cópia local

commit prepara o envio para o repositório de arquivos que foram editados localmente

push envia os arquivos preparados (committed) para o repositório

A partir destas operações, vamos ver como eu poderia dar os primeiros passos para usar o GitLab:

Crio o repositório no GitLab

Realizo uma operação clone para criar uma cópia local em meu computador (sim, uma cópia do repositório ainda vazio)

Copio no diretório local os arquivos da minha pesquisa, organizando-os como eu quiser (diretórios, nomes de arquivos, etc)

Realizo uma operação commit e preparo o envio destes arquivos para o repositório

Realizo uma operação push, que vai colocar no repositório todos os arquivos committed no passo 4

Se eu estiver trabalhando apenas no meu computador pessoal, vou repetindo os passos 4 e 5 sempre que eu realizar alterações.

Por outro lado, se eu fizer alterações diretamente no GitLab, ou se eu fizer alterações a partir de outro computador, a minha cópia local estará desatualizada. Neste caso, meu procedimento deverá ser o seguinte:

Realizo uma operação pull para atualizar a cópia local

Faço as edições em meus arquivos locais

Realizo uma operação commit e preparo o envio destes arquivos para o repositório

Realizo uma operação push, que vai colocar no repositório todos os arquivos committed no passo 4

Cada vez que realizo um commit, tenho que informar uma mensagem dizendo o que são aquelas alterações. Esta mensagem é para meu uso, e serve para que eu saiba o conteúdo daquelas alterações. Por exemplo, uma mensagem como “criação de arquivo” não serve de nada; mas uma mensagem como “criação do arquivo com as entrevistas na empresa em 15/04” é informativa o bastante para que eu saiba do que se trata.

Além disso, cada operação commit é registrada separadamente no repositório, e eu sempre posso consultar a lista de commits e recuperar qualquer versão do meu trabalho.

Mas ainda há uma possibilidade mais instigante com o git, que explico a seguir.

Branches

Todo repositório git tem um branch (“ramo”) principal, justamente chamado main. Mas é possível criar branches adicionais.

Quando se cria um novo branch de um repositório, o trabalho neste branch fica independente do main branch. Como usar isso?

Digamos que eu tenhomeus dados em uma planilha Excel, e quero experimentar diferentes métodos estatísticos A, B e C. Claro que eu poderia criar três pastas A, B e C, fazer três cópias de trabalho da planilha e fazer os testes nelas. Com o git, posso trabalhar de forma um pouco diferente.

Primeiro, crio um branch do meu repositório – por exemplo, teste-A. A seguir, passo a fazer as operações clone, pull, commit e push com o branch teste-A e não mais com o main.

A minha cópia local é inicialmente idêntica aos arquivos main, mas logo vai ficar diferente. a partir das modificações que eu fizer. Não faz mal: enquanto os meus pushes forem para o teste-A, nenhum dos artigos em main foi alterado. Essencialmente, o GitLab tem agora duas cópias diferentes do meu repositório.

Se eu chegar à conclusão que teste-A é um beco sem saída, posso arquivar ou apagar este branch e nada foi alterado em main.

Por outro lado, se eu gostar do resultado, posso fazer uma operação merge e combinar as alterações de teste-A com o main branch. Ou posso crar outros branches e fazer estas mesmas operações com eles.

Claro que este é um exemplo bastante simples. Mas a minha intenção é apenas mostrar como os branches de um repositório podem ser úteis para que um pesquisador crie caminhos alternativos de pesquisa, sem que os seus documentos e arquivos principais sejam afetados. Além disso, também nos branches toda a capacidade de controle de versões do git continua válida.

Issues

Como mencionei na primeira parte, um de meus requisitos é o de permitir acesso ao repositório por outras pessoas – como o meu orientador. Para isso, meu orientador precisa criar uma conta no GitLab e me informar o seu nome de usuário; com esta informação, autorizo o seu acesso ao meu repositório.

A possibilidade do meu orientador ler os meus arquivos de trabalho já é útil por si só, especialmente porque ele pode fazer isso quando quiser e tiver tempo disponível. Mas o git oferece uma possibilidade ainda mais útil.

Digamos que o meu orientador tenha uma crítica a fazer, após ler um de meus textos. Ele pode criar uma issue (“tema de discussão”), e escrever algo nela como “Recomendo revisar o capítulo de metodologia e ampliar a discussão sobre o método escolhido”. Na próxima vez que eu abrir o repositório, vou ver que uma issue foi criada em meu projeto, e vou ler a recomendação.

Posso usar isso como oportunidade para uma discussão, e responder à issue perguntando alguma coisa, e assim por diante.

Ou posso fazer a alteração pedida, responder na issue e encerrá-la.

Note que, neste caso, meu orientador não alterou qualquer de meus arquivos. Mas ele conseguiu dar a orientação necessária para que eu fizesse alterações. Melhor ainda: como tudo o que acontece no git, todas as mensagens ficam gravadas, mesmo depois que a issue é fechada.

Markdown

Como mencionei, acima, documentos em modo texto podem ser editados diretamente no repositório. Por exemplo, tipicamente um repositório inclui um arquivo chamado http://readme.md em seu diretório-raiz. A extensão .md indica que este é um arquivo markdown, uma forma especial do modo texto.

Um texto escrito em markdown tem comandos básicos de formatação. Por exemplo:

use dois asteriscos para indicar início e fim detexto em negrito, ou um asterisco para indicar início e fim detexto em itálico

inicie uma linha com # para indicar um título nível 1, ## para um título nível 2, etc.

Trabalhar em markdown é muito mais simples do que trabalhar em um arquivo do Microsoft Word: primeiro, porque o formato .md pode ser usado com facilidade em qualquer ambiente de trabalho – até em um celular. Segundo, porque trabalhar em markdown faz com que você se concentre no conteúdo de seu trabalho, e não na formatação – que deve ser a última coisa a ser feita, depois que você já tem a visão de conjunto de seu documento.

Um texto escrito em markdown pode ser convertido para o Microsoft Word, ou para LaTeX, ou mesmo para HTML, com facilidade – por exemplo, usando o programa pandoc. Mesmo que o seu formato final seja, por exemplo, .docx, você pode fazer todo o seu trabalho preliminar com documentos markdown e fazer a conversão apenas quando estiver preparando o documento final.

Se você acha que vale a pena aprender a usar markdown, faça uma pesquisa; há várias páginas na Internet com boas explicações a respeito.

Um exemplo

Criei um repositório público gitlab para exemplificar o que descrevi neste texto; você pode usá-lo como modelo para você criar o seu próprio repositório. Ele está disponível em https://gitlab.com/quartelmestre/repositorio-modelo.

Para encerrar

Seria possível falar muito mais sobre estes assuntos – seria possível escrever livros inteiros! Mas, como eu mencionei anteriormente, não é meu objetivo aqui ensinar a usar estas várias ferramentas, e sim apontar alguns de seus usos para um pesquisador.

Fique à vontade para fazer comentários, críticas, sugestões, perguntas, etc. Veja meus contatos na página inicial.