3.6 : Le .gitignore : ce qui ne doit jamais monter

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 .gitignore se 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 --cached pour les autres.
  • Retirer du suivi n’efface pas de l’historique — si c’était un secret, changez-le.
  • git check-ignore -v indique quelle règle s’applique.
  • Configurez un fichier global pour vos artefacts d’éditeur.
  • Versionnez un .env.example pour 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.