.gitignore ne fonctionne pas : la règle n'atteint pas l'index

Si .gitignore ne « fonctionne pas », un seul mécanisme couvre la majorité des cas : le fichier a été commité avant que la règle n'existe. .gitignore n'est pas un filtre qui cache des fichiers à git — c'est une règle sur ce que git add récupère depuis un état non suivi. Tant qu'un fichier est dans l'index, git suit les changements de son contenu pour toujours, jusqu'à ce que vous le sortiez explicitement du suivi. C'est pourquoi la séquence classique « commit .env, panique, add .env dans .gitignore, re-commit » expédie toujours le secret à chaque push.

■ la réponse d'abord

.gitignore « ne fonctionne pas » signifie presque toujours que le fichier est déjà suivi — un fichier dans l'index est immunisé contre toute règle que vous écrivez.

git check-ignore -v <path> donne la réponse : règle affichée = un problème de règle ; silence = fichier suivi et aucune règle applicable.

Correction : git rm --cached <path>, commit — la règle fonctionne à partir de ce commit.

LES DEUX PORTES

Une commande, deux issues possibles — git check-ignore -v vous fait passer par l'une des deux :

PORTE 1 · elle affiche une règle

$ git check-ignore -v debug.log
.gitignore:3:*.log    debug.log

une règle s'applique — la mauvaise, ou dans la mauvaise portée. Le problème vit dans le fichier .gitignore : ordre des règles, pièges de négation, ou quel fichier d'ignore possède le chemin.

PORTE 2 · silence

$ git check-ignore -v src/.env
$ # (nothing — no rule applies)

le fichier est suivi malgré tout. Vérifiez avec git ls-files --error-unmatch <path>, puis git rm --cached <path> et commitez la suppression. Le silence est le diagnostic.

les codes de sortie sont scriptables : 0 = ignoré, 1 = non ignoré — git check-ignore -q debug.log && echo ignored || echo tracked-or-unruly

LE SPÉCIMEN — UN GITIGNORE, LIGNE PAR LIGNE

Le piège de la négation, annoté. Pourquoi !build/keep.me ne sauve jamais le fichier :

build/ignore le répertoire en bloc — git ne regarde plus jamais à l'intérieur

!build/keep.melettre morte : impossible de ré-inclure un fichier situé dans un répertoire exclu

build/*la solution — ignorer le contenu, pas le répertoire

!build/keep.mecette fois vivant : le chemin parent est parcourable, l'exception s'applique

*.log puis !important.logla dernière règle correspondante gagne — la négation qui suit la règle ré-inclut ce seul fichier

LA TABLE COMPLÈTE DES CAUSES

Symptôme	Vraie cause	Correctif
Le fichier ignoré apparaît toujours dans `git status`	Commité avant la règle — dans l'index	`git rm --cached` + commit
`git add .` le ré-ajoute sans fin	Pareil : le suivi l'emporte sur l'ignore	En masse : `git rm -r --cached .` → `git add .`
`!build/keep.me` ne sauve jamais le fichier	Répertoire parent exclu — git le saute en bloc	`build/*` + `!build/keep.me`
Une règle plus bas écrase la vôtre	La dernière règle correspondante gagne	Réordonnez, ou lisez la gagnante via `check-ignore -v`
La règle marche pour vos collègues, pas pour vous (ou l'inverse)	`.gitignore` imbriqué / exclude / global qui divergent	Reportez-vous à la table des portées ci-dessous
VS Code le montre modifié après l'ajout de la règle	Suivi — ou une vue SCM périmée	`git rm --cached` ; rechargez d'abord la fenêtre
Vous voulez des modifications silencieuses, fichier toujours suivi	Divergence locale volontaire	`git update-index --skip-worktree`

LES TROIS PORTÉES

Les règles peuvent vivre à trois endroits, et « ça marche pour les collègues, pas pour moi » est presque toujours un problème de portée :

.gitignore dans le dépôt — commité, partagé avec tout le monde. Chez lui par défaut pour les sorties de build et les dossiers de dépendances.
.git/info/exclude — par clone, jamais commité. Pour vos fichiers personnels dans ce checkout précis.
Votre fichier d'ignore global (core.excludesFile) — par machine, sur tous les dépôts. L'adresse classique de .DS_Store et les déchets d'éditeur.

Lire check-ignore -v affiche la source directement : le fichier d'ignore, puis line-number:pattern, puis le chemin — donc quand une règle surprise gagne, la gagnante s'identifie elle-même.

vérification : git check-ignore -v debug.log → .gitignore:3:*.log debug.log

LE RETRAIT DU SUIVI, PAS À PAS

# untrack one file (the local copy survives — --cached touches the index only)
git rm --cached .env
git commit -m "stop tracking .env"

# verify the ignore rule now applies
git check-ignore -v .env

À partir de ce commit, .gitignore possède le chemin : les modifications n'apparaissent plus dans git status, et git add . ne ramassera plus le fichier.

S'il s'agissait d'un secret, le retrait du suivi n'est pas la solution. Le fichier reste dans l'historique — le retirer du dernier commit ne suffit pas. Rotation du secret = la vraie réparation ; réécrire l'historique = la cosmétique.

■ cachet d'honnêteté Testé sur : git 2.4x · Linux · macOS · Windows · vue SCM de VS Code. Première publication : 2026-09-17. Le mécanisme d'immunité de l'index, la priorité à la dernière règle correspondante, la règle de négation des répertoires et les codes de sortie sont le comportement documenté de git — le spécimen ci-dessus a exactement la forme de tous les .gitignore qui « n'ont jamais marché ».

fin des deux portes · rien fetché · tout en local