Générateur de .gitignore

Qu’est-ce qu’un générateur de .gitignore ?

Un fichier .gitignore indique à git quels chemins laisser tranquilles : résultats de compilation, dossiers de dépendances, résidus de l’éditeur, tout ce que vous ne voulez pas voir dans l’historique. Un générateur vous donne un fichier de départ raisonnable pour les technologies que vous employez, afin de ne pas réécrire node_modules de mémoire à chaque nouveau dépôt.

La moitié qui génère est la moitié facile, et seule elle ne vaut pas grand-chose : on ne vérifie pas une liste de motifs en la regardant. Cette page l’associe donc à la partie qui, elle, se vérifie : collez un chemin et elle vous dit si git l’ignorerait, et quelle ligne a pris cette décision.

C’est dans cette seconde moitié que se cachent les surprises. Un .gitignore n’est pas une liste de fichiers, c’est un ensemble de règles avec priorité, ancrage et sémantique de répertoires — et la règle que tout le monde cite est incomplète d’une manière qui finit par mordre presque tout le monde.

Comment s’en servir

1. Cochez les technologies que vous utilisez. Le fichier est composé à partir de modèles, avec un en-tête par technologie. Ceux marqués global ont leur place dans votre propre ~/.gitignore_global et non dans le dépôt : le dossier de votre éditeur vous regarde, pas le projet.
2. Modifiez le fichier librement. C’est une zone de texte ordinaire. Si c’est le vérificateur qui vous intéresse, collez-y directement un .gitignore existant.
3. Saisissez un chemin et lisez le verdict. Vous obtenez ignoré ou non, le numéro et le texte de la ligne qui a décidé, et — le cas échéant — le répertoire parent sur lequel la décision a réellement été prise.

Pourquoi !build/keep.txt ne fait rien, et quoi écrire à la place

La règle que tout le monde répète, c’est que le dernier motif correspondant l’emporte. Elle est vraie jusqu’à un certain point, et elle prédit la mauvaise réponse à la question la plus fréquente sur .gitignore. Avec build/ sur une ligne et !build/keep.txt sur la suivante, le fichier reste ignoré. Git est d’accord : interrogez-le et il désigne la ligne 1, celle du répertoire, comme celle qui a décidé.

La raison est que git ne parcourt pas une liste plate de motifs face à votre chemin. Il parcourt les répertoires du chemin de haut en bas, et dès qu’un répertoire est exclu il n’y descend plus. Aucun motif situé plus bas n’a l’occasion de réintégrer quoi que ce soit, puisque rien de ce qui s’y trouve n’est jamais regardé.

Le correctif tient en un caractère. Excluez le contenu du répertoire plutôt que le répertoire : build/* au lieu de build/. Git descend alors, la négation est atteinte, et build/keep.txt est conservé tandis que tout le reste demeure ignoré. Cet outil signale la forme cassée : il énumère toute négation qu’une règle antérieure a rendue inatteignable, de sorte que vous l’apprenez avant de valider et non après vous être demandé pourquoi le fichier n’est jamais apparu.

Le reste de la syntaxe mérite aussi d’être connu, et le vérificateur l’exerce en entier : une barre ailleurs qu’à la fin ancre le motif au répertoire du fichier lui-même, si bien que /build ne correspond qu’à la racine tandis que build correspond à n’importe quelle profondeur ; une barre finale restreint le motif aux répertoires ; une étoile s’arrête à la barre mais une double étoile la franchit ; et un point d’exclamation initial nie, sauf si vous l’échappez.

Limites honnêtes

Les modèles sont un point de départ, pas une autorité. Ils forment une sélection de l’ensemble versé au domaine public que publie github, et la date à laquelle cet instantané a été pris figure sous l’outil. Un modèle qui n’a pas suivi l’apparition d’un nouveau répertoire de compilation est incomplet, ce que vous voyez et corrigez dans la zone de texte ; c’est autre chose qu’être faux.

Cette page raisonne par ailleurs sur un seul fichier .gitignore à la fois. Un vrai dépôt peut en compter plusieurs — un par répertoire, plus .git/info/exclude, plus votre fichier global — et git les applique du moins au plus spécifique, si bien qu’une règle dans un sous-répertoire l’emporte sur une règle à la racine. Le vérificateur répond pour le fichier qui est dans la boîte, relativement à l’endroit où ce fichier se trouve.

Deux autres choses qu’un chemin seul ne peut pas vous dire. Un fichier déjà suivi le reste quoi que vous ajoutiez au .gitignore, car les règles d’exclusion s’appliquent aux fichiers non suivis ; il faut git rm --cached pour cesser de le suivre. Et l’outil raisonne sur des motifs et non sur votre disque : il traite le chemin exactement tel que vous l’écrivez — la case à cocher est là parce qu’être ou non un répertoire change la réponse pour les motifs terminés par une barre.

Enfin, les verdicts ont été vérifiés contre git lui-même et non contre une autre implémentation : un balayage généré de 252 combinaisons de motif et de chemin, exécuté dans un vrai dépôt, sans le moindre désaccord.

Pourquoi est-ce gratuit ?

Parce que cela ne coûte rien à faire tourner. La comparaison a lieu dans votre navigateur ; aucun fichier n’est envoyé, aucun serveur ne voit vos chemins, et il n’y a pas de compte.

Les modèles sont dans le domaine public, les règles de motifs viennent du comportement documenté de git lui-même, et le test qui compare cette implémentation à git est conservé à côté du code.