Pourquoi est-ce ignoré ? Déboguer avec git check-ignore

Quand les règles s'accumulent, on se demande « pourquoi ce fichier n'apparaît-il pas ? » ou « pourquoi apparaît-il encore ? ». git dispose de commandes qui répondent à ces questions.

git check-ignore -v

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

La sortie a le format source:ligne:motif<TAB>chemin.

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

• La source est le fichier qui contient la règle : .gitignore, sub/.gitignore, .git/info/exclude ou le chemin du fichier global.
• Le numéro de ligne et le motif indiquent exactement de quelle ligne il s'agit.
• Si rien ne s'affiche, le chemin n'est pas ignoré.
• Avec -v, les cas réinclus par ! apparaissent aussi avec leur règle de négation, par exemple .gitignore:4:!keep.log keep.log.
• Pour un fichier dont le répertoire parent est exclu, c'est la règle de ce répertoire qui s'affiche. Par exemple, si la cause est la règle logs/, la sortie est .gitignore:1:logs/ logs/keep.txt.

Pour voir aussi les chemins sans correspondance, ajoutez --non-matching (-n).

Fichiers suivis : --no-index

Les règles d'exclusion ne s'appliquant pas aux fichiers déjà suivis, check-ignore n'affiche rien pour eux par défaut. Pour savoir simplement si une règle correspond au fichier, ajoutez --no-index.

$ git check-ignore -v app.log            # suivi, aucune sortie
$ git check-ignore -v --no-index app.log
.gitignore:3:*.log	app.log

Lister les fichiers ignorés

# affiche les éléments ignorés avec l'état (marque !!)
git status --ignored --short

# liste tous les fichiers ignorés, un par un
git ls-files --others --ignored --exclude-standard

# fichiers suivis qui correspondent aux règles d'exclusion
git ls-files -ci --exclude-standard

Quand un répertoire entier est ignoré, git status --ignored l'affiche comme un seul élément, par exemple !! logs/. Pour voir fichier par fichier, utilisez ls-files.

Causes fréquentes de règles qui ne fonctionnent pas

1. Le fichier est déjà suivi. C'est la plus courante. Si git ls-files <chemin> affiche quelque chose, il est suivi. Arrêtez le suivi avec git rm --cached.
2. Le répertoire parent est exclu. Avec dir/ ignoré, !dir/file n'a aucun effet. Remplacez par dir/*.
3. L'ordre est inversé. Si une règle plus large revient après la négation, c'est elle qui l'emporte. Le numéro de ligne de check-ignore -v le montre immédiatement.
4. Espaces finaux. L'espace à la fin de *.log est supprimé, mais les espaces avant le motif et les caractères invisibles comme l'espace pleine chasse restent dans le motif.
5. Sens de la barre oblique. gitignore n'utilise que / comme séparateur, même sous Windows. Dans build\output, la barre oblique inverse est lue comme un échappement et la règle ne fait pas ce qui est attendu.
6. Méprise sur l'ancrage. config/local.json contient une barre au milieu et ne correspond donc qu'au config de la racine. Pour toute profondeur, utilisez **/config/local.json.
7. Casse. Là où core.ignorecase vaut false (généralement Linux), *.JPG et *.jpg sont différents. Les dépôts créés sous macOS ou Windows ont souvent true, ce qui peut faire fonctionner une règle en local mais pas en CI.

Vérifier d'abord dans le navigateur

Pour comparer les résultats en modifiant les règles avant de les appliquer au dépôt, l'onglet Test de motifs de ce site est pratique. Collez les règles et la liste de chemins : pour chaque chemin s'affichent le résultat, la règle décisive (avec numéro de ligne) et les cas ignorés à cause du répertoire parent. La liste de chemins peut être la sortie de git ls-files ou de find . -type f. Le verdict final, qui inclut les .gitignore des sous-répertoires et la configuration globale, se vérifie dans le dépôt avec git check-ignore -v.

Références

• Documentation officielle de git-check-ignore
• Documentation officielle de git-status : --ignored
• Documentation officielle de git-ls-files
• Vérifié le : 2026-09-23 (format de sortie contrôlé avec git 2.50.1)