.gitignore: como ignorar arquivos e pastas no Git

.gitignore diz quais caminhos não rastreados o Git deve omitir das sugestões de git status e de um git add comum. Ele não apaga arquivos e não deixa um arquivo já rastreado invisível. Essa diferença é essencial para dependências, builds, logs e configurações locais.

O sandbox desta lição contém um node_modules didático, com apenas dois arquivos. A medida é real e deliberadamente não finge ser uma instalação Vite:

du -sh node_modules
find node_modules -type f | wc -l

Num projeto real, meça o seu diretório. Dependências podem ocupar centenas de megabytes e milhares de arquivos, mas o número varia com sistema, versão e pacotes. O motivo para ignorar não é apenas tamanho: essas dependências podem ser reconstruídas a partir do manifesto e do lockfile.

Faça a regra morar com o projeto

O arquivo usado no teste tem uma regra por intenção:

sed -n '1,10p' .gitignore

A barra final expressa diretório. *.log encontra arquivos com essa extensão em qualquer nível. .env protege o nome exato conforme o contexto da regra. A negação permite versionar um modelo sem segredo, como config/exemplo.env.

Depois de criar o arquivo, os artefatos ignorados somem do status, enquanto a regra e o modelo continuam visíveis:

git status --short

node_modules, dist e o log existem no disco. O Git apenas parou de sugerir esses caminhos. Commitar .gitignore é parte da solução: outro clone recebe a mesma política.

Leia padrões do mais geral ao específico

* casa caracteres dentro de um componente do caminho. Uma barra no começo ancora a regra na raiz do .gitignore. ** atravessa níveis de diretório. ! nega uma regra anterior, mas o diretório pai também precisa estar acessível para que a inclusão funcione.

git check-ignore -v node_modules/pacote/index.js dist/app.js logs/app.log config/exemplo.env

git check-ignore -v é melhor que editar padrões no escuro. Ele mostra arquivo, linha e regra vencedora. A saída da negação confirma que o modelo foi reincluído; por isso ele aparece no status.

Uma estrutura comum para o projeto da livraria seria:

node_modules/
dist/
coverage/
*.log
.env
.env.*
!.env.example

Esse é um exemplo de política, não saída de execução; ajuste-o aos artefatos realmente gerados pelo projeto. Não cole um template enorme sem entender. Uma regra ampla como *.json pode esconder package.json. Ignore resultados reconstruíveis e configurações locais; versione código, manifestos, lockfiles e modelos necessários para outra pessoa reproduzir o ambiente.

Ignorar não remove o que já entrou

No teste, .env foi commitado antes da regra. Depois de criar .gitignore, ele não apareceu como não rastreado porque já tinha identidade no índice.

git ls-files .env

Para deixar o arquivo no disco e removê-lo do próximo retrato, use --cached:

git rm --cached .env
git status --short

O D preparado significa que o próximo commit remove .env do repositório. O arquivo local permanece e passa a ser ignorado. Revise o diff, commit a remoção e a regra juntas, e forneça um .env.example sem credenciais.

Um segredo vazado continua no histórico

Remover da versão atual não apaga commits antigos. O próprio log prova que .env participou do primeiro commit:

git --no-pager log --all --oneline -- .env

Se havia uma chave real, revogue ou troque a credencial antes de qualquer reescrita. Considere o segredo comprometido. Depois, siga o procedimento de segurança do provedor e coordene a limpeza do histórico. Reescrever não impede que clones, caches e logs já tenham guardado o valor.

Preferências da máquina ficam no ignore global

Arquivos do editor ou do sistema que não pertencem à política do projeto podem ficar num arquivo global. O teste isolado configurou:

HOME="$HOME_TEMP" git config --global core.excludesFile "$HOME_TEMP/.gitignore_global"
HOME="$HOME_TEMP" git config --show-origin --get core.excludesFile

Não coloque no .gitignore do time uma regra para uma ferramenta que só você usa, a menos que o time tenha adotado essa política. O arquivo global também não deve esconder artefatos essenciais do projeto, porque colegas e CI não recebem sua configuração pessoal.

O erro comum é adicionar .gitignore, executar git add . e acreditar que um segredo antigo desapareceu. Confirme com git ls-files, git log --all -- .env e o scanner de segredos do fluxo. A lição de status e log ajuda a ler esses estados; a de desfazer no Git separa remoção local de histórico compartilhado.

Sua missão é criar artefatos falsos, escrever regras mínimas e explicar cada decisão com git check-ignore -v. Termine quando o modelo de configuração aparecer no status, o arquivo local de segredo não aparecer e o fluxo de publicação puder clonar o projeto sem depender de conteúdo confidencial. Acrescente uma regra errada de propósito, como *.json, e use git check-ignore -v package.json para localizar o dano antes de corrigir. Esse contraste ensina a tratar padrões como código: regra ampla precisa de caso de teste, revisão e explicação.

Ao trabalhar em equipe, inclua no pull request por que cada artefato é reconstruível. “É lixo” não ajuda alguém que vê a pasta pela primeira vez. Explique qual comando gera dist, qual manifesto reinstala node_modules e qual arquivo de exemplo documenta as variáveis esperadas. Assim, ignorar deixa de ser limpeza cosmética e vira parte verificável da reprodução do projeto. Em ambientes de CI, essa clareza também impede que a aplicação dependa por acidente de um arquivo que existia apenas na sua máquina.