¿Por qué se ignora? Depurar con git check-ignore

Cuando las reglas se multiplican surgen preguntas como "¿por qué no veo este archivo?" o "¿por qué sigue apareciendo?". git tiene comandos que responden a esas preguntas.

git check-ignore -v

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

La salida tiene el formato origen:número de línea:patrón<tab>ruta.

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

• El origen es el archivo que contiene la regla. Aparece uno de estos: .gitignore, sub/.gitignore, .git/info/exclude o la ruta del archivo global.
• Con el número de línea y el patrón sabes exactamente de qué línea se trata.
• Si no se muestra nada, esa ruta no se ignora.
• Con -v, los casos recuperados con ! también muestran la regla de negación, como en .gitignore:4:!keep.log keep.log.
• Para archivos cuyo directorio padre está excluido, se muestra la regla de ese directorio. Por ejemplo, si se debe a la regla logs/, aparece .gitignore:1:logs/ logs/keep.txt.

Para ver también las rutas que no coinciden, añade --non-matching (-n).

Para archivos rastreados, --no-index

Las reglas de ignorar no se aplican a archivos ya rastreados, así que check-ignore tampoco muestra nada por defecto. Si solo quieres saber si una regla coincide con ese archivo, añade --no-index.

$ git check-ignore -v app.log            # rastreado, sin salida
$ git check-ignore -v --no-index app.log
.gitignore:3:*.log	app.log

Ver la lista de archivos ignorados

# Mostrar los ignorados junto con el estado (marca !!)
git status --ignored --short

# Listar todos los archivos ignorados, archivo por archivo
git ls-files --others --ignored --exclude-standard

# Archivos rastreados que coinciden con las reglas de ignorar
git ls-files -ci --exclude-standard

Si se ignora un directorio entero, git status --ignored lo muestra como un solo directorio, por ejemplo !! logs/. Si quieres verlo archivo por archivo, usa ls-files.

Causas comunes de que una regla no funcione

1. Ya se está rastreando. Es lo más habitual. Si git ls-files <ruta> muestra algo, se está rastreando. Corta el seguimiento con git rm --cached.
2. El directorio padre está excluido. Con dir/ ignorado, !dir/file no tiene efecto. Cámbialo por dir/*.
3. El orden está invertido. Si tras la regla de negación vuelve a aparecer una regla más amplia, gana esa regla. Se ve enseguida con el número de línea de check-ignore -v.
4. Espacios finales. El espacio final de *.log se elimina, pero los espacios delante del patrón o caracteres invisibles como el espacio de ancho completo sí quedan como parte del patrón.
5. Dirección de la barra. gitignore usa solo / como separador de rutas, también en Windows. En build\output la barra invertida se interpreta como escape y no funciona como se espera.
6. Confusión con el anclaje. config/local.json solo coincide con el config de la raíz por la barra intermedia. Para aplicarlo a cualquier profundidad usa **/config/local.json.
7. Mayúsculas y minúsculas. En entornos donde core.ignorecase es false (normalmente Linux), *.JPG y *.jpg son distintos. Los repositorios creados en macOS o Windows suelen tener true, lo que puede provocar diferencias: funciona en local pero no en la CI.

Comprobarlo antes en el navegador

Si quieres cambiar reglas y comparar resultados antes de aplicarlas al repositorio, la pestaña Probar patrones de este sitio es práctica. Al pegar las reglas y la lista de rutas, muestra para cada ruta el resultado, la regla decisiva (número de línea) y los casos ignorados por el directorio padre. Como lista de rutas puedes usar tal cual la salida de git ls-files o find . -type f. Eso sí, el veredicto final que combina los .gitignore de subdirectorios y la configuración global compruébalo en el repositorio con git check-ignore -v.

Referencias

• Documentación oficial de git-check-ignore
• Documentación oficial de git-status: --ignored
• Documentación oficial de git-ls-files
• Fecha de verificación: 2026-09-23 (formato de salida comprobado con git 2.50.1)