Le scénario que ce fichier évite
Vous rangez vos stacks Docker dans un dépôt — c’est le pattern ① et l’objet de la section 5. Parmi elles, celle de votre forge, avec son docker-compose.yml et son .env.
Souvenez-vous de la leçon 2.2 : ce .env contient le mot de passe de la base de données de la forge.
Un matin, vous tapez git add ., vous enregistrez, vous publiez. Et le mot de passe de production de votre forge se retrouve dans un dépôt consultable par toute l’équipe — et dans son historique, pour toujours.
Le .gitignore est le fichier qui empêche cela. C’est le garde-fou le plus important de votre dépôt, et il tient en quelques lignes.
Le principe
Créez un fichier nommé .gitignore à la racine du dépôt. Chaque ligne décrit ce que Git doit ignorer : ces fichiers n’apparaîtront plus dans git status, et git add . ne les prendra jamais.
# Secrets
.env
# Journaux
*.log
C’est tout. Deux lignes utiles, et le scénario ci-dessus devient impossible.
Ce fichier se versionne, contrairement à ce que beaucoup croient. C’est même essentiel : il doit s’appliquer à tous vos collègues, pas seulement à vous. Il fait partie du dépôt au même titre que les scripts.
La syntaxe, en sept règles
| Écriture | Effet |
|---|---|
secrets.txt |
Ce nom de fichier, où qu’il se trouve dans le dépôt |
/secrets.txt |
Uniquement à la racine du dépôt |
logs/ |
Le dossier logs et tout son contenu |
*.log |
Tous les fichiers portant cette extension |
**/temp/ |
Les dossiers temp à n’importe quel niveau |
!important.log |
Exception : ne pas ignorer ce fichier |
# commentaire |
Ligne ignorée |
Deux subtilités qui font perdre du temps.
La barre oblique initiale ancre à la racine. Sans elle, la règle s’applique partout. config.json ignore tous les fichiers de ce nom dans l’arborescence ; /config.json seulement celui du dessus.
La barre oblique finale désigne un dossier. build/ ignore le dossier ; build ignorerait aussi un fichier portant ce nom.
L’ordre compte
Les règles sont évaluées dans l’ordre, et la dernière qui correspond l’emporte. Une exception doit donc venir après la règle qu’elle contredit :
*.env # on ignore tous les .env
!.env.example # sauf celui-ci
Écrit dans l’autre sens, l’exception serait annulée par la règle suivante.
⚠️ Une limite à connaître : on ne peut pas ré-inclure un fichier situé dans un dossier ignoré. Si vous ignorez secrets/, aucun !secrets/public.txt ne fonctionnera — Git n’entre même pas dans le dossier. Il faut alors ignorer le contenu plutôt que le dossier : secrets/* puis !secrets/public.txt.
Un .gitignore pour un dépôt d’administration système
Voici une base à adapter. Elle couvre les trois familles de fichiers qui posent problème dans nos dépôts.
# ─── Secrets et variables d'environnement ────────────────
.env
.env.*
!.env.example
*.pem
*.key
*.pfx
credentials.*
secrets/
# ─── Sorties d'exécution ─────────────────────────────────
*.log
logs/
*.tmp
*.bak
*.old
output/
rapports/
# ─── Exports volumineux ──────────────────────────────────
*.zip
*.iso
*.vhdx
*.bak.sql
dumps/
# ─── Artefacts des systèmes et des éditeurs ──────────────
Thumbs.db
desktop.ini
.DS_Store
.vscode/
.idea/
*.swp
# ─── PowerShell ──────────────────────────────────────────
*.ps1xml
Modules/*/ # modules téléchargés, pas les vôtres
Trois commentaires sur ce contenu.
La première section est la plus importante. Le !.env.example est délibéré, et nous y revenons plus bas.
La troisième évite un problème durable. Un fichier volumineux enregistré une fois reste dans l’historique définitivement, même supprimé ensuite. Un .vhdx de 40 Go poussé par erreur alourdira chaque clone du dépôt pour l’éternité. Nous verrons pourquoi en section 5.
La quatrième est une question de politesse. Vos préférences VS Code n’ont rien à faire dans le dépôt de l’équipe. Cela dit, elles ont plutôt leur place dans votre configuration globale — voir plus bas.
⚠️ Le point que tout le monde découvre trop tard
Le .gitignore ne s’applique qu’aux fichiers non suivis.
Autrement dit : si un fichier a déjà été enregistré une fois, l’ajouter au .gitignore ne change rien. Git continue de le suivre, ses modifications continuent d’apparaître, et il continuera de partir sur la forge.
C’est la source d’incompréhension numéro un sur ce fichier.
Comment retirer un fichier du suivi
git rm --cached .env
git commit -m "Retrait du .env du suivi Git"
L’option --cached est essentielle : elle retire le fichier du suivi, sans le supprimer de votre disque. Sans elle, git rm effacerait votre configuration de production.
Pour un dossier entier :
git rm -r --cached logs/
Et ce qui est déjà dans l’historique ?
Voici la mauvaise nouvelle, et elle est importante.
Retirer un fichier du suivi ne l’efface pas de l’historique. Les enregistrements passés le contiennent toujours, et n’importe qui ayant accès au dépôt peut le consulter :
git log --all --full-history -- .env
Si ce fichier contenait un mot de passe, le mot de passe est compromis. La première mesure à prendre n’est pas une commande Git : c’est de le changer.
La purge réelle de l’historique existe, elle est délicate, et nous lui consacrerons la leçon 5.6.
Déboguer une règle
Un fichier apparaît toujours alors que vous pensiez l’avoir ignoré ? Une seule commande à connaître :
git check-ignore -v config/local.json
.gitignore:4:*.json config/local.json
Elle vous dit quelle règle, dans quel fichier, à quelle ligne s’applique. Si elle ne renvoie rien, aucune règle ne correspond — et le fichier est peut-être simplement déjà suivi.
Pour voir tout ce qui est ignoré dans le dépôt :
git status --ignored
Les trois niveaux
Le .gitignore du dépôt n’est pas le seul mécanisme.
| Fichier | Portée | Versionné | Pour quoi |
|---|---|---|---|
.gitignore |
Le dépôt, pour tout le monde | ✅ | Les règles du projet |
.git/info/exclude |
Ce dépôt, chez vous seul | ❌ | Vos fichiers de travail temporaires |
| Fichier global | Tous vos dépôts | ❌ | Vos outils personnels |
Le fichier global : à configurer une fois
Vos artefacts d’éditeur et de système ne concernent que vous. Plutôt que de les imposer à chaque dépôt :
git config --global core.excludesFile ~/.gitignore_global
Puis, dans ~/.gitignore_global :
.DS_Store
Thumbs.db
desktop.ini
.vscode/
.idea/
*.swp
Cinq minutes une fois, et vous ne polluerez plus jamais un dépôt d’équipe avec vos préférences.
.git/info/exclude : le local ponctuel
Pour les fichiers propres à votre poste dans un dépôt donné — un jeu de données de test, un script de dépannage temporaire — sans imposer la règle aux autres.
Deux compléments utiles
Le fichier d’exemple
Ignorer le .env pose un problème pratique : comment un collègue saura-t-il quelles variables renseigner ?
La convention est de versionner un modèle :
# .env.example ← celui-ci est versionné
DB_PASSWORD=changez-moi
FORGEJO_DOMAIN=forge.exemple.local
Les noms des variables sont documentés, les valeurs sont factices. C’est pour cela que le .gitignore proposé plus haut contient !.env.example.
Nous systématiserons cette pratique en section 5, pour toutes vos stacks Docker.
Conserver un dossier vide
Git ne suit que des fichiers, jamais des dossiers. Un dossier vide n’existe donc pas pour lui — et disparaîtra au clone.
Si votre script attend un dossier logs/ en place, créez-y un fichier témoin :
touch logs/.gitkeep
Puis, dans le .gitignore :
logs/*
!logs/.gitkeep
La structure est préservée, le contenu est ignoré.
Les erreurs classiques
| Symptôme | Cause |
|---|---|
| Le fichier apparaît malgré la règle | Il est déjà suivi : git rm --cached |
| La règle semble ignorée | Vérifiez avec git check-ignore -v |
Une exception ! ne fonctionne pas |
Le dossier parent est ignoré : ignorez son contenu plutôt que lui |
| Le dossier vide a disparu au clone | Ajoutez-y un .gitkeep |
| Un collègue voit encore le fichier | Il ne l’a pas retiré de son suivi local, ou n’a pas tiré |
Le .gitignore lui-même est ignoré |
Quelqu’un a écrit .git* quelque part |
Ce qu’il faut retenir
- Le
.gitignorese versionne : il s’applique à toute l’équipe. - Les secrets d’abord :
.env, clés, certificats. C’est sa raison d’être principale. - La barre initiale ancre à la racine, la barre finale désigne un dossier.
- La dernière règle qui correspond l’emporte : les exceptions viennent après.
- ⚠️ Il ne s’applique qu’aux fichiers non suivis :
git rm --cachedpour les autres. - Retirer du suivi n’efface pas de l’historique — si c’était un secret, changez-le.
git check-ignore -vindique quelle règle s’applique.- Configurez un fichier global pour vos artefacts d’éditeur.
- Versionnez un
.env.examplepour documenter les variables attendues.
Dans la leçon suivante
Votre dépôt est propre et protégé. Il est temps d’apprendre à l’interroger.
Nous verrons comment mener une enquête dans l’historique : retrouver quand une ligne a été introduite, qui l’a écrite et pourquoi, comparer deux états éloignés dans le temps, et retrouver un enregistrement à partir d’un mot-clé.
C’est le moment où Git cesse d’être un outil de sauvegarde pour devenir un outil d’investigation — celui qui répond en une minute à la question du lundi matin de la leçon 1.3.