gitignore : exclure des fichiers et utiliser des modèles

Un fichier .gitignore indique à Git quels fichiers il doit ignorer, et une bonne utilisation de gitignore empêche votre dépôt de gonfler avec des artefacts de build, des clés secrètes et des résidus d'éditeur. Une fois que des fichiers comme node_modules/, vendor/, .env ou .DS_Store entrent dans l'historique, le dépôt grossit inutilement et, un jour, vous risquez de publier par erreur le mot de passe de quelqu'un. Cet article présente la bonne façon d'exclure des fichiers, la syntaxe des motifs et les erreurs les plus fréquentes.

Une règle d'emblée : .gitignore n'agit que sur les fichiers pas encore suivis (untracked). Ajouter un fichier à la liste d'exclusion après l'avoir commité ne le retire pas automatiquement — c'est la confusion la plus courante, et je lui ai consacré une section ci-dessous.

Où placer le fichier .gitignore ?

Dans la plupart des projets, un seul .gitignore vit à la racine du dépôt et est lui-même commité, afin que toute l'équipe partage les mêmes règles. Mais Git prend en charge plusieurs niveaux :

• .gitignore racine — règles communes à tout le projet ; inclus dans le contrôle de version.
• .gitignore de sous-dossier — un fichier placé dans n'importe quel dossier ne s'applique qu'à ce dossier et à son contenu. Les chemins sont relatifs à ce répertoire.
• .git/info/exclude — règles propres à votre machine ; jamais commitées ni partagées.
• gitignore global — règles personnelles appliquées à tous vos dépôts (voir plus bas).

Les fichiers plus profonds, lus en dernier, peuvent remplacer ceux du dessus. Ainsi un .gitignore de sous-dossier peut ré-inclure, via une négation, une règle exclue par celui de la racine.

Syntaxe des motifs

Chaque ligne est un motif. Les lignes vides sont ignorées et celles qui commencent par # sont des commentaires. Les bases :

# Ligne de commentaire
*.log              # tous les fichiers .log (dans tout répertoire)
build/             # un / final ne correspond qu'aux dossiers
/config.local      # un / initial ancre le motif à la racine du dépôt
temp?.txt          # ? correspond à un seul caractère
cache[0-9].dat     # les crochets définissent une plage de caractères
!important.log      # ! négation : suivre quand même ce fichier

Distinctions clés :

• * correspond à tout sauf la barre oblique (/) ; ** franchit les limites de répertoires. Par exemple logs/**/*.log attrape les fichiers .log à n'importe quelle profondeur sous logs.
• Un / initial ancre le motif à la racine : /build n'exclut que le dossier build de la racine, pas les build des sous-dossiers.
• Un / final ne vise que les dossiers : build/ n'exclura pas un fichier du même nom.
• ! ré-inclut un fichier exclu par une règle antérieure — mais si le dossier parent du fichier est entièrement ignoré, la négation ne sert à rien, car Git ne regarde jamais à l'intérieur de ce dossier.

Un exemple de .gitignore typique

Dans un projet Laravel + Node, le .gitignore racine ressemble à peu près à ceci :

# Dépendances
/node_modules
/vendor

# Environnement et secrets
.env
.env.*
!.env.example

# Sorties de build
/public/build
/dist

# Logs et fichiers temporaires
*.log
/storage/*.key

# Éditeur et système
.DS_Store
.idea/
.vscode/
Thumbs.db

À noter : .env.* exclut tous les fichiers d'environnement, tandis que la ligne !.env.example garde volontairement le modèle d'exemple suivi — les nouveaux développeurs s'en servent pour remplir leur propre .env.

Exclure un fichier déjà suivi

Supposons que vous ayez oublié d'ignorer node_modules/ au départ et que vous l'ayez commité. L'ajouter à .gitignore ne suffit plus ; il faut retirer les fichiers du suivi de Git. La solution est de les sortir de l'index sans les supprimer du disque :

git rm -r --cached node_modules
git commit -m "chore: ne plus suivre node_modules"

L'option --cached est essentielle : les fichiers restent dans votre répertoire de travail et ne quittent que l'index de Git. Après ce commit, la règle de .gitignore entre en jeu et les fichiers ne sont plus rajoutés. Pour un seul fichier, git rm --cached fichier suffit.

gitignore global : faire taire les résidus personnels partout

Des fichiers comme .DS_Store, .idea/ ou *.swp sont propres à votre système ou à votre éditeur ; les ajouter au .gitignore de chaque projet est injuste envers vos collègues. La bonne approche est un gitignore global :

git config --global core.excludesFile ~/.gitignore_global

Vous écrivez ensuite vos motifs personnels dans ~/.gitignore_global. Ces règles ne s'appliquent que sur votre machine, dans tous vos dépôts, sans polluer le fichier du projet.

Modèles prêts à l'emploi et débogage

Inutile d'écrire chaque langage à partir de zéro. Le dépôt officiel github/gitignore propose des modèles prêts pour des centaines de langages et d'outils, tandis que gitignore.io génère un fichier combiné selon les technologies choisies. Servez-vous-en comme point de départ, puis adaptez à votre projet.

Pour savoir pourquoi un fichier est ignoré, ne devinez pas — demandez à Git :

git check-ignore -v dist/app.js

Cette commande indique quelle ligne de quel .gitignore a exclu le fichier. Si vous devez tout de même ajouter un fichier ignoré, forcez-le avec git add -f fichier.

Questions fréquentes

Pourquoi un fichier ajouté à .gitignore est-il toujours commité ?

Le fichier est sans doute déjà suivi. .gitignore n'agit que sur les fichiers non suivis. Retirez-le de l'index avec git rm --cached fichier, puis commitez ; la règle s'applique ensuite.

Comment inclure un dossier vide dans le dépôt ?

Git ne suit pas les répertoires vides. La convention consiste à placer dans le dossier un fichier vide nommé .gitkeep (ce n'est pas une fonctionnalité officielle de Git, juste une convention) et à commiter ce fichier pour conserver le dossier.

J'ai publié un fichier .env par erreur — que faire ?

Retirez d'abord le fichier du suivi avec git rm --cached .env et ajoutez-le à .gitignore. Mais souvenez-vous qu'il reste dans les anciens commits : s'il était vraiment secret, changez immédiatement tous les mots de passe et jetons qu'il contient — nettoyer l'historique ne suffit pas comme garantie.

Garder ses dépôts propres est un gain modeste mais durable. Si vous souhaitez revoir votre configuration Git, votre flux de déploiement ou bien démarrer un projet correctement dès le départ, contactez-moi.