O que é repositório de código e o que deve (e não deve) ficar nele

Sexta à noite, você termina o projeto do curso, cria um repositório público no GitHub e manda tudo com git add .. Junto foi o arquivo .env com a chave da API de pagamentos que você usou para testar. Em poucas horas, robôs que varrem repositórios públicos atrás de credenciais podem encontrar a chave, e apagar o arquivo no commit seguinte não resolve: ele continua no histórico.

Essa cena é mais comum do que parece, e mostra que saber o que é um repositório é só metade da conversa. A outra metade é saber o que colocar dentro dele.

Em três linhas:

• Repositório é a pasta do projeto mais o histórico completo de todas as versões, guardado pelo Git numa subpasta oculta chamada .git.
• Entra o que é necessário para reconstruir o projeto: código-fonte, configuração sem segredo, testes, documentação e o arquivo de dependências.
• Fica de fora o que é segredo, o que é gerado automaticamente e o que é pessoal da sua máquina.

Repositório local e remoto: duas cópias completas, papéis diferentes

Quando você roda git init numa pasta, ela vira um repositório local. O Git cria a pasta .git e passa a registrar cada commit ali, no seu computador. Não precisa de internet nem de conta em site nenhum.

O repositório remoto é uma cópia do mesmo projeto hospedada num servidor (GitHub, GitLab, Bitbucket ou um servidor da própria empresa). A documentação do GitHub sobre repositórios o descreve como o lugar que guarda os arquivos do projeto e o histórico de revisões de cada um. Ele serve de ponto de encontro: todo mundo envia (git push) e busca (git pull) dali.

Para ligar os dois, você usa git remote add origin URL num projeto que nasceu local, ou git clone URL quando o projeto já existe no servidor. O nome origin é só uma convenção para o remoto principal; um repositório pode ter vários remotos, como acontece quando você contribui com um projeto de código aberto e mantém um upstream apontando para o original e um origin apontando para a sua cópia (o fork).

Um detalhe que pega iniciantes: o Git é distribuído. Ao clonar, você recebe o histórico inteiro, não só a versão atual. Se o servidor sumisse amanhã, qualquer clone completo poderia recriá-lo.

O que nunca deve ir para o repositório

Aqui o custo do erro varia de “repositório pesado” a “conta da nuvem invadida”. Do mais grave ao menos grave:

Senhas, tokens e chaves de API

Arquivos .env, chaves .pem, credenciais de banco, tokens de bot. Mesmo em repositório privado é má ideia, porque o acesso muda com o tempo (um estagiário entra, um fornecedor recebe permissão). O GitHub tem o secret scanning, que procura credenciais expostas e avisa os provedores parceiros, mas trate isso como rede de proteção, não como plano.

Se uma chave vazou, a ordem é: revogar a chave no provedor primeiro, gerar outra, e só depois limpar o histórico. Limpar o histórico sem revogar não adianta, porque alguém pode já ter copiado.

Dependências baixadas e arquivos gerados

node_modules/, venv/, vendor/, dist/, build/, arquivos .class e __pycache__. Tudo isso é recriado com um comando a partir do arquivo de dependências ou do código. Versionar só infla o repositório e gera conflitos sem sentido em cada merge.

Arquivos grandes e binários

O GitHub bloqueia arquivos acima de 100 MiB e recomenda manter repositórios abaixo de 1 GB, segundo a página sobre arquivos grandes no GitHub. Dumps de banco, vídeos e datasets vão para armazenamento próprio ou para o Git LFS, que guarda o arquivo fora e deixa só uma referência no repositório.

Configurações pessoais da sua máquina

Pastas .idea/ e .vscode/ com preferências individuais, .DS_Store do macOS, Thumbs.db do Windows, logs locais. Não fazem mal, mas poluem cada git status do time.

O que entra no repositório sem discussão

O critério é simples: se alguém clonar o projeto numa máquina nova, o que precisa existir para ele rodar e ser entendido?

• Código-fonte, claro, incluindo scripts de build e de migração do banco.
• Arquivo de dependências: package.json, requirements.txt, pom.xml. E também o lockfile (package-lock.json, poetry.lock), que fixa as versões exatas e evita o famoso “na minha máquina funciona”.
• Testes e seus dados de exemplo pequenos.
• README com o que o projeto faz e como rodar.
• Configuração sem segredo: linter, formatador, .editorconfig, arquivos de CI.
• Um modelo de variáveis de ambiente, o .env.example, com os nomes das variáveis e valores falsos.
• O próprio .gitignore, que diz ao Git o que ignorar.

Um .gitignore de partida para projetos Node ou Python

# segredos
.env
*.pem

# dependências e gerados
node_modules/
venv/
__pycache__/
dist/
build/

# sistema e editor
.DS_Store
Thumbs.db
.idea/
*.log

A especificação do gitignore explica os padrões (asterisco, barra no fim para pastas, exclamação para exceções). Um ponto que confunde: o .gitignore só vale para arquivos que ainda não foram rastreados. Se o .env já entrou num commit, adicioná-lo ao .gitignore não o remove. É preciso rodar git rm --cached .env e fazer commit, e mesmo assim ele continua nos commits antigos.

Repositório público ou privado: quando cada um faz sentido

Para portfólio de dev júnior, repositório público é vitrine. Recrutadores olham commits, README e organização. Só que público exige o dobro de cuidado com o que foi dito acima, porque qualquer pessoa (e qualquer robô) lê tudo, inclusive o histórico.

Antes de tornar público um projeto que nasceu privado, revise o histórico inteiro, não só a versão atual. Um comando como git log -p -- .env mostra se o arquivo de segredos apareceu em algum commit antigo. Se apareceu, troque as chaves antes de abrir o repositório, porque a mudança de visibilidade expõe todos os commits de uma vez.

Projetos de cliente, código de empresa e qualquer coisa com dado pessoal ficam em repositório privado, com acesso por pessoa e revisado de tempos em tempos. Quem trabalha com dados de terceiros também precisa lembrar que um dump de banco com nomes e CPFs no repositório é um problema de LGPD, não só de organização.

Plataformas como o GitHub também oferecem controles extras para repositórios de equipe, como o controle de licenças de dependências, que ajuda a evitar que uma biblioteca com licença incompatível entre no projeto.

Repositório limpo começa no primeiro commit

O próximo passo prático: antes do primeiro git add de qualquer projeto novo, crie o .gitignore e o .env.example. Depois, troque o hábito de git add . por olhar o git status antes de cada commit, nem que seja por cinco segundos. É nesse olhar que o .env aparece na lista e você para a tempo. Os outros termos que aparecem nesse cuidado diário, como commit, push e clone, estão explicados no glossário de programação.