guide

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

TipoExemplosMotivo
Saídas de builddist/, build/, target/, *.o, *.classsão recriadas a partir do código
Dependências instaladasnode_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, *.tfstatevariam por pessoa/ambiente ou não podem vazar
Estado de ferramentas pessoais.DS_Store, *.swp, .idea/workspace.xmlnão têm relação com o projeto (gitignore global recomendado)

O que commitar

.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

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

← AnteriorPor que está sendo ignorado? Depuração com git check-ignore