C'est quoi un fichier .gitignore ? Comment ça marche, avec des exemples

 Un fichier .gitignore est un fichier en texte brut qui indique à Git quels fichiers et dossiers exclure de ton dépôt. Tu y listes ce que tu veux ignorer, un motif par ligne, et Git cesse de proposer ces fichiers lorsque tu prépares et valides ton travail.

Si tu as déjà ouvert un projet et trouvé un fichier nommé .gitignore à côté du code, ce guide t’explique ce qu’il fait là. Il explique comment fonctionne ce fichier, ce qu’on y met généralement, les règles de motifs, et comment résoudre le problème le plus courant : un fichier que Git continue de suivre même après que tu l’as ignoré.

Comment fonctionne un fichier .gitignore

Point clé : Git lit le fichier .gitignore avant de décider quels nouveaux fichiers te montrer, et ignore tout ce qui correspond à un motif qu’il contient.

Git est l’outil que la plupart des développeurs utilisent pour suivre les modifications apportées à leur code. Il surveille le dossier d’un projet et détecte chaque fichier nouveau ou modifié. Sans instructions, il te proposerait de tout enregistrer, y compris les mots de passe, les bibliothèques téléchargées et les fichiers temporaires que ton ordinateur crée de lui-même.

Un fichier .gitignore, c’est cet ensemble d’instructions. Il se trouve généralement dans le dossier racine d’un projet, et chaque ligne décrit les fichiers à ignorer. Quand tu lances `git status` pour voir ce qui a changé, ou `git add` pour préparer des fichiers à un commit, Git vérifie chaque nouveau fichier par rapport à ces lignes. Les fichiers qui correspondent restent invisibles.

Ce fichier n’affecte que les fichiers que Git ne suit pas encore. La documentation de Git explique que son but est de maintenir les fichiers non suivis hors du suivi ; ainsi, un fichier qui a déjà été validé reste suivi jusqu’à ce que tu le retires du suivi (voir les erreurs courantes ci-dessous). Quelques autres détails déterminent son fonctionnement :

• Le fichier .gitignore est validé comme n’importe quel autre fichier ; ainsi, tous ceux qui clonent le projet bénéficient des mêmes règles.
• Un fichier .gitignore situé dans un sous-dossier s’applique à ce dossier et à tout ce qu’il contient.
• Les règles qui ne s’appliquent que sur ta machine, comme les fichiers créés par ton éditeur, peuvent être placées dans un fichier d’exclusion global ou dans .git/info/exclude, qui n’est jamais partagé.

Que mettre dans un fichier .gitignore

Point clé : ignore tout ce qui est confidentiel, tout ce qui peut être recréé, et tout ce qui est spécifique à la machine d’une seule personne.

La plupart des entrées se répartissent en cinq catégories :

Voici un petit fichier .gitignore pour un projet web classique. Les lignes qui commencent par # sont des commentaires, que Git ignore.

# Secrets and local settings
.env
.env.local

# Dependencies
node_modules/
vendor/

# Build output
dist/

# Logs
*.log

# Editor and operating system files
.DS_Store
.idea/
.vscode/

Tu as rarement besoin d’en écrire un à partir de zéro. GitHub propose une collection publique de modèles de fichiers .gitignore pour la plupart des langages et des frameworks, et de nombreux modèles de démarrage de projet en créent un pour toi.

Faut-il inclure le fichier .env dans le .gitignore ?

Point clé : oui. Ignore ton fichier .env et valide un fichier .env.example contenant des valeurs par défaut pour que tes collègues sachent de quels paramètres le projet a besoin.

Un fichier .env contient les paramètres que ton application lit au démarrage, notamment souvent les mots de passe de base de données et les clés API. (Notre guide « Qu’est-ce que .env ? » aborde ce sujet en détail.) Comme ces valeurs sont confidentielles, le fichier .env est généralement la première ligne de tout fichier .gitignore.

Un nouveau coéquipier qui clone le projet n’obtient pas de fichier .env ; il ne peut donc pas savoir quels paramètres l’application attend. La solution courante consiste à créer un deuxième fichier, .env.example, qui répertorie les mêmes noms avec des valeurs factices. Tu peux le valider en toute sécurité, car rien dedans n’est réel. Chaque développeur le copie dans .env et y remplit ses propres valeurs.

# .env.example
DATABASE_URL=your-database-url-here
PAYMENT_API_KEY=your-key-here

Ignorer le fichier .env te protège à partir de maintenant. Ça ne change rien au passé : si un secret a déjà été validé, il reste dans l’historique du projet. La meilleure chose à faire, c’est de remplacer ce mot de passe ou cette clé par un nouveau, puis de retirer le fichier du suivi.

Est-ce que .gitignore empêche les agents de codage IA de lire .env ?

Point clé : non. Le fichier .gitignore empêche Git d’indexer les fichiers, mais ne les rend pas inaccessibles. Les agents de codage IA présents sur ta machine peuvent lire tout ce que ton compte utilisateur peut lire.

Un agent de codage IA tel que Cursor, Claude Code ou Codex fonctionne à l’intérieur de ton dossier de projet, avec le même accès aux fichiers que toi. Le fichier .gitignore indique à Git ce qu’il faut exclure des commits. Il ne cache pas les fichiers aux autres programmes en cours d’exécution sur ton ordinateur ; un agent peut donc ouvrir ton fichier .env, afficher ses valeurs ou les coller dans un chat.

La plupart des outils te proposent un moyen spécifique d’empêcher les agents d’accéder aux fichiers sensibles :

• Cursor ignore par défaut les fichiers listés dans .gitignore, ainsi que les fichiers .env, et tu peux ajouter d’autres motifs dans un fichier .cursorignore. La documentation de Cursor précise que le terminal de l’agent et les outils MCP peuvent toujours lire les fichiers ignorés.
• Claude Code te permet d’ajouter des règles de refus dans son fichier de paramètres, comme une règle qui bloque la lecture des fichiers .env.

Considère ces mesures comme un filet de sécurité, pas comme une garantie. La configuration la plus sûre consiste à ne conserver que les clés de développement ou de test dans ton fichier .env local, et à garder les secrets de production complètement hors de ta machine.

Aide-mémoire sur la syntaxe de .gitignore

Point clé : quelques symboles suffisent pour couvrir presque tous les cas. Une barre oblique finale désigne uniquement les dossiers, un astérisque correspond à n’importe quel caractère et un point d’exclamation crée une exception.

Deux règles posent le plus souvent problème. Premièrement, en cas de conflit entre deux lignes, c’est la plus récente qui prévaut ; place donc les exceptions après la règle qu’elles remplacent. Deuxièmement, tu ne peux pas définir d’exception pour un fichier situé dans un dossier que tu as entièrement ignoré, car Git ne regarde jamais à l’intérieur de ce dossier. Ignore le contenu du dossier (logs/*) plutôt que le dossier lui-même si tu as besoin d’exceptions à l’intérieur.

Erreurs courantes dans le fichier .gitignore et comment les corriger

Point clé : si Git suit toujours un fichier que tu as ignoré, c’est qu’il a été validé en premier. Supprime-le de la liste des fichiers suivis avec `git rm --cached` et valide la modification.

Le fichier avait déjà été validé

C’est généralement la raison pour laquelle un fichier .gitignore semble ne pas fonctionner. Git ignore uniquement les fichiers qu’il ne suit pas encore. Pour cesser de suivre un fichier tout en conservant ta copie locale, exécute :

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

Pour un dossier entier, ajoute -r, comme dans `git rm -r --cached node_modules`. Tes fichiers restent sur ton ordinateur. Ils disparaissent du dépôt à partir de la prochaine validation, même s’ils restent dans son historique.

Le motif ne correspond pas à ce que tu penses

Pour voir quelle ligne, dans quel fichier, ignore un chemin, lance git check-ignore -v suivi du chemin. Si rien ne s'affiche, aucune règle ne correspond.

Il y a un hic : par défaut, la commande ignore les fichiers que Git suit déjà ; elle n’affiche donc rien pour ceux-ci, même lorsqu’une règle correspond. Ajoute --no-index pour vérifier l’un d’entre eux :

git check-ignore -v --no-index .env

Le fichier n’est pas au bon endroit ou porte un nom incorrect

Le fichier doit s’appeler exactement .gitignore, avec le point au début et sans extension. Le Bloc-notes sous Windows, par exemple, peut l’enregistrer sous le nom .gitignore.txt. Les règles sont également lues par rapport au dossier dans lequel se trouve le fichier .gitignore.

Des fichiers personnels dans le fichier partagé

Les fichiers créés uniquement par ta configuration, comme le dossier de paramètres d’un éditeur, ont tout intérêt à être conservés dans ton fichier d’ignorance global. Ça permet au fichier .gitignore partagé de rester concentré sur ce qui compte pour l’ensemble du projet.

Par langage et framework

Point clé : chaque langage laisse sa propre trace de paquets installés et de fichiers de compilation. Ignore-les, et conserve les fichiers qui décrivent ce qu’il faut installer.

Les « secrets » et les fichiers superflus liés à l’éditeur mentionnés plus haut s’appliquent à tous les projets. Les autres éléments à ignorer dépendent du langage, car chacun installe ses paquets et ses fichiers de compilation dans ses propres dossiers :

Le principe est le même à chaque ligne. Ignore ce qui peut être recompilé et valide les fichiers qui décrivent comment le recompiler, y compris le fichier de verrouillage. Notre guide « Qu'est-ce qu'un fichier de verrouillage ? » explique pourquoi le fichier de verrouillage a sa place dans Git.

De nombreux frameworks créent un fichier .gitignore de départ pour toi lorsque tu lances un nouveau projet, notamment Laravel et Rails ; vérifie donc ce qui s’y trouve déjà avant d’ajouter des lignes. Pour tout ce qui manquerait, la collection de modèles .gitignore de GitHub propose un fichier prêt à l’emploi pour la plupart des langages et des frameworks.

Comment Upsun Cloud gère les secrets sans fichiers validés

Point clé : sur Upsun Cloud, les secrets sont stockés dans des variables au niveau du projet ou de l’environnement, et non dans des fichiers ; ton fichier .env peut donc rester ignoré et ton application obtient quand même les valeurs dont elle a besoin.

Upsun Cloud compile et déploie ton application à partir de ton dépôt Git ; un fichier .env ignoré n’y parvient donc jamais.

Les vrais mots de passe proviennent des variables que tu définis directement dans Upsun Cloud, via la console ou la ligne de commande. Deux niveaux sont importants ici :

• Les variables de projet s’appliquent à tous les environnements. Elles conviennent aux secrets qui sont identiques partout, comme les identifiants d’un service partagé.
• Les variables au niveau de l’environnement s’appliquent à un seul environnement, comme la production. Elles conviennent aux valeurs qui diffèrent, par exemple l’utilisation de clés de paiement de test dans un environnement de test et de clés de production en environnement de production.

Quelques options permettent de mettre ça en pratique. Marquer une variable comme sensible masque sa valeur dans la console et dans la sortie de la ligne de commande, tout en permettant à ton appli de continuer à la lire. Un secret réservé à la production peut être défini de manière à ce que les autres environnements ne l’héritent pas. Et en ajoutant le préfixe « env: » à une variable, celle-ci est exposée à ton appli comme une variable d’environnement ordinaire ; ainsi, le code qui lit déjà ses paramètres depuis l’environnement n’a pas besoin d’être modifié.

Par exemple, cette commande stocke une clé de paiement réservée à la production qui reste masquée et n’est pas transmise aux autres environnements :

upsun variable:create --level environment -e main --name env:PAYMENT_API_KEY --value ta-clé-ici --sensitive true --inheritable false

La documentation d’Upsun souligne également que les valeurs que tu définis dans le fichier de configuration du projet sont commitées dans Git, ce qui les rend peu adaptées aux secrets. Réserve-les aux paramètres que tu peux partager en toute sécurité. Ainsi, le fichier .gitignore empêche les secrets d’apparaître dans ton code, et les variables d’Upsun cloud les transmettent à l’application en cours d’exécution. Consulte la section « Définition des variables » dans la documentation d’Upsun pour découvrir toutes les options.

Ne néglige pas le fichier .environment

Upsun Cloud ne lit absolument pas les fichiers .env. En revanche, il lit un autre fichier, .environment, situé dans le dossier racine de ton application. Ce fichier s’exécute comme un script au démarrage du conteneur de ton application et permet de définir des variables d’environnement pour celle-ci. Les projets créés avec la commande upsun project:init peuvent déjà en comporter un, par exemple pour transmettre les informations de base de données sous le format attendu par un framework.

Malgré la similitude des noms, le fichier .environment doit être validé pour qu’Upsun Cloud puisse l’utiliser. Vérifie qu’aucun motif dans ton fichier .gitignore, tel que .env*, ne l’ignore par erreur. Comme il est validé, évite d’y mettre des informations confidentielles : il doit pointer vers des variables, et non contenir de mots de passe.

Upsun Cloud génère chaque environnement à partir de ton dépôt Git et stocke les informations confidentielles dans des variables ; un fichier .gitignore bien nettoyé suffit donc pour ton dépôt. Tu peux déployer gratuitement sur Upsun Cloud pendant 15 jours, sans avoir besoin d’une carte bancaire, ou découvrir comment fonctionne l’automatisation pilotée par Git.

Foire aux questions (FAQ)

À quoi sert un fichier .gitignore ?

Il indique à Git quels fichiers et dossiers ne doivent pas être inclus dans un dépôt. Les équipes l’utilisent pour exclure du code partagé les secrets, les bibliothèques installées, les résultats de compilation et les fichiers spécifiques à une machine.

Où faut-il placer le fichier .gitignore ?

En général, dans le dossier racine du projet, à côté du dossier caché .git. Tu peux ajouter d’autres fichiers .gitignore dans des sous-dossiers ; chacun s’applique à son propre dossier et à tout ce qu’il contient.

Dois-je valider le fichier .gitignore ?

Oui. Le valider permet de s’assurer que tous ceux qui travaillent sur le projet ignorent les mêmes fichiers.

Pourquoi mon fichier .gitignore ne fonctionne-t-il pas ?

Le fichier a probablement été validé avant que tu n’aies ajouté la règle. Exécute la commande `git rm --cached` dessus, puis valide-le. Si ce n’est pas la cause du problème, exécute la commande `git check-ignore -v` avec le chemin d’accès au fichier pour voir quelle règle s’applique, le cas échéant.

Est-ce que le fichier .gitignore supprime des fichiers ?

Non. Les fichiers ignorés restent sur ton ordinateur. Git empêche simplement qu’ils soient proposés lors des validations.

Est-ce que le fichier .gitignore empêche les agents de codage IA de lire mon fichier .env ?

Non. Il contrôle uniquement ce que Git valide. Utilise les paramètres d’ignorance ou d’autorisation de ton outil de codage, comme un fichier .cursorignore dans Cursor ou les règles de refus dans Claude Code, et garde les secrets de production hors de ton fichier .env local.

Est-ce que le fichier .gitignore supprime les secrets qui ont déjà été validés ?

Non. Tout ce qui a été validé reste dans l’historique du projet. Remplace le mot de passe ou la clé exposée par un nouveau, puis désactive le suivi du fichier.

Quelle est la différence entre .gitignore et .git/info/exclude ?

Les deux utilisent les mêmes règles de motifs. Le fichier .gitignore est partagé avec tout le monde via le dépôt, tandis que .git/info/exclude reste uniquement sur ta machine.