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

Quando as regras se acumulam, surgem perguntas como "por que este arquivo não aparece?" ou "por que ele continua aparecendo?". O git tem comandos que respondem a isso.

git check-ignore -v

git check-ignore -v logs/app.log src/build/keep.txt

A saída tem o formato origem:linha:padrão<TAB>caminho.

.gitignore:3:*.log	logs/app.log

• A origem é o arquivo que contém a regra: .gitignore, sub/.gitignore, .git/info/exclude ou o caminho do arquivo global.
• Com o número da linha e o padrão você sabe exatamente qual linha foi.
• Se nada for exibido, o caminho não é ignorado.
• Com -v, casos reincluídos com ! também aparecem com a regra de negação, como .gitignore:4:!keep.log keep.log.
• Para arquivos cujo diretório pai foi excluído, aparece a regra desse diretório. Por exemplo, se a causa for a regra logs/, a saída é .gitignore:1:logs/ logs/keep.txt.

Para ver também os caminhos que não casaram, acrescente --non-matching (-n).

Arquivos rastreados: --no-index

Como as regras de ignorar não se aplicam a arquivos já rastreados, o check-ignore por padrão não mostra nada para eles. Se você só quer saber se uma regra casa com o arquivo, acrescente --no-index.

$ git check-ignore -v app.log            # rastreado, sem saída
$ git check-ignore -v --no-index app.log
.gitignore:3:*.log	app.log

Listar arquivos ignorados

# mostra os itens ignorados junto com o status (marca !!)
git status --ignored --short

# lista todos os arquivos ignorados, um por um
git ls-files --others --ignored --exclude-standard

# arquivos rastreados que casam com regras de ignorar
git ls-files -ci --exclude-standard

Quando um diretório inteiro é ignorado, git status --ignored o mostra como um só item, como !! logs/. Para ver arquivo por arquivo, use ls-files.

Causas comuns de regras que não funcionam

1. O arquivo já é rastreado. É a mais comum. Se git ls-files <caminho> exibe algo, ele é rastreado. Pare de rastreá-lo com git rm --cached.
2. O diretório pai foi excluído. Com dir/ ignorado, !dir/file não tem efeito. Troque por dir/*.
3. A ordem está invertida. Se uma regra mais ampla aparece depois da negação, ela vence. O número da linha no check-ignore -v mostra isso na hora.
4. Espaços finais. O espaço no fim de *.log é removido, mas espaços antes do padrão e caracteres invisíveis como o espaço de largura total continuam fazendo parte dele.
5. Direção da barra. O gitignore usa só / como separador, inclusive no Windows. Em build\output, a barra invertida é lida como escape e não funciona como esperado.
6. Engano de ancoragem. config/local.json tem barra no meio, então só casa com o config da raiz. Para qualquer profundidade, use **/config/local.json.
7. Maiúsculas e minúsculas. Em ambientes com core.ignorecase igual a false (geralmente Linux), *.JPG e *.jpg são diferentes. Repositórios criados no macOS ou Windows costumam ter true, o que pode fazer algo funcionar localmente e falhar na CI.

Conferir antes no navegador

Se quiser comparar resultados mudando as regras antes de aplicar ao repositório, a aba Testar padrões deste site ajuda. Cole as regras e a lista de caminhos para ver, para cada caminho, o resultado, a regra decisiva (com número da linha) e os casos ignorados por causa do diretório pai. A lista de caminhos pode ser a saída de git ls-files ou find . -type f. O veredito final, que inclui .gitignore de subdiretórios e a configuração global, deve ser conferido no repositório com git check-ignore -v.

Referências

• Documentação oficial do git-check-ignore
• Documentação oficial do git-status: --ignored
• Documentação oficial do git-ls-files
• Verificado em: 2026-09-23 (formato de saída conferido com git 2.50.1)