19  Git e GitHub

O Git guarda cada versão do livro; o GitHub hospeda o repositório, recebe colaborações e publica o site. Para um livro, o uso é simples: um ramo principal, commits pequenos e frequentes, e o cuidado com o que não deve ser versionado.

19.1 O ciclo básico

git status                       # o que mudou
git add capitulos/ references/   # o que vai entrar
git commit -m "cap. 5: reescreve a seção sobre consolidação"
git push                         # envia para o GitHub e dispara a publicação

Cada commit deve ter uma mensagem que diga o que mudou e por quê, na linguagem do livro (“cap. 5”, “referências”, “capa”), não da ferramenta. Commits pequenos são mais fáceis de revisar e de reverter.

19.2 Mover e renomear

Quando um capítulo é renumerado ou fundido, o arquivo se move com git mv, para que o histórico o acompanhe:

git mv capitulos/parte-2/05-antigo.qmd capitulos/parte-2/06-antigo.qmd

19.3 O que não entra no repositório

O .gitignore da casa exclui:

  • as saídas do Quarto (_book/, .quarto/, _freeze/);
  • o ambiente Python (.venv/) e os relatórios de validação gerados pelo CI;
  • todos os PDFs e as pastas de fontes usadas na revisão: o repositório é público e o material tem direitos autorais;
  • fontes da edição anterior (_old_book/) e arquivos temporários.

Se um arquivo com direitos autorais chegar a ser enviado, não basta apagá-lo no commit seguinte: ele continua no histórico e precisa ser removido dele.

19.4 Colaboração

Quem quiser propor correções abre uma issue ou um pull request no repositório. Os pull requests passam pela validação bibliográfica automaticamente, mas não publicam nada: só o que chega ao ramo main vai ao ar.

19.5 O CLAUDE.md

Cada livro tem na raiz um arquivo CLAUDE.md com as regras do projeto para quem escreve com apoio de IA: a regra zero da bibliografia, o que está congelado, as convenções de capítulo, os comandos. É lido pelas ferramentas de IA a cada sessão e também serve de documentação para colaboradores humanos (Capítulo 22).

NotaPontos-chave
  • Um ramo principal, commits pequenos com mensagens na linguagem do livro, git push publica.
  • Renumerações usam git mv para preservar o histórico.
  • Saídas do Quarto, ambiente Python e todos os PDFs ficam fora do Git.
  • Pull requests validam a bibliografia mas não publicam; CLAUDE.md documenta as regras do projeto.