O que ignorar e o que commitar
Critérios para ignorar saídas de build, dependências, caches e segredos e commitar lockfiles, configurações de exemplo e configurações de editor do time, além de .gitignore em subdiretórios, diretórios vazios e dicas para combinar modelos.
Um bom .gitignore se avalia pelo critério, não pelo tamanho. O critério é um só: quem clonar o repositório do zero consegue recriar o mesmo resultado só com o código e as configurações? O que pode ser recriado é ignorado; o que não pode, ou o que fixa o resultado, é commitado.
O que ignorar
| Tipo | Exemplos | Motivo |
|---|---|---|
| Saídas de build | dist/, build/, target/, *.o, *.class | são recriadas a partir do código |
| Dependências instaladas | node_modules/, vendor/ (PHP), .venv/ | são reinstaladas pelo manifesto e pelo lockfile |
| Caches e logs | .cache/, .pytest_cache/, *.log, coverage/ | mudam a cada execução |
| Ambiente local e segredos | .env, *.pem, local.properties, *.tfstate | variam por pessoa/ambiente ou não podem vazar |
| Estado de ferramentas pessoais | .DS_Store, *.swp, .idea/workspace.xml | não têm relação com o projeto (gitignore global recomendado) |
O que commitar
- Lockfiles:
package-lock.json,yarn.lock,pnpm-lock.yaml,Cargo.lock,poetry.lock,uv.lock,Gemfile.lock,composer.lock,go.sum,.terraform.lock.hcl. Garantem que todos instalem as mesmas versões. Alguns modelos, como o do Angular, ignoram lockfiles, então confira o resultado. - Configurações de exemplo:
.env.example,config.example.yml. Mostram quais valores são necessários sem conter segredos reais. - Wrappers de ferramentas de build:
gradlewegradle/wrapper/,mvnw. Confira se o jar do wrapper não foi ignorado pelo*.jardo modelo Java. - Configurações de editor combinadas pelo time:
.editorconfig,.vscode/settings.json,.vscode/extensions.json,.idea/codeStyles/. Compartilhar formatação e lint facilita as revisões.
.gitignore em subdiretórios
O .gitignore não precisa ficar só na raiz. Um .gitignore em um subdiretório funciona tendo esse diretório como base e tem precedência sobre os arquivos de cima. Em um monorepo em que cada pacote precisa de regras diferentes, fica mais legível manter um arquivo em cada pasta de pacote.
repo/
├── .gitignore # comum: .DS_Store, .env, coverage/
├── apps/web/.gitignore # .next/, out/
└── services/api/.gitignore # target/
Manter diretórios vazios
O git rastreia só arquivos e não guarda diretórios vazios. Para que uma pasta exista, mas com o conteúdo ignorado, como uma pasta de logs, coloque um arquivo marcador dentro dela e reinclua-o com uma negação.
/log/*
!/log/.keep
Nomes como .keep ou .gitkeep não são um recurso oficial do git, apenas uma convenção. Qualquer nome funciona. Outra forma é colocar dentro da pasta um .gitignore com o conteúdo abaixo, que ignora tudo menos ele mesmo.
*
!.gitignore
Ao combinar modelos
- A combinação comum é 1 ou 2 linguagens/frameworks + SO + editor. Se as regras de SO e editor já estão no global, dá para omiti-las.
- Confira a ordem. Modelos com regras de negação (Gradle, VisualStudioCode) devem vir depois dos modelos com regras amplas (Java, Kotlin).
- Remova duplicatas preservando o significado. Repetir a regra não muda o comportamento, mas dificulta a leitura. O gerador deste site só remove duplicatas quando não há regra de negação entre elas.
- Mantenha os comentários de seção. Meses depois, você precisa saber de onde veio cada regra para poder removê-la com segurança.
- Teste. Coloque no teste de padrões os caminhos reais obtidos com
git ls-filese confirme que nada é ignorado sem querer (por exemplo, código front-end preso nolib/do modelo Python).
Regras curtas e específicas
Regras amplas demais, como *.json, engolem até arquivos de configuração. Restrinja o caminho sempre que puder (/dist/) e termine diretórios com barra para diferenciá-los de arquivos com o mesmo nome. Um comentário de uma linha acima da regra explicando o motivo ajuda a próxima pessoa a decidir se pode removê-la.
Referências
- Documentação oficial do gitignore
- README do repositório github/gitignore
- npm Docs: package-lock.json
- Verificado em: 2026-09-23