Usar Git no projeto de pesquisa significa registrar mudanças relevantes em textos simples, scripts, configurações e documentação para poder entender como o trabalho evoluiu. O sistema não substitui backup, armazenamento de dados, caderno de laboratório nem revisão acadêmica. Sua função é criar um histórico consultável: cada commit reúne um estado coerente dos arquivos, identifica autoria e permite comparar versões.
Comece pequeno. Instale o Git, defina nome e e-mail de autoria, transforme a pasta do projeto em repositório e faça um primeiro commit apenas quando a estrutura inicial estiver compreensível. Em vez de versionar tudo, separe o que deve ser acompanhado do que precisa ficar fora por tamanho, sigilo, licença ou geração automática.
Defina o que o repositório representa
Antes do primeiro comando, descreva o escopo. O repositório pode conter scripts de coleta e análise, documentos em Markdown ou Quarto, arquivos de configuração, dicionários de dados, protocolos e instruções de reprodução. Essa seleção deve permitir que outra pessoa entenda o método sem expor dados pessoais nem materiais que a equipe não pode redistribuir.
Arquivos binários grandes, bases brutas sensíveis, credenciais, resultados temporários e pastas geradas automaticamente costumam exigir outro destino. Guarde dados restritos em ambiente autorizado e documente como obtê-los ou por que não podem ser compartilhados. Quando um conjunto público possui DOI, registre o identificador no README em vez de duplicar gigabytes dentro do Git.
Git e uma plataforma remota também são coisas diferentes. Git controla versões localmente. GitHub, GitLab e serviços equivalentes hospedam cópias, facilitam colaboração e podem executar automações. Um repositório enviado à nuvem continua sem ser um plano completo de preservação; mantenha backup institucional ou outro mecanismo definido pelo projeto.
Crie uma estrutura simples antes do histórico
Organize pastas por função, com nomes estáveis e sem depender do computador de uma pessoa. Um projeto pode separar data, scripts, docs, results e references, mas a estrutura precisa refletir o fluxo real. Se os dados brutos não entram no Git, a pasta pode conter apenas um arquivo explicando sua origem, seu esquema e as regras de acesso.
Inclua um README com objetivo, responsáveis, requisitos, ordem de execução e localização dos dados. Acrescente um arquivo de licença quando a equipe tiver autoridade para licenciar o conteúdo. Para software próprio, um CITATION.cff informa como citar a versão publicada. Esses arquivos transformam uma sequência de commits em um objeto que outras pessoas conseguem interpretar.
Crie também .gitignore antes de adicionar arquivos. O GitHub mantém modelos de gitignore para linguagens e ambientes comuns, mas eles são ponto de partida, não resposta automática. Revise cada regra e acrescente saídas, caches, ambientes locais, credenciais e dados excluídos pelo protocolo.
Faça commits pequenos, coerentes e explicativos
Um commit deve responder o que mudou e por quê. “Ajusta recodificação de respostas ausentes” informa mais que “alterações”. Reúna mudanças relacionadas: modificação no script, teste correspondente e atualização da documentação podem pertencer ao mesmo commit; correção de análise e reformulação completa da introdução provavelmente merecem registros distintos.
Antes de confirmar, examine o status e a diferença. Essa revisão evita incluir arquivo temporário, dado restrito ou alteração acidental. Depois, escreva a mensagem no imperativo ou em outro padrão consistente adotado pela equipe. O importante é permitir que alguém percorra o histórico e reconheça decisões metodológicas, correções e pontos de transição.
Não espere semanas para criar um único commit gigante. Registre estados funcionais ao concluir unidades pequenas de trabalho. Ao mesmo tempo, evite commits a cada tecla ou arquivos que não abrem. O histórico é mais útil quando cada ponto representa uma mudança inteligível e, sempre que possível, verificável.
Use branches para mudanças que precisam de revisão
Uma branch separa uma linha de trabalho da versão principal. Use-a para testar novo método, reorganizar dados derivados, escrever uma seção extensa ou preparar uma correção que outra pessoa revisará. O nome pode indicar ação e assunto, como ajusta-modelo-regressao, sem incluir nomes ou informações sensíveis.
Ao terminar, compare a branch com a principal, execute testes e revise resultados. Em plataformas colaborativas, uma solicitação de incorporação permite discutir a mudança antes do merge. Isso é especialmente útil quando uma alteração afeta critérios de exclusão, transformação de variáveis, parâmetros de análise ou conclusões apresentadas no relatório.
Branches não substituem versões publicadas. Quando o projeto alcança um estado usado em manuscrito, relatório ou depósito, crie uma tag ou release identificável. A tag conecta o resultado a um ponto específico do histórico; o depósito preservado e o DOI dão persistência à versão distribuída.
Mantenha dados, segredos e arquivos gerados fora do Git
O .gitignore impede que arquivos ainda não rastreados sejam adicionados por engano. Ele não remove um segredo que já entrou no histórico. Se uma senha, chave ou dado pessoal foi commitido, trate como incidente: revogue a credencial, avalie a exposição e siga o protocolo institucional. Apagar o arquivo na versão atual não apaga automaticamente as versões anteriores.
Dados pessoais ou sigilosos só devem entrar quando houver base ética, jurídica e técnica, com controle de acesso compatível. Na maioria dos projetos, o repositório de código guarda instruções, esquema, dados sintéticos ou uma amostra anonimizada autorizada, enquanto a base real permanece em ambiente protegido. Consulte também as exigências do comitê de ética e do plano de gestão de dados.
Resultados recriáveis, como gráficos exportados e tabelas intermediárias, podem ser gerados pelo fluxo de análise em vez de armazenados a cada execução. A decisão depende do custo de reprodução e da necessidade de revisão. Documente o comando ou a sequência que os produz e defina quais saídas finais devem acompanhar uma release.
Conecte o histórico às decisões da pesquisa
Git registra diferenças nos arquivos, mas não explica sozinho o significado científico de cada escolha. Associe mudanças relevantes a issues, notas de decisão, protocolo, diário de campo ou documentação metodológica. Se um critério de inclusão mudou, registre a justificativa, a data e o impacto, não apenas a linha alterada no script.
Uma rotina segura pode seguir esta ordem:
- atualizar a cópia local e confirmar a branch de trabalho;
- modificar uma unidade coerente, executar verificações e revisar as diferenças;
- remover arquivos indevidos, confirmar o status e criar um commit descritivo;
- enviar a branch, solicitar revisão quando necessário e incorporar a mudança aprovada;
- marcar a versão efetivamente usada em produtos acadêmicos e preservar a release.
O manual oficial do Git explica o modelo de objetos, branches, histórico e recuperação. Para operações específicas, consulte a documentação da versão instalada e pratique em um repositório descartável antes de reescrever histórico compartilhado.
Verifique se outra pessoa consegue recuperar o projeto
Faça um teste em uma pasta vazia ou em outro computador autorizado. Clone o repositório, siga o README, instale dependências e execute uma etapa representativa. Verifique se caminhos absolutos, arquivos locais esquecidos ou configurações invisíveis impedem a reprodução. O teste demonstra se o histórico contém contexto suficiente, não apenas se os arquivos foram enviados.
Confirme também se a versão marcada corresponde ao manuscrito. Registre a tag, o hash do commit ou o DOI do release nos materiais de pesquisa quando isso ajudar a rastreabilidade. Se o relatório mudou depois da análise, explique a relação entre versões para não produzir uma falsa equivalência.
Um bom uso de Git torna mudanças auditáveis e reduz a dependência de arquivos chamados “final”, “final2” e “agora-vai”. O benefício aparece quando o repositório permanece compreensível: escopo definido, arquivos adequados, commits coerentes, revisões documentadas e versões publicadas. Essa disciplina não garante uma pesquisa correta, mas oferece evidências claras de como ela foi construída.
