.gitignore
Découvrez les motifs ignorés par Git, les règles globales et personnelles, comment valider, remiser et déboguer les fichiers .gitignore.
Vue d'ensemble
Dans une copie de travail, Git voit chaque fichier dans l'un de ces trois états : suivi (déjà dans le dépôt ou indexé), non suivi (nouveau et pas encore indexé), ou ignoré (délibérément exclu). Ce chapitre explique comment faire ignorer des fichiers par Git à l'aide d'un fichier .gitignore : la syntaxe des motifs, où les règles d'exclusion peuvent résider (par répertoire, par dépôt et globalement), et comment gérer les cas délicats — ignorer un fichier déjà validé, forcer la validation d'un fichier ignoré, remiser des fichiers ignorés, et déboguer pourquoi un fichier est ignoré.
Les fichiers ignorés sont ceux que vous avez indiqué à Git de ne pas prendre en compte. Ils ne sont jamais indexés, jamais validés, et n'apparaissent jamais sous git status comme bruit non suivi. Les candidats typiques sont les fichiers générés à partir des sources plutôt qu'écrits à la main :
- Fichiers créés à l'exécution — journaux, fichiers de verrouillage (
*.log,*.lock). - Métadonnées du système d'exploitation et de l'IDE —
.DS_Store,Thumbs.db,.idea/,.vscode/. - Sorties compilées et dépendances —
*.o,*.class,node_modules/,dist/. - Secrets et configuration locale —
.env, fichiers d'identification.
La règle générale : si un fichier peut être régénéré à partir des sources du dépôt, ou est spécifique à votre machine, ignorez-le.
Une règle .gitignore n'affecte que les fichiers non suivis. Si un fichier est déjà suivi par Git, l'ajouter à .gitignore ne change rien — Git continue de le suivre. Consultez Ignorer un fichier précédemment validé ci-dessous pour la solution.
Motifs d'exclusion Git
Les règles d'exclusion résident dans un fichier texte brut nommé .gitignore. Il n'existe pas de commande git ignore — vous créez et éditez le fichier manuellement, puis vous le validez comme n'importe quel autre fichier. Chaque ligne non vide est un motif comparé aux chemins de fichiers ; un fichier est ignoré lorsqu'il correspond à un motif.
Quelques règles s'appliquent au format du fichier lui-même :
- Une ligne vide ne correspond à rien et n'est utilisée que pour la lisibilité.
- Une ligne commençant par
#est un commentaire. Pour correspondre à un nom de fichier qui commence littéralement par#, échappez-le en\#. - Les espaces en fin de ligne sont ignorés, sauf si échappés avec une barre oblique inverse (
\). - Les motifs sont comparés relativement à l'emplacement du fichier
.gitignore.
Les motifs eux-mêmes sont construits à partir de ces symboles :
| Motif | Explication |
|---|---|
| **/logs | Les doubles astérisques permettent de correspondre aux répertoires n'importe où dans le dépôt |
| **/logs/debug.log | Les doubles astérisques permettent de correspondre aux fichiers selon leur nom et le nom de leur répertoire parent. |
| *.log | Un astérisque correspond à zéro ou plusieurs caractères. |
| *.log !important.log | Le point d'exclamation nie le motif. Un fichier ne sera pas ignoré s'il correspond à un motif négatif défini plus tard. |
| *.log !important/*.log trace.* | Un motif ultérieur peut re-ignorer un fichier précédemment dé-ignoré, à condition qu'il corresponde au même fichier. |
| /debug.log | Le slash correspond aux fichiers uniquement à la racine du dépôt. |
| debug.log | Par défaut, les motifs correspondent aux fichiers dans n'importe quel répertoire. |
| debug?.log | Le point d'interrogation correspond exactement à un seul caractère. |
| debug[0-9].log | Les crochets permettent de correspondre à un seul caractère d'une plage donnée. |
| debug[01].log | Les crochets correspondent à un seul caractère d'un ensemble donné. |
| debug[!01].log | Le point d'exclamation permet de correspondre à n'importe quel caractère sauf ceux de l'ensemble donné. |
| debug[a-z].log | Les plages peuvent être numériques ou alphabétiques. |
| logs | Le motif correspondra à la fois aux fichiers et au contenu des répertoires portant ce nom s'il n'est pas utilisé avec un slash. |
| logs/ | L'utilisation d'un slash indique que le motif est un répertoire. Tout le contenu de tout répertoire portant ce nom, avec ses fichiers et sous-répertoires dans le dépôt, sera ignoré par Git. |
| logs/**/debug.log | Un double astérisque correspond à zéro ou plusieurs répertoires. |
| logs/*day/debug.log | Les astérisques peuvent également être utilisés dans les noms de répertoires. |
Voici un petit .gitignore montrant comment debug?.log (le ? correspond exactement à un caractère) se comporte. Il ignore debug0.log et debug1.log, mais pas debug10.log, car 10 représente deux caractères :
motifs .gitignore
debug?.log
# matches debug0.log, debug1.log, debug9.log
# does NOT match debug10.log (two characters)Fichiers .gitignore partagés dans le dépôt
Vous pouvez définir plusieurs fichiers .gitignore dans différents répertoires du dépôt. Chacun des motifs est testé relativement au répertoire contenant ce fichier. Cependant, la façon la plus simple est de définir un seul fichier .gitignore à la racine du dépôt.
Comme votre fichier .gitignore est enregistré dans votre dépôt, il est versionné comme les autres fichiers et est partagé avec votre équipe lors de vos push. Vous devriez n'inclure dans .gitignore que des motifs bénéfiques aux autres utilisateurs du dépôt.
Règles personnelles pour Git ignore
Les motifs d'exclusion personnels pour un seul dépôt peuvent être placés dans le fichier spécial .git/info/exclude. Sa syntaxe est identique à celle de .gitignore, mais comme le répertoire .git ne fait pas partie du contenu du dépôt, ces règles ne sont pas versionnées et ne sont pas partagées lors d'un push ou d'un clone. Utilisez ce fichier pour les sauvegardes d'éditeur, les fichiers temporaires, ou tout ce qui est spécifique à votre propre flux de travail et que le reste de l'équipe ne devrait pas se voir imposer.
Règles globales Git ignore
Vous pouvez définir la propriété Git core.excludesFile pour spécifier en plus des motifs d'exclusion Git globaux pour tous les dépôts de votre système local. Ce fichier doit être créé par vous-même. Vous pouvez placer votre fichier .gitignore global dans votre répertoire personnel pour le retrouver facilement. Une fois le fichier créé, configurez son emplacement avec la commande git config, comme ceci :
règles gitignore globales
touch ~/.gitignore
git config --global core.excludesFile ~/.gitignoreIgnorer un fichier précédemment validé
L'ajout d'un motif à .gitignore n'empêche pas Git de suivre un fichier déjà validé — les règles d'exclusion s'appliquent uniquement aux fichiers non suivis. Pour commencer à ignorer un tel fichier, vous devez d'abord le supprimer de l'index de Git. Utilisez git rm avec l'option --cached : cela indexe la suppression du fichier du dépôt tout en conservant la copie sur votre disque comme fichier ignoré. Validez ensuite la modification.
fichiers validés .gitignore
echo debug.log >> .gitignore
git rm --cached debug.log
#rm 'debug.log'
git commit -m "Start ignoring debug.log"Si vous souhaitez également supprimer le fichier de votre répertoire de travail, retirez --cached (git rm debug.log). Utilisez git status ensuite pour confirmer que le fichier n'apparaît plus comme suivi ou non suivi.
Valider un fichier ignoré
Le fichier ignoré peut être validé dans le dépôt en combinant l'option -f (ou --force) avec git add. Cependant, choisissez cette méthode si vous avez un motif général, tel que *.log, mais souhaitez valider un fichier spécifique :
validation de fichiers ignorés
cat .gitignore
# *.log
git add -f debug.log
git commit -m "Force adding debug.log"Sinon, la façon la plus simple est de définir une exception à la règle générale :
valider des fichiers ignorés
echo '!debug.log' >> .gitignore
cat .gitignore
#*.log
#!debug.log
git add debug.log
git commit -m "Adding debug.log"Remiser un fichier ignoré
La commande git stash prend vos modifications non validées indexées et non indexées, les sauvegarde pour plus tard, et ramène votre copie de travail à un état propre. Par défaut, elle remise uniquement les modifications apportées aux fichiers suivis — les fichiers ignorés et non suivis restent en place. Deux options élargissent cette portée :
git stash --include-untracked(ou-u) remise également les fichiers non suivis.git stash --all(ou-a) remise à la fois les fichiers non suivis et ignorés.
git stash --allDéboguer les fichiers .gitignore
Avec des motifs complexes, ou des règles réparties dans plusieurs fichiers .gitignore, il peut être difficile de déterminer quelle règle masque un fichier. La commande git check-ignore avec -v (ou --verbose) indique le motif exact responsable :
git vérifier les fichiers ignorés
git check-ignore -v debug.log
#.gitignore:3:*.log debug.logLa sortie comporte quatre champs séparés par des deux-points (et un espace avant le nom du fichier) :
<file containing the pattern>:<line number of the pattern>:<pattern> <file name>Ainsi, .gitignore:3:*.log debug.log signifie : la règle *.log à la ligne 3 de .gitignore est ce qui provoque l'exclusion de debug.log. Si la commande n'affiche rien, le fichier n'est ignoré par aucune règle.
Chapitres associés
- git rm — supprimer des fichiers du suivi, la clé pour ignorer un fichier déjà validé.
- git add — indexer des fichiers, y compris
-fpour forcer l'ajout d'un fichier ignoré. - git stash — sauvegarder des modifications de côté ; combiner avec
--allpour inclure les fichiers ignorés. - git config — définir
core.excludesFilepour une liste d'exclusion globale. - git clean — supprimer les fichiers non suivis ; combiner avec
-xpour supprimer également les fichiers ignorés.