Fichier .gitignore : exclure des fichiers de Git et retirer ceux déjà suivis

Le mécanisme gitignore permet de dire à Git : « ne touche pas à ces fichiers, ne les affiche pas dans git status et ne les ajoute pas avec git add . ». Les règles s'écrivent dans un fichier texte .gitignore, commité avec le projet et valable pour toute l'équipe. La subtilité principale : l'ignore ne s'applique qu'aux fichiers que Git ne suit pas encore.

Que mettre dans un .gitignore

• Les dépendances : node_modules/, vendor/, .venv/ — le gestionnaire de paquets les réinstalle.
• Les artefacts de build : dist/, build/, *.class, __pycache__/.
• Les logs et fichiers temporaires : *.log, tmp/, *.swp.
• Les secrets et réglages locaux : .env, clés, configs locales.
• Les fichiers parasites de l'OS et des éditeurs : .DS_Store, Thumbs.db, .idea/ — même s'il vaut mieux les placer dans l'ignore global, voir plus bas.

La règle est simple : le dépôt doit contenir ce que les humains écrivent, pas ce que les programmes génèrent ni ce qui dépend d'une machine précise.

Créer un fichier .gitignore

C'est un simple fichier texte à la racine du dépôt. Créez-le, écrivez un motif par ligne et commitez-le :

cat > .gitignore <<'EOF'
# dépendances
node_modules/
# build
dist/
# logs
*.log
# secrets
.env
EOF

git add .gitignore
git commit -m "chore: ajout du .gitignore"

Des modèles prêts à l'emploi pour les langages et frameworks courants se trouvent dans le dépôt github/gitignore ; GitHub et GitLab proposent d'en choisir un à la création du projet. Partez de là et retirez le superflu.

Syntaxe des motifs .gitignore

Nuance importante : un motif sans slash interne (config.json) s'applique à tout niveau, alors qu'un motif avec un slash au début ou au milieu (/config.json, src/config.json) est relatif au dossier qui contient ce .gitignore.

Exceptions avec le point d'exclamation

*.log
!important.log

Piège : impossible de « récupérer » un fichier si son dossier parent est ignoré. Git n'entre pas dans les dossiers ignorés, donc ceci ne fonctionne pas :

logs/
!logs/keep.txt     # ne fonctionne pas

La bonne méthode : ignorer le contenu, pas le dossier :

logs/*
!logs/keep.txt

La même astuce sert à conserver un dossier vide dans le dépôt : Git ne stocke pas les répertoires vides, on y place donc un fichier .gitkeep et on n'autorise que lui.

Où définir d'autres règles d'ignore

Les fichiers parasites de votre OS et de votre IDE ont leur place dans l'ignore global, pour ne pas encombrer le .gitignore commun :

git config --global core.excludesFile ~/.gitignore_global
echo ".DS_Store" >> ~/.gitignore_global
echo ".idea/" >> ~/.gitignore_global

Si core.excludesFile n'est pas défini, Git lit ~/.config/git/ignore s'il existe.

Pourquoi le .gitignore ne fonctionne pas

La plainte la plus fréquente : « j'ai ajouté le fichier au .gitignore, mais Git affiche toujours ses modifications ». La cause est presque toujours la même : le fichier est déjà suivi. L'ignore n'a aucun effet sur un fichier qui a été commité au moins une fois.

Pour savoir quelle règle s'applique (ou pourquoi elle ne s'applique pas), utilisez git check-ignore :

git check-ignore -v logs/app.log
# .gitignore:3:*.log	logs/app.log

La sortie indique le fichier et la ligne de la règle. Une sortie vide signifie que le fichier n'est pas ignoré. Autres causes de dysfonctionnement : des espaces en fin de ligne dans un motif ou un mauvais encodage du fichier (par exemple UTF-16 s'il a été créé via PowerShell).

Retirer du dépôt un fichier déjà commité : git rm --cached

La commande git rm supprime le fichier de l'index et du disque. Avec l'option --cached, seulement de l'index : le fichier reste chez vous mais n'est plus suivi.

echo ".env" >> .gitignore
git rm --cached .env
git commit -m "chore: .env n'est plus suivi"
git push

Pour un dossier, ajoutez -r :

git rm -r --cached node_modules/

S'il y a beaucoup de règles et que vous ne savez plus ce qui est déjà dans le dépôt, vous pouvez reconstruire l'index entièrement : git rm -r --cached ., puis git add . et un commit. Avant de commiter, vérifiez git status : les fichiers retirés de l'index y apparaissent.

Attention : les secrets restent dans l'historique

git rm --cached retire le fichier des commits suivants, pas des précédents. Si un mot de passe ou un token a atterri dans le dépôt, il reste accessible dans l'historique à quiconque possède un clone. Considérez le secret comme compromis et régénérez-le. Des outils comme git filter-repo permettent de réécrire l'historique, mais cela change les hashes de tous les commits suivants et doit être coordonné avec l'équipe.

Autre conséquence : chez vos collègues, après git pull, un fichier retiré de l'index via --cached sera supprimé du disque. Pour .env, prévenez l'équipe à l'avance ou gardez un modèle .env.example dans le dépôt.

git rm : supprimer des fichiers

git rm old.py              # supprimer du disque et de l'index
git rm -r legacy/          # supprimer un dossier
git rm -n '*.tmp'          # dry run : afficher ce qui serait supprimé
git rm -f changed.py       # supprimer un fichier avec des modifications non commitées

Si vous supprimez un fichier avec un simple rm, Git le voit comme « deleted » et il faut ensuite indexer la suppression avec git add ou git rm. git rm fait les deux d'un coup. Sans -f, il refuse de supprimer un fichier contenant des modifications non commitées : c'est une protection contre la perte de travail.

git mv : renommer et déplacer

git mv utils.py helpers.py
git mv helpers.py src/helpers.py

git mv est un raccourci pour mv + git rm de l'ancien chemin + git add du nouveau. Git n'enregistre pas le renommage en tant que tel : il le déduit de la similarité du contenu lors de git status, git log --follow et git diff. Un renommage et un mv classique suivi de git add -A donnent donc le même résultat.

Conseil pratique : renommez et modifiez le contenu d'un fichier dans des commits séparés. Si le fichier change beaucoup en même temps qu'il est renommé, Git risque de ne pas le reconnaître comme le même fichier, et l'historique via --follow sera interrompu.

Pour ne changer que la casse d'un nom sous Windows et macOS (systèmes de fichiers insensibles à la casse), utilisez git mv readme.md README.md : un simple renommage dans l'explorateur peut passer inaperçu pour Git.

Ordre des règles et priorité

Dans un même fichier, les règles sont lues de haut en bas et la dernière qui correspond l'emporte. L'exception !keep.log doit donc se trouver sous la règle *.log, sinon elle sera écrasée. Entre fichiers, la priorité est la suivante : un .gitignore de sous-dossier l'emporte sur celui de la racine, et l'ignore global ainsi que .git/info/exclude ont la priorité la plus basse.

Exemple de .gitignore pour un projet web

Voici une version opérationnelle pour un projet Node.js avec un backend Python. Notez les commentaires : dans six mois, personne ne se souviendra pourquoi telle règle a été ajoutée.

# --- dépendances ---
node_modules/
.venv/

# --- build et caches ---
/dist
/build
__pycache__/
*.pyc
.pytest_cache/
coverage/

# --- logs ---
*.log
npm-debug.log*

# --- environnement et secrets ---
.env
.env.*
!.env.example

# --- uploads des utilisateurs, mais on garde le dossier ---
uploads/*
!uploads/.gitkeep

Les deux techniques d'exception sont utilisées ici : .env.* masque toutes les variantes locales d'environnement, mais le modèle .env.example reste dans le dépôt, et le dossier uploads existe dans le clone grâce à .gitkeep.

Ce qu'il ne faut pas ignorer

En faire trop avec l'ignore est aussi nuisible. Les lockfiles de dépendances — package-lock.json, poetry.lock, composer.lock — sont généralement commités dans les applications : ils garantissent que tous les développeurs et la CI installent les mêmes versions de paquets. Les réglages de formatage partagés (.editorconfig, configs de linters) doivent aussi vivre dans le dépôt.

Cas discutable : les réglages de l'IDE. Le dossier .vscode/ est souvent ignoré en entier, mais on commite parfois les extensions recommandées et les tâches de build : .vscode/*, puis !.vscode/extensions.json. C'est à l'équipe de décider ; l'essentiel est de ne pas garder de chemins personnels ni de clés dans le dépôt commun.

Scénario : node_modules commité par erreur

Erreur classique de débutant : git add . avant de créer le .gitignore, et des dizaines de milliers de fichiers partent dans le commit. La correction en trois étapes :

echo "node_modules/" >> .gitignore
git rm -r --cached node_modules
git commit -m "chore: node_modules retiré du dépôt"

Si le commit n'a pas encore été poussé sur le serveur, il est plus propre de le réécrire pour que les fichiers lourds ne restent pas dans l'historique : git reset --soft HEAD~1, puis les mêmes commandes et un nouveau commit. Après un push, les fichiers sont déjà dans l'historique et la taille du clone ne diminuera pas sans réécriture de l'historique.

Pour éviter que cela se reproduise, créez le .gitignore avant le premier git add et prenez l'habitude de regarder git status avant chaque commit : une liste de nouveaux fichiers étrangement longue est un signal pour s'arrêter.

En résumé

Le .gitignore est le premier fichier à commiter dans un nouveau projet : dépendances, builds, logs et secrets n'ont rien à faire dans le dépôt. L'ignore ne fonctionne que pour les fichiers non suivis : ce qui est déjà ajouté se retire avec git rm --cached, et les règles se vérifient avec git check-ignore -v. Pour supprimer et renommer, utilisez git rm et git mv afin que les changements arrivent directement dans l'index. Le travail avec l'index et un premier dépôt est abordé en pratique dans le cours Git.