.gitignore ne marche pas ? Voilà le vrai correctif

TL;DR : si .gitignore ne marche pas, le fichier est presque toujours déjà suivi. Git ignore les fichiers qu’il n’a jamais vus — un fichier présent dans l’index est immunisé contre toute règle que tu écris. Vérifie la vérité avec git check-ignore -v <path> : une sortie silencieuse veut dire que le chemin est suivi et qu’aucune règle ne s’applique. Corrige avec git rm --cached <path>, commite, et la règle d’ignore se met à travailler à partir de ce commit. L’ordre des règles, les pièges de négation et les fausses pistes VS Code expliquent les cas restants.

Pourquoi .gitignore ne marche 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 doit ramasser depuis un état non suivi. Dès qu’un fichier est dans l’index, git suit ses changements de contenu pour toujours, tant que tu ne le détaches pas explicitement. Éditer .gitignore après coup ne change rien aux fichiers suivis — c’est pourquoi la séquence classique « commit de .env, panique, ajout de .env dans .gitignore, recommit » livre quand même le secret à chaque push.

Ça mord tout le monde parce que git est partout — l’enquête Stack Overflow 2022 compte plus de 93 % de devs pros utilisateurs de Git (survey.stackoverflow.co) — et chacun de ces devs finit par écrire une règle pour un fichier commité la semaine passée.

La suite de ce billet couvre les cas minoritaires : erreurs d’ordre de règles, pièges de négation, cas limites des dossiers et la question de l’IDE. Mais lance d’abord le check-up de la section suivante — plus de neuf fois sur dix, il clos l’enquête.

Comment savoir quelle règle gitignore matche un fichier ?

git check-ignore est l’outil de diagnostic, et son silence est le diagnostic :

# Affiche la règle qui matche + le fichier + le numéro de ligne quand une règle s'applique
git check-ignore -v debug.log
# .gitignore:3:*.log    debug.log

# N'affiche RIEN quand aucune règle ne s'applique — le fichier est suivi (ou aucune règle n'existe)
git check-ignore -v src/.env
# (silence = .gitignore n'ignore pas ce chemin, quoi que tu aies écrit)

# Codes de sortie : 0 = ignoré, 1 = pas ignoré — scriptable
git check-ignore -q debug.log && echo "ignored" || echo "tracked or unruly"

Lecture de la sortie de -v : la source d’ignore (.gitignore, .git/info/exclude, ou ton fichier d’ignore global), puis numéro-de-ligne:motif, puis le chemin. Si une règle plus bas te surprend, rappelle-toi la précédence : la dernière règle qui matche gagne, donc !important.log après *.log ré-inclut ce seul fichier.

Pourquoi gitignore ne marche pas sur des fichiers déjà commités ?

Détache le fichier, garde-le sur disque, commite la suppression :

# Détacher un fichier (la copie locale survit — --cached ne touche que l'index)
git rm --cached .env
git commit -m "stop tracking .env"

# Vérifie que la règle d'ignore s'applique maintenant
git check-ignore -v .env

À partir de ce commit, .gitignore possède le chemin : ses modifications n’apparaissent plus dans git status, et git add . ne le ramassera plus. Le fichier reste pourtant dans l’historique — si c’était un secret, le retirer du dernier commit ne suffit pas. La rotation du credential est le seul vrai correctif ; la réécriture d’historique est le correctif cosmétique (et annuler le dernier commit n’aide que tant que le mauvais commit est encore la pointe).

Pour un repo plein de déchets commités avant — sortie de build, dépôts d’éditeur, node_modules entré en douceur — le détachement de masse tient en deux lignes :

git rm -r --cached .
git add .
git commit -m "apply .gitignore to tracked files"

Ça reconstruit l’index contre les règles actuelles : les chemins ignorés tombent, tout le reste est ré-ajouté à l’identique. Le diff a l’air dramatique (des milliers de suppressions) mais ne supprime rien du disque. Si ton but est de supprimer ces fichiers et pas seulement de les détacher, c’est le territoire de git clean -fdx — voir git remove untracked files, safely.

Git ignore les fichiers qu’il n’a jamais vus. Un fichier déjà dans l’index est immunisé contre .gitignore — aucune règle que tu écriras ne lui fera oublier qu’il existe.

Pourquoi gitignore ne marche pas sur un dossier ?

Trois pièges propres aux dossiers :

1. Le slash final parle d’intention, pas de matching. build et build/ matchent tous deux un répertoire, mais build/ documente que tu vises un répertoire seulement — un fichier nommé build lui survivrait. La symétrie casse en revanche à la ré-inclusion (piège suivant).

2. La négation ne peut pas sauver des fichiers dans un répertoire exclu. La doc git est sans ambiguïté : « il est impossible de ré-inclure un fichier si un répertoire parent de ce fichier est exclu » (git-scm.com/docs/gitignore). C’est une décision de performance — git saute les répertoires exclus en bloc au lieu de les parcourir. Donc ceci ne marche pas :

build/
!build/keep.me        # règle morte — git ne regarde jamais dans build/

Le correctif : exclure le contenu, pas le répertoire :

build/*
!build/keep.me        # marche — build/ lui-même reste ouvert à l'inspection

3. Les .gitignore imbriqués gagnent dans leur périmètre. Les règles de subdir/.gitignore priment sur le fichier racine pour les chemins sous subdir. Quand git check-ignore -v nomme une source d’ignore que tu n’attendais pas, c’est généralement ça.

Pourquoi gitignore ne marche pas dans VS Code ?

Presque jamais pour des raisons VS Code. La vue Source Control lit le même index que git, donc le symptôme est identique : le fichier était déjà commité, et aucun redémarrage d’IDE ne change l’index. Deux réalités adjacentes à VS Code valent la peine d’être connues :

• Grisé dans l’Explorer = ignoré ; orange/jaune = suivi avec des modifications. Un fichier affiché comme modifié après que tu l’as ignoré, c’est ta confirmation qu’il est suivi — lance le correctif git rm --cached plus haut.
• L’absence d’un .gitignore dans la liste changed de l’Explorer veut dire que la règle marche — il n’apparaît jamais comme fichier non suivi en premier lieu. On rapporte souvent « VS Code ignore mon gitignore » quand le git status du CLI est en désaccord avec une vue SCM périmée ; recharge la fenêtre (Cmd/Ctrl+Shift+P → « Reload Window ») avant d’accuser git.

.gitignore, .git/info/exclude ou global : lequel, quand ?

Fichier	Périmètre	Commité ?	Pour
.gitignore (repo)	Tous ceux qui clonent	Oui	Sortie de build, dépendances, .env — règles partagées
.git/info/exclude	Ton clone seulement	Non	Ton bazar personnel : .scratch/, dépôts d’éditeur
core.excludesFile (global)	Tous tes repos	Non	Déchets OS : .DS_Store, Thumbs.db, *.swp
.gitignore + négation	Repo	Oui	Ré-inclure des exceptions de config suivie

Le fichier global est celui que la plupart des devs ne définissent jamais et devraient :

git config --global core.excludesFile ~/.gitignore_global
printf '.DS_Store\nThumbs.db\n*.swp\n' >> ~/.gitignore_global

Règle de maison à copier : si une règle profite à toute l’équipe, elle va dans le repo ; si elle ne profite qu’à toi, elle va dans exclude ou dans le fichier global. Commettre ses règles d’ignore personnelles, c’est comme ça que les .gitignore finissent à 300 lignes et que plus personne ne sait quelle moitié compte encore.

Comment ignorer les changements d’un fichier suivi ?

Parfois tu veux un fichier suivi (un template de config, des réglages d’IDE) mais tu veux que tes éditions locales cessent d’apparaître dans git status. Deux flags de git update-index, dont aucun n’a sa place dans un workflow d’équipe :

git update-index --skip-worktree config/local.dev   # les éditions locales se taisent
git update-index --no-skip-worktree config/local.dev  # ...et on leur rend la parole

--skip-worktree est le défendable — il dit « ma version locale diverge intentionnellement ». Son cousin --assume-unchanged est une promesse de performance (« ce fichier ne changera pas »), pas un mécanisme d’ignore, et git peut le casser en silence. Les deux flags échouent bruyamment au pull quand l’amont a aussi changé le fichier — les réponses durables sont une config locale-only via exclude dès la création, ou un fichier template (config.example) que git suit et que tu copies.

Le check-up gitignore en 30 secondes

git check-ignore -v <path>        # quelle règle ? (silence = suivi, aucune règle)
git ls-files --error-unmatch <path>  # est-il suivi, tout court ?
git rm --cached <path>            # détache, garde sur disque
git commit -m "stop tracking <path>"
git check-ignore -v <path>        # la règle s'affiche maintenant

Diagnostiquer, détacher, vérifier. Le motif derrière chaque rapport « gitignore not working », c’est le même fichier portant deux chapeaux — suivi d’un côté de l’index, ignoré de l’autre — et un flag --cached retire le second chapeau.