Introduction

Un fichier .gitignore liste les motifs que Git doit traiter comme non suivis et ne jamais proposer d'ajouter. Il garde les artefacts de build, les secrets, les métadonnées de l'OS et les fichiers temporaires d'éditeur hors de votre dépôt.

Syntaxe des motifs

• name : correspond aux fichiers ou répertoires nommés name à toute profondeur.
• /name : correspond seulement à la racine du dépôt.
• name/ : correspond aux répertoires uniquement.
• *.log : glob ; correspond à tout fichier .log.
• **/build : correspond à build à toute profondeur.
• !important.log : ré-inclure un chemin précédemment ignoré.
• # en début de ligne est un commentaire.

Un exemple réaliste

# .gitignore
# Sortie de build
/dist/
/build/
*.o
*.pyc

# Dépendances
/node_modules/
/vendor/

# Éditeurs
.idea/
.vscode/
*.swp

# OS
.DS_Store
Thumbs.db

# Secrets
.env
*.pem

Plusieurs fichiers .gitignore

Vous pouvez placer un .gitignore à n'importe quel niveau. Les motifs sont relatifs au répertoire du fichier, et les fichiers plus profonds remplacent les moins profonds. Il existe également un fichier d'exclusion global pour vos préférences personnelles :

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

Utilisez-le pour les fichiers temporaires d'éditeur et les déchets d'OS, pas pour les chemins spécifiques au projet.

Suivre des fichiers déjà suivis

Ajouter un chemin à .gitignore ne le supprime pas du dépôt. Arrêter de suivre un fichier tout en le gardant sur disque :

git rm --cached secrets.env
git commit -m "Stop tracking secrets.env"

Déboguer les ignores

Pourquoi Git ignore-t-il (ou n'ignore-t-il pas) un chemin ? Demandez :

git check-ignore -v path/to/file

La sortie nomme le fichier et la ligne qui correspondent.

Ordre d'évaluation

Git évalue les règles d'exclusion à partir de plusieurs sources, dans cet ordre : arguments de ligne de commande, puis les fichiers .gitignore par répertoire (le plus profond d'abord), puis $GIT_DIR/info/exclude, et enfin le core.excludesFile global. Les règles ultérieures (plus spécifiques) remplacent les antérieures, et une négation (!pattern) ne ré-inclut un chemin que si son répertoire parent n'est pas lui-même exclu. Cette dernière règle piège beaucoup d'utilisateurs :

# Mauvais : impossible de désigner un fichier dans un répertoire ignoré
/build/
!/build/keep.log

# Correct : ignorer le contenu mais garder le répertoire
/build/*
!/build/keep.log

Exclusions par dépôt et globales

Deux mécanismes d'exclusion supplémentaires complètent .gitignore. Le fichier non suivi par dépôt .git/info/exclude ne s'applique qu'à votre clone (bon pour les fichiers d'IDE que vous ne voulez pas commiter dans le .gitignore de toute l'équipe). Le core.excludesFile global s'applique à tous vos dépôts :

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

Utilisez-les pour les préférences personnelles ; réservez le .gitignore commité aux règles d'équipe.

Erreurs fréquentes

Ajouter secrets.env à .gitignore après qu'il a déjà été commité et supposer que le secret a disparu. Il est toujours dans l'historique ; faites tourner le secret et envisagez d'utiliser git filter-repo pour le purger. Autre piège : ignorer un répertoire avec build alors que vous vouliez /build, supprimant accidentellement un fichier nommé build en profondeur dans l'arborescence. Enfin, commiter .gitignore lui-même est essentiel ; sans lui, chaque collaborateur doit inventer ses propres règles d'exclusion. .gitignore appartient au dépôt, pas à l'extérieur.