Git contra «versão_final_v3_revisada.docx»: um histórico completo, com autor, data e motivo de cada mudança
Git é um sistema de controle de versão distribuído, livre e de código aberto (GPLv2), segundo git-scm.com/about — o site cita uma pesquisa de 2022 em que «96% dos desenvolvedores profissionais usam Git», e o histórico do kernel Linux (1,4 milhão de commits) ocupa 5,5 GB. Para a pesquisa, o que importa é outra coisa: cada commit guarda quem mudou, quando, o quê e por quê.
texto_v1.docx,texto_v2.docx,texto_final.docx,texto_final_REVISADO.docx…- Ninguém sabe o que mudou entre duas cópias, nem quem mudou
- Dois autores editando: uma cópia sobrescreve a outra
- O backup é a última cópia que alguém lembrou de fazer
- Um único
main.tex; o histórico fica em.git/ git loglista cada versão com autor, data e mensagem;git diffmostra linha a linha o que mudou- Cada autor trabalha na sua cópia; o Git combina as mudanças e aponta os conflitos
git pushleva o histórico inteiro para o GitHub, o GitLab ou o servidor da instituição
O Git versiona texto: .tex, .md, .csv, .py, .R, .bib. Um .docx ou um PDF entra, mas o Git só sabe dizer que «mudou», não o quê — o Turing Way é direto: não é ferramenta para versionar binários. Quem escreve em LaTeX (manual irmão) ganha o diff por linha de graça.
Git × GitHub × GitLab: a ferramenta no seu computador e os serviços que hospedam o repositório
| Nome | O que é | Onde roda · custo |
|---|---|---|
| Git | O programa de controle de versão: cria o repositório, registra commits, compara versões, combina branches. Funciona sem internet e sem conta | No seu computador · gratuito (GPLv2); versão 2.55.0 |
| GitHub | Serviço que hospeda repositórios Git e soma interface web, issues, pull requests, Actions, Pages, Codespaces, «Cite this repository» e a integração com o Zenodo | Na nuvem · Free (US$ 0), Team (US$ 4/usuário/mês), Enterprise (US$ 21) |
| GitLab | Alternativa com o mesmo Git por baixo: gerenciamento de código e CI/CD; muitas universidades hospedam uma instância própria | Na nuvem ou na instituição · Gratuito (US$ 0), Premium (US$ 29/usuário/mês, anual), Ultimate (sob consulta) |
| Codeberg | Plataforma comunitária citada pelo Turing Way como alternativa | Na nuvem |
Aprenda o Git, não o GitHub: tudo o que este manual faz no terminal funciona igual com GitLab, Codeberg ou um servidor da instituição. O GitHub é a escolha deste manual porque é o mais usado, tem documentação em português e liga-se ao Zenodo para o DOI (Parte 4) — mas o repositório é seu e pode ser levado para outro serviço com um git push.
Local é o repositório na sua máquina; remoto é a cópia no serviço (por convenção chamada origin). git push envia commits do local para o remoto; git pull traz os do remoto; git clone cria um local a partir de um remoto.
Instalar e configurar: Git 2.55.0 para Windows, macOS e Linux; user.name e user.email uma vez por máquina
brew install git) ou Xcode Command Line Tools; Linux: apt install git, dnf install git.
git --version # confere a instalação (nesta máquina: 2.48.1) git config --global user.name "Aluna Exemplo" # o nome que vai em cada commit git config --global user.email "aluna@universidade.br" git config --global --list # confere o que ficou gravado
Nome e e-mail vão para o histórico de todos os commits e aparecem no GitHub: use o nome com que você assina os artigos e um e-mail que continue seu depois do curso. O VS Code exige essas duas configurações e Git ≥ 2.0.0 para funcionar (slide «GitHub Desktop e VS Code»).
A demonstração deste manual rodou com Git 2.48.1; nenhum comando aqui exige a versão mais nova (2.55.0). O git init -b main (Parte 2) cria o repositório já com o branch main, sem depender de configuração.
Começar um repositório: git init, git status, git add e o primeiro git commit
/home/usuario): git init -b main responde «Repositório vazio Git inicializado em /home/usuario/minha-pesquisa/.git/»; git status --short lista quatro itens com ?? (não rastreados); git add e git commit -m produzem [main (root-commit) 3b95655] … 4 files changed, 25 insertions(+); git log --oneline mostra o commit.git init -b mainNa pasta do projeto: cria a pasta oculta .git/ e o branch main. Uma vez por projetogit status --short?? = arquivo que o Git ainda não rastreia; M = modificado; A = adicionado à área de preparaçãogit add …Coloca os arquivos escolhidos na área de preparação (staging): o que o próximo commit vai incluirgit commit -m "…"Registra a versão com a mensagem; o código 3b95655 é o identificador do commitNomeie os arquivos no git add (como na figura: README.md .gitignore 06_texto/main.tex 01_buscas/BUSCA.csv) até o .gitignore estar pronto (slide seguinte); só então git add -A é seguro. Sempre git status antes de git commit: é a lista do que vai entrar.
root-commit é o primeiro commit do repositório; create mode 100644 é o modo de arquivo normal (sem permissão de execução). Os identificadores (3b95655) são únicos por repositório: os seus serão diferentes.
.gitignore: o que o Git deve fingir que não existe — com os modelos oficiais para TeX, Python e R
TeX.gitignore, Python.gitignore e R.gitignore. Copie o conteúdo do que serve para o seu projeto para o .gitignore na raiz.# dados brutos, pessoais ou licenciados: nunca dados_FORA_DO_GIT/ # segredos .env *.pem # gerados pelo LaTeX *.aux *.log *.bbl *.blg *.out *.toc *.synctex.gz # gerados pelo Python e pelo R __pycache__/ .Rhistory .ipynb_checkpoints/
git rm --cached .env # tira do Git; o arquivo continua na pasta echo ".env" >> .gitignore # e passa a ser ignorado git commit -m "Tira o .env do Git (a chave foi trocada)"
O .gitignore fica na raiz do repositório e entra no primeiro commit (como na Figura 5). Um padrão vale para toda a árvore; pasta/ ignora a pasta inteira. Para ignorar algo em todos os repositórios da máquina (arquivos do editor, do sistema), o arquivo é ~/.config/git/ignore. O gerador gitignore.io monta um arquivo a partir de várias ferramentas.
Branch, diff, merge e tag: uma linha paralela para a revisão do capítulo, de volta ao main, e uma tag por marco
/home/usuario): git switch -c revisao-capitulo-2 cria e entra no branch; git diff mostra a linha removida (-, em vermelho) e as acrescentadas (+, em verde); git commit -am; git switch main; git merge revisao-capitulo-2 responde «Fast-forward»; git tag -a v0.1-qualificacao -m "…"; e git log --oneline --graph --decorate mostra HEAD -> main, tag: v0.1-qualificacao.| Comando | O que faz |
|---|---|
git switch -c nome | Cria um branch e muda para ele; os commits seguintes ficam nessa linha, sem tocar o main |
git diff | Compara o arquivo no disco com o último commit: - saiu, + entrou |
git commit -am "…" | Adiciona todos os arquivos já rastreados que mudaram e faz o commit (arquivos novos ainda precisam de git add) |
git switch main → git merge nome | Volta ao main e traz os commits do branch. «Fast-forward»: o main só avançou, porque ninguém mexeu nele enquanto isso |
git tag -a v0.1-qualificacao -m "…" | Tag anotada (com autor, data e mensagem) no commit atual: o marco «versão entregue à qualificação» |
Uma tag por marco que alguém pode pedir de volta: qualificação, submissão do artigo, versão que gerou os resultados, defesa. Use sempre -a e -m: é a tag anotada que carrega a mensagem e que o git push --follow-tags envia (Parte 3). Branch para trabalhar sem medo — um capítulo em revisão, uma análise alternativa — e merge quando ficar bom.
Quem trabalha sozinho pode viver no main com commits e tags. O branch começa a valer quando há um orientador ou colega editando ao mesmo tempo, ou quando você quer testar algo que talvez não fique.
Para aprofundar: o Pro Git em português (gratuito) e a oficina Version Control with Git do Software Carpentry
| Depois deste manual, leia | Para |
|---|---|
| Pro Git, «Fundamentos do Git» | Tudo sobre status, add, commit, log, diff, desfazer e tags |
| Pro Git, «Ramificação» | Branches e merges com desenhos; conflitos com calma |
| Pro Git, «GitHub» | Conta, fork, pull request, organização |
| Software Carpentry, episódios 1 a 9 | A mesma sequência da Parte 2, com exercícios; «Remotes in GitHub» e «Collaborating» cobrem a Parte 3 |
| Software Carpentry, «Open Science», «Licensing», «Citation» | O que a Parte 4 deste manual faz com licença, CITATION.cff e DOI |
Quando um comando deste manual não bastar, a resposta está no Pro Git — em português, gratuito e mantido pelo próprio projeto Git. Prefira-o a respostas soltas em fóruns: elas costumam trazer o reset --hard e o force push como se fossem inofensivos.
O episódio suplementar «Using Git from RStudio» mostra a aba Git do RStudio para quem trabalha em R; os comandos são os mesmos.
Conta e planos: o GitHub Free basta para a pesquisa — e o Student Developer Pack dá o Pro a estudantes verificados
| Plano | Preço | O que inclui (github.com/pricing, 09/09/2026) |
|---|---|---|
| Free | US$ 0 | Repositórios públicos e privados ilimitados; colaboradores ilimitados; 2.000 minutos de GitHub Actions por mês; 500 MB no Packages; 120 horas-núcleo e 15 GB de Codespaces por mês; GitHub Pages em repositórios públicos; alertas do Dependabot; suporte da comunidade |
| Team | US$ 4 por usuário/mês | 3.000 minutos de Actions; 2 GB de Packages; revisores obrigatórios, branches protegidas, code owners; suporte por e-mail/web |
| Enterprise | US$ 21 por usuário/mês | 50.000 minutos; 50 GB; SAML SSO; SLA de 99,9% |
| Pro (individual) | gratuito no Student Developer Pack | Não aparece em destaque na página de preços; vem com o pacote de estudante |
Crie a conta gratuita em github.com com o e-mail que você configurou no Git (slide «Instalar e configurar») e um nome de usuário que continue fazendo sentido depois do curso: ele entra na URL do repositório, no CITATION.cff e no DOI. Este manual não cria conta nem faz login: a senha é digitada só na página do GitHub.
A página de preços mostra dólares; o manual não converte nem afirma promoções. O Student Developer Pack exige verificação de estudante feita pelo GitHub — a página não detalha os documentos.
Criar o repositório e o «Olá, Mundo»: «+» → «Novo repositório» → nome → «Criar repositório»; depois branch, edição, pull request e merge
hello-world, o branch readme-edits, edita o README, abre e mescla uma solicitação de pull — tudo pelo navegador.hello-world no tutorial; minha-pesquisa aqui), descrição, Público ou Privado, «Adicionar um arquivo LEIAME» → «Criar repositório»readme-edits → «Criar branch: readme-edits a partir do main»Para o projeto de pesquisa que já existe no seu computador (Parte 2), crie o repositório no GitHub sem «Adicionar um arquivo LEIAME» e sem .gitignore: o histórico vem do git push (slide seguinte). O «Olá, Mundo» é para entender a interface — faça-o uma vez, num repositório de teste.
Privado enquanto o texto está em construção, se preferir; público quando for citar ou pedir o DOI — o Zenodo só arquiva repositórios públicos (Parte 4). Dado pessoal não entra em nenhum dos dois.
Remoto e push: git remote add origin e git push -u origin main --follow-tags levam o histórico e as tags para o GitHub
/home/usuario): salvar_versao.sh faz o commit e a tag v0.2 (Parte 5); checar_repo.py devolve «0 bloqueio(s), 1 aviso(s)» — o aviso é «nenhum remoto configurado»; git remote add origin e git push -u origin main --follow-tags respondem * [new branch] main -> main, * [new tag] v0.1-qualificacao, * [new tag] v0.2 e «branch 'main' set up to track 'origin/main'». O remoto aqui é um repositório bare local (../remoto-demonstracao.git), porque nenhum repositório foi criado no GitHub para a demonstração; no GitHub, a URL é https://github.com/<usuário>/<repo>.git.git remote add origin https://github.com/<usuário>/minha-pesquisa.git git push -u origin main --follow-tags # primeira vez: -u grava o vínculo; --follow-tags envia as tags anotadas # das próximas vezes, na pasta do projeto: git push # envia os commits novos git push --follow-tags # commits e tags novas git pull # traz o que mudou no GitHub (edições pelo navegador, colegas)
Ao fim de cada sessão: git status → commit → git push. Só depois do push o repositório existe em dois lugares — até lá, o checar_repo.py avisa: «o backup só existe nesta máquina». A URL do remoto se lê com git remote -v.
No primeiro push o Git pede que você se autentique no GitHub: siga o que a tela mostrar (a documentação de autenticação está em docs.github.com/pt). Nunca cole uma credencial em script, em arquivo versionado nem neste manual — o checar_repo.py procura exatamente esse tipo de conteúdo antes do push.
A página de um repositório real: árvore de arquivos, README renderizado, «About», releases, linguagens — e o arquivo aberto
README.md do mesmo repositório aberto no navegador (captura de 09/09/2026): qualquer arquivo de texto pode ser lido, editado e ter o histórico consultado pela interface.| Elemento | O que é |
|---|---|
| Árvore de arquivos | As pastas e arquivos do último commit do branch escolhido; ao lado, a mensagem do commit que mexeu em cada um |
| README | Renderizado logo abaixo da árvore: é a «capa» do projeto (slide «README») |
| «About» | Descrição, site e tópicos; edita-se pela engrenagem ao lado |
| «Releases» | Versões publicadas com notas e anexos (Parte 4); vazio até a primeira |
| «Languages» | Proporção de cada linguagem, calculada pelos arquivos |
| Abas | Commits, issues, pull requests, Actions e configurações — aparecem nos slides seguintes |
A página do repositório é o que um revisor, um colega ou um avaliador vê primeiro. Três coisas a fazem legível: um README que diga o que o projeto é e como reproduzir, um LICENSE e um CITATION.cff — os três estão na Parte 4 e os três são o que o checar_repo.py cobra.
O grafo de rede do repositório, que desenha branches e forks, devolveu uma página de erro nas tentativas sem login em 09/09/2026 e não aparece neste manual.
Commits e GitHub Actions: o histórico na web e um workflow que confere o repositório a cada push (integração contínua)
git log na web — mensagem, autor, data e identificador; cada linha abre o diff daquele commit.
verificar.yml) rodou a cada push — o GitHub executou um script de conferência numa máquina virtual e registrou o resultado.name: verificar
on: [push, pull_request]
jobs:
checar:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: python3 scripts/checar_repo.py .| Termo | O que é |
|---|---|
| CI (integração contínua) | Rodar conferências e testes automaticamente a cada commit enviado |
| GitHub Actions | O serviço de CI do GitHub: arquivos YAML em .github/workflows/; 2.000 minutos por mês no plano Free |
| Workflow | Um arquivo YAML: quando rodar (on), em que máquina (runs-on) e os passos (steps) |
| Status | Verde ou vermelho ao lado de cada commit e em cada pull request |
Para a pesquisa, um workflow que rode a auditoria (checar_repo.py) e, se houver, os testes do código já vale: um push com segredo ou com arquivo grande fica vermelho antes de alguém clonar. Compilar o LaTeX ou reexecutar a análise no Actions é o passo seguinte, quando o projeto estabilizar.
Issues e pull requests: a lista de tarefas do projeto e a proposta de mudança com revisão
| Na pesquisa | Use assim |
|---|---|
| Issue como tarefa | «Refazer a Tabela 3 com os dados de 2025», «Conferir a NBR 6023 nas referências» — numerada, atribuída, fechada quando resolvida; o commit pode citar «#12» |
| Issue como dúvida do orientador | Um comentário por trecho, fora do e-mail, com histórico |
| Pull request | O branch revisao-capitulo-2 vira uma PR: o orientador lê o diff, comenta linha a linha, e o merge acontece na web |
| Sozinho no projeto | Issues ainda valem como lista de pendências; a PR é opcional — o merge local (Figura 7) faz o mesmo |
Issues e pull requests são públicas num repositório público: nada de dado de participante, nem de nome de avaliador, nem de trecho de artigo de base paga nos comentários. O que precisa ficar restrito fica no repositório privado ou fora do GitHub.
Para colaborar num repositório de outra pessoa sem permissão de escrita, faz-se um fork (cópia na sua conta), trabalha-se num branch e abre-se a pull request de volta — é como se contribui para pacotes de código aberto.
Sem terminal: o GitHub Desktop e a visão «Source Control» do VS Code fazem os mesmos commits e pushes
| Ferramenta | Vantagens | O que saber |
|---|---|---|
| GitHub Desktop | Tudo por botões; diff visual; integra a conta do GitHub | Windows e macOS; código aberto sob MIT; release 3.6.5 |
| VS Code | O editor onde você já escreve o .tex ou o .py; staging por arquivo ou por trecho; troca de branches; gráfico de commits e Timeline por arquivo; extensão «GitHub Pull Requests and Issues» para revisar PRs no editor | Exige Git ≥ 2.0.0 instalado e user.name/user.email configurados; há geração de mensagem de commit por IA |
Interface gráfica e terminal fazem a mesma coisa no mesmo repositório: use o VS Code no dia a dia e o terminal quando precisar de um comando que o botão não tem (tags anotadas, rm --cached, os scripts da Parte 5). Aprender os comandos primeiro (Parte 2) é o que faz os botões fazerem sentido.
A página do GitHub Desktop não lista plataformas; o repositório distribui para Windows e macOS. No Linux, o VS Code, o terminal e a GitHub CLI cobrem tudo.
GitHub CLI (gh) e Codespaces: o GitHub no terminal e um computador de desenvolvimento no navegador
brew install gh, WinGet, apt/dnf/zypper; versão v2.100.0 (03/09/2026). Nesta máquina: gh 2.46.0.
gh repo create minha-pesquisa --private --source=. --push # cria o repositório no GitHub a partir da pasta e faz o push gh issue create --title "Refazer a Tabela 3" # abre uma issue gh pr create # abre a pull request do branch atual gh release create v0.2 --notes "Repositório pronto para publicar" # publica uma release (Parte 4)
A CLI é o caminho mais curto de «pasta no computador» para «repositório no GitHub» sem clicar em formulário — e o que o plugin da Parte 5 usa quando o aluno pede para criar o repositório ou a release. Confira cada comando na página do manual antes de rodar: a sintaxe acima é a da documentação, não foi executada na demonstração.
Serve para rodar um script ou compilar o LaTeX num computador emprestado, sem instalar nada: o repositório abre num VS Code no navegador. A cota gratuita mensal (120 horas-núcleo, 15 GB) acaba; não é lugar para dados sensíveis, que não devem estar no repositório de qualquer forma.
GitHub Pages: um site estático a partir do repositório — a página do projeto, a documentação, o manual
| Item (docs, 09/09/2026) | Valor |
|---|---|
| Site de usuário | Repositório <owner>.github.io → https://<owner>.github.io; um por conta |
| Site de projeto | https://<owner>.github.io/<repo>; um por repositório |
| Domínio próprio | Opcional |
| Limites | Repositório recomendado ≤ 1 GB; site ≤ 1 GB; largura de banda flexível de 100 GB/mês; 10 builds por hora (salvo com Actions próprio) |
| Proibido | Uso comercial e e-commerce; envio de senhas ou cartões; os IPs dos visitantes são registrados |
Para a pesquisa, o Pages publica a página do projeto (o README com um índice), a documentação de um pacote ou um relatório em HTML. Dados de participantes e resultados sob embargo não entram: o site é público e o repositório também. Um formulário de coleta de dados no Pages viola a regra de não receber senhas ou cartões e, mais importante, a LGPD.
A ativação fica nas configurações do repositório, que exigem login e não foram capturadas: consulte «O que é o GitHub Pages?» e os guias vizinhos em docs.github.com/pt.
Arquivos grandes e Git LFS: 50 MiB avisa, 100 MiB bloqueia — e o LFS guarda o conteúdo fora do histórico
git lfs install # uma vez por máquina (Windows: instalador; macOS: brew install git-lfs; Linux: PackageCloud ou tarball) git lfs track "*.psd" # ou "*.mp4", "dados/*.parquet": grava a regra em .gitattributes git add .gitattributes git add dados/amostras.parquet # commit e push normais: o Git guarda o ponteiro, o LFS o conteúdo git commit -m "Amostras via LFS"
| Git LFS no GitHub (docs de cobrança) | Valor |
|---|---|
| Free e Pro | 10 GiB de armazenamento e 10 GiB de largura de banda |
| Team e Enterprise Cloud | 250 GiB |
| Excedente | Cobrado por GiB baixado e por hora de armazenamento (calculadora de preços do GitHub) |
Antes do LFS, pergunte se o arquivo precisa estar no repositório: dado bruto grande pertence a um repositório de dados (OSF, Zenodo, o da instituição) com DOI, e o Git guarda o script que o lê. O LFS é para o que precisa acompanhar o código e cabe na cota. Um arquivo acima de 100 MiB já commitado bloqueia o push: tire-o do histórico antes de enviar — o checar_repo.py e o salvar_versao.sh recusam esses arquivos.
Overleaf: a integração Git e o GitHub Synchronization são recursos premium — no plano gratuito, «Download → Source» e commit local
https://git.overleaf.com/<ID_DO_PROJETO>, com autenticação por token criado nas configurações da conta.| Recurso | Como (conforme a documentação) | Plano |
|---|---|---|
| Git integration | Menu → Sync → Git; clonar https://git.overleaf.com/<ID_DO_PROJETO> com o token; o branch chama-se main; não suporta branches, Git LFS, tags nem submodules; symlinks viram arquivos | premium |
| GitHub Synchronization | Liga um projeto Overleaf a um repositório GitHub e os mantém sincronizados | premium (Overleaf Cloud) |
| Plano gratuito | «Download → Source» (zip) → descompactar na pasta do repositório local → git add, git commit, git push | gratuito |
No gratuito, o Overleaf é o editor e o Git é o histórico: baixe o «Source» ao fim de cada sessão de escrita, faça o commit e o push. As tags por marco (qualificação, defesa) só existem no Git — a integração premium do Overleaf não as suporta. O manual irmão de LaTeX detalha o editor e os planos.
O token do Overleaf é uma credencial: fica no gerenciador de credenciais do Git ou é digitado a cada clone — nunca num arquivo do repositório.
README: o que o projeto faz, por que é útil, como começar, onde obter ajuda e quem mantém — em Markdown, na raiz
.github/, na raiz ou em docs/ (nessa ordem); gera um sumário automático; acima de 500 KiB o arquivo é truncado; um README num repositório com o nome do usuário aparece no perfil.# Manutenção preditiva em guindastes portuários: dados e scripts Scripts e dados derivados da dissertação «…» (versão 0.2, set. 2026). ## O que há aqui - `01_buscas/` — diário de busca e estratégias por base - `06_texto/` — o texto em LaTeX - `scripts/` — `checar_repo.py`, `citacao_cff.py`, `salvar_versao.sh` ## Como reproduzir 1. `git clone https://github.com/<usuário>/minha-pesquisa.git` 2. `python3 scripts/checar_repo.py .` ## Dados Os dados brutos não estão neste repositório (LGPD); os derivados estão em `dados/` sob CC BY 4.0. Contato: e-mail institucional. ## Como citar Veja `CITATION.cff` ou o botão «Cite this repository». ## Licença CC BY 4.0 (texto e dados) — ver `LICENSE`.
Cinco perguntas, na ordem da documentação: o que faz, por que é útil, como começar, onde obter ajuda, quem mantém. Um README que diz onde os dados estão (e por que não estão aqui) evita a issue mais comum de um revisor. O checar_repo.py avisa quando o README falta.
Licença: sem um arquivo LICENSE ninguém pode reutilizar legalmente — MIT, GPLv3 ou Apache 2.0 para código; CC BY 4.0 para dados e texto
| Licença | Para | O que permite (choosealicense.com) |
|---|---|---|
| MIT | Código | Curta e direta; quase tudo, inclusive versões fechadas; exige manter o aviso de copyright |
| GNU GPLv3 | Código | O mesmo, exceto distribuir versões fechadas: quem redistribui precisa abrir o código |
| Apache 2.0 | Código | Permissiva; listada na página de licenças do site — leia o texto antes de escolher |
| CC BY 4.0 | Dados, texto, figuras | «My project isn't software»: uso, cópia e adaptação com atribuição — a licença desta série |
| Nenhuma | — | «I don't want to choose a license»: sem licença, ninguém pode legalmente reutilizar, mesmo com o repositório público |
Um arquivo LICENSE na raiz com o texto integral da licença (copie de choosealicense.com — na demonstração, a CC BY 4.0 veio do repositório github/choosealicense.com). Código e dados no mesmo repositório podem ter licenças diferentes: diga no README qual vale para o quê. Licença é condição para o DOI pelo Zenodo (slide «DOI pelo Zenodo»).
A escolha depende do programa, do financiador e de coautores; dados de terceiros e artigos de bases pagas têm licença própria e não entram no repositório. Em dúvida, pergunte à instituição.
CITATION.cff: um arquivo na raiz e o GitHub mostra «Cite this repository», com APA e BibTeX prontos
CITATION.cff na raiz, a barra lateral do repositório ganha o botão «Cite this repository», com exportação em APA e BibTeX; preferred-citation aponta para o artigo quando se quer que citem o artigo, não o software.
cffconvert, para BibTeX, RIS e CodeMeta); o arquivo é lido pelo GitHub, pelo Zenodo e pelo Zotero.cff-version: 1.2.0
message: "Se você usar este software ou material, cite-o como abaixo."
title: "Manutenção preditiva em guindastes portuários: dados e scripts"
version: "0.1"
date-released: 2026-09-09
authors:
- family-names: "Exemplo"
given-names: "Aluna"
url: "https://github.com/aluna/minha-pesquisa"
license: CC-BY-4.0| Campo | O que é |
|---|---|
cff-version | Versão do formato: 1.2.0 |
message | O pedido de citação que o leitor vê |
authors | Lista com family-names e given-names (e, se houver, orcid) |
title · version | Título e versão citadas; date-released, url, license e doi completam |
preferred-citation | Quando há artigo: os metadados do artigo, para que o botão cite o artigo |
Um CITATION.cff por repositório, na raiz, atualizado a cada release (versão, data e, depois do Zenodo, o DOI). O Zenodo lê o arquivo para preencher os metadados do registro; o Zotero o importa. O citacao_cff.py (Parte 5) gera o arquivo e imprime o BibTeX e a referência ABNT para conferir com a biblioteca.
cffinit: o formulário web que monta ou atualiza o CITATION.cff sem escrever YAML à mão
CITATION.cff existente para editar. O formulário guia campo a campo e entrega o arquivo pronto para salvar na raiz do repositório.family-names, given-names), versão, data, licença, URL, DOI se já houverCITATION.cff gerado; salve na raiz do repositóriogit add CITATION.cff → commit → push; o botão «Cite this repository» aparece| Ferramenta | Quando |
|---|---|
| cffinit (web) | Primeira vez, ou para quem prefere formulário; valida o arquivo |
citacao_cff.py (Parte 5) | Pelo terminal, com BibTeX e ABNT impressos; recusa sobrescrever sem --forcar |
cffconvert (cff-converter-python) | Converter o .cff para BibTeX, RIS ou CodeMeta |
Os autores do CITATION.cff são os autores do repositório (quem escreveu o código e organizou os dados), não necessariamente os do artigo — para o artigo há o preferred-citation. Use o ORCID de cada autor: é o que liga o DOI do Zenodo ao perfil.
Releases: «Versões» → «Rascunho de uma nova versão» → tag → título → notas → «Publicar versão» — cada release traz ZIP e tar.gz do código
| Passo (docs, 09/09/2026) | O que fazer |
|---|---|
| «Versões» → «Rascunho de uma nova versão» | Na página do repositório |
| «Escolher uma marca» | A tag anotada que você enviou com --follow-tags (v0.2), ou uma nova criada ali |
| «Título da versão» · «Descrever esta versão» | O que mudou desde a anterior; o botão «Gerar notas de lançamento» escreve as notas automaticamente |
| Anexos | Opcionais: o PDF da dissertação, uma planilha de resultados |
| «Publicar versão» | A release fica pública; se o Zenodo estiver ligado, o DOI é emitido (slides seguintes) |
Uma release por marco citável: a versão do código que gerou os resultados do artigo, a versão depositada com a dissertação. A tag no Git (Parte 2) é o ponto fixo; a release é a tag com nome, notas e anexos — e é ela que o Zenodo arquiva. «Este é um pré-lançamento» serve para versões em revisão.
gh release create v0.2 --notes "…" (GitHub CLI) faz o mesmo sem abrir o navegador.
DOI pelo Zenodo: repositório público, com licença, ligado à conta — e cada release ganha um DOI
| Condição | Por quê |
|---|---|
| Repositório público | O Zenodo só arquiva o que pode ler; um repositório privado não recebe DOI por esta via |
| Arquivo LICENSE | É a segunda condição da documentação do GitHub: o registro arquivado precisa dizer sob que termos pode ser reutilizado |
| Conta no Zenodo ligada ao GitHub | «Entrar com GitHub» → «Autorizar Zenodo»: é o que permite ao Zenodo ver as releases |
| Uma release | O DOI é emitido por release, não por commit; a primeira release depois de «Ativado» gera o primeiro DOI |
Ordem: LICENSE e CITATION.cff no repositório → repositório público → ligar no Zenodo → release. O CITATION.cff (ou um .zenodo.json) preenche os metadados do registro — título, autores com ORCID, licença — e evita corrigir à mão no Zenodo depois. Depois do DOI, coloque-o no CITATION.cff e no README.
Limites de tamanho por registro no Zenodo não foram conferidos nesta data e não aparecem no manual. Telas logadas do Zenodo não foram capturadas: os nomes de botão são os da documentação do GitHub em português e de help.zenodo.org.
DOI pelo Zenodo, passo a passo: perfil → GitHub → «Sync now» → ligar o controle deslizante → publicar a release
CITATION.cff ou .zenodo.json; integração com o Software Heritage.| Depois do DOI | Onde colocar |
|---|---|
CITATION.cff | Campo doi; commit → a próxima release já nasce com ele nos metadados |
| README | Na seção «Como citar» |
| Artigo ou dissertação | Na seção de disponibilidade de dados e código, e nas referências (a referência ABNT sai do citacao_cff.py) |
O DOI aponta para o registro no Zenodo, não para o GitHub: mesmo que o repositório mude de nome ou saia do ar, o arquivo permanece. Cite a versão que gerou os resultados (o DOI daquela release), e não «o repositório».
GitLab como alternativa: o mesmo Git por baixo, plano gratuito sem cartão — e muitas universidades hospedam o próprio
| Plano GitLab | O que inclui (pricing, 09/09/2026) |
|---|---|
| Gratuito (US$ 0) | 5 usuários por grupo de nível superior; 400 minutos de computação por mês; código-fonte e CI/CD; armazenamento ajustável de 10 GiB; sem cartão de crédito |
| Premium (US$ 29/usuário/mês, anual) | Recursos de equipe e de planejamento |
| Ultimate | Preço sob consulta na página |
git remote add gitlab https://gitlab.com/<usuário>/minha-pesquisa.git git push -u gitlab main --follow-tags # o histórico e as tags vão inteiros; o GitHub continua como origin
Se a instituição hospeda um GitLab, ele pode ser o lugar do trabalho em andamento (privado, dentro da rede) e o GitHub o da publicação (público, com «Cite this repository» e Zenodo). Um repositório pode ter dois remotos; os comandos são os mesmos. O Turing Way cita ainda o Codeberg como alternativa comunitária.
checar_repo.py: a auditoria antes do push — segredos, dados pessoais, arquivos grandes, README, LICENSE, CITATION.cff, remoto
/home/usuario): python3 scripts/checar_repo.py . lista «5 arquivos rastreados», um BLOQUEIO («.env parece guardar segredo — tire do Git (git rm --cached) e troque a credencial») e três AVISOs (falta LICENSE, falta CITATION.cff, nenhum remoto configurado); depois do git rm --cached .env e do commit, o citacao_cff.py grava o CITATION.cff e imprime o BibTeX @software e a referência ABNT (slide seguinte).| O que confere | Como aparece |
|---|---|
| Arquivos grandes | Rastreados acima de 50 MiB → AVISO; acima de 100 MiB → BLOQUEIO (os limites do GitHub); binários acima de 5 MiB → aviso |
| Segredos | Nomes (.env, .pem, id_rsa) e conteúdos (tokens ghp_, AKIA, sk-, chave privada PEM) → BLOQUEIO |
| Dados pessoais (LGPD) | Padrões de CPF e listas de e-mails em arquivos de texto; pastas de dados brutos (dados_FORA_DO_GIT/ etc.) rastreadas |
| Publicação | Falta de README, LICENSE, CITATION.cff ou .gitignore; ausência de remoto; mudanças sem commit |
| Saída | «N bloqueio(s), M aviso(s)»; código de saída 1 se houver bloqueio — por isso serve no GitHub Actions (Figura 18) |
python3 scripts/checar_repo.py . # a pasta atual (ou o caminho de outro repositório) python3 scripts/checar_repo.py . && git push --follow-tags # só faz o push se não houver bloqueio
O script só lê: não apaga, não faz commit, não envia nada. Um BLOQUEIO é decisão sua de resolver — na demonstração, git rm --cached .env tirou o arquivo do Git e a mensagem do commit registrou que a chave foi trocada. Os AVISOs de LICENSE e CITATION.cff sumiram na segunda auditoria (Figura 14), depois dos slides da Parte 4.