Si Git sur votre Mac ignore un fichier, exécutez git check-ignore -v -- 'path/to/file' depuis le dépôt dans Terminal. La sortie indique la source d'exclusion, le numéro de ligne, le motif correspondant et le chemin, ce qui vous permet de trouver la règle et de décider si vous devez la modifier. Si le fichier est déjà suivi, répétez la vérification avec --no-index.
Exécuter la vérification depuis le dépôt
Ouvrez Terminal et accédez au répertoire de premier niveau du dépôt. Vous pouvez saisir cd suivi d'un espace, faire glisser le dossier du projet depuis le Finder dans la fenêtre du Terminal pour insérer son chemin, puis appuyer sur Retour. Vérifiez que vous êtes bien dans un arbre de travail Git avec git status ; si Git signale que le répertoire n'est pas un dépôt, placez-vous d'abord dans le dossier réel du dépôt du projet.
Utilisez le chemin vers le fichier par rapport à la racine du dépôt. Par exemple, pour diagnostiquer build/cache.json, exécutez :
git check-ignore -v -- 'build/cache.json'
Les guillemets simples rendent le chemin littéral pour le shell par défaut de macOS, zsh. Ils sont particulièrement utiles lorsqu'un nom contient des espaces ou des caractères tels que * que le shell interpréterait autrement. Le -- marque la fin des options, ce qui empêche également qu'un chemin commençant par un trait d'union soit traité comme un indicateur.
Lire la sortie pour localiser la règle
Une correspondance détaillée ressemble à ceci :
.gitignore:12:build/ build/cache.json
Les champs signifient : .gitignore est le fichier source, 12 est son numéro de ligne, build/ est le motif, et build/cache.json est le chemin que vous avez interrogé. Ouvrez ce fichier source dans votre éditeur de texte préféré et inspectez la ligne signalée. La source peut également être un .gitignore imbriqué, .git/info/exclude, ou un fichier d'exclusions globales configuré pour votre compte Git. Git documente les champs de sortie détaillés et ces sources d'exclusion.
Un chemin source sous .git/info/exclude s'applique à ce dépôt mais n'est normalement pas partagé avec d'autres clones. Un fichier d'exclusions globales s'applique à vos propres dépôts. Un motif .gitignore est généralement l'endroit approprié pour une règle que le projet doit partager. Git vérifie les sources d'exclusion par ordre de priorité : les fichiers .gitignore de niveau inférieur peuvent remplacer les règles parentes, et le dernier motif correspondant au même niveau de priorité détermine le résultat. Le manuel de gitignore explique la priorité et l'utilisation prévue de chaque source.
Si Git n'affiche rien
L'absence de sortie signifie généralement qu'aucun motif d'exclusion ne correspond à ce chemin. La sortie normale de la commande liste les chemins ignorés ; utilisez -v pour voir le motif déterminant. Vérifiez que vous êtes dans le bon dépôt et que l'orthographe et la casse du chemin sont exactes.
Les fichiers suivis sont une source fréquente de confusion : par défaut, git check-ignore ne les signale pas, car les règles d'exclusion s'appliquent aux fichiers qui ne sont pas déjà suivis. Ajoutez --no-index pour demander à Git de vérifier tout de même les règles :
git check-ignore -v --no-index -- 'build/cache.json'
Cette option permet de diagnostiquer la règle ; elle ne supprime pas le suivi du fichier et ne le retire pas d'un commit. La méthode documentée par Git pour cesser de suivre un fichier est git rm --cached, suivie d'une règle d'exclusion appropriée. Cela modifie l'index, inspectez donc le statut et comprenez l'effet avant de l'exécuter. Git explique la restriction relative aux fichiers suivis et l'option --no-index.
Vérifier les négations et la portée des motifs
Une ligne correspondante commençant par ! est une négation : elle peut réintégrer un chemin après un motif d'exclusion antérieur, de sorte qu'une correspondance détaillée avec une telle ligne ne signifie pas que le fichier reste ignoré. De plus, Git ne peut pas réinclure un fichier si un répertoire parent est exclu ; le répertoire parent doit d'abord être rendu accessible via des règles correspondantes. La documentation des motifs de Git décrit la négation et cette limitation liée aux répertoires parents.
Les motifs sont interprétés par rapport au fichier .gitignore qui les contient. Un motif comportant une barre oblique est limité au niveau du répertoire de ce fichier ; un motif de nom simple peut correspondre à ce niveau et en dessous. Cela a son importance lorsqu'une règle provient d'un .gitignore imbriqué : le motif affiché peut sembler correct tout en s'appliquant à une sous-arborescence différente de celle attendue. Vérifiez l'emplacement du fichier source ainsi que le texte du motif.
Pour un seul fichier, git check-ignore -v suffit généralement pour savoir où chercher. Pour un fichier suivi, incluez --no-index ; ensuite, utilisez la source, la ligne et le motif rapportés pour déterminer si la règle doit être modifiée, restreinte ou laissée en place.