.gitattributes

Ce que fait .gitattributes

Un fichier .gitattributes indique à Git comment traiter des fichiers spécifiques en fonction de leur chemin. Là où .gitignore décide si Git suit un fichier, .gitattributes décide comment Git gère les fichiers qu'il suit — comment normaliser les fins de ligne, comment les comparer, comment les fusionner, et quoi faire au moment de l'export. Il réside dans votre dépôt et est versionné, de sorte que chaque collaborateur bénéficie du même comportement, quelle que soit sa configuration Git personnelle.

Cette page couvre le format du fichier, les attributs les plus courants (normalisation des fins de ligne, marquage des binaires, pilotes de diff/fusion personnalisés et export-ignore), où Git cherche le fichier, et comment les règles conflictuelles sont résolues.

Format du fichier

Chaque ligne associe un motif de fichier à un ou plusieurs attributs :

# pattern        attributes
*.txt            text
*.png            binary
*.sh             text eol=lf

Les motifs suivent les mêmes règles glob que .gitignore : * correspond à n'importe quoi sauf /, ** correspond à travers les répertoires, un / en tête ancre au répertoire du fichier .gitattributes, et les lignes commençant par # sont des commentaires. Chaque attribut après le motif prend l'une des quatre formes suivantes :

• Défini — text active l'attribut.
• Non défini — -text le désactive (le tiret initial).
• Valeur — eol=lf fixe une valeur spécifique.
• Non spécifié — !text efface tout paramètre antérieur, laissant Git utiliser sa valeur par défaut.

Où Git le cherche

La plupart des projets conservent un seul .gitattributes à la racine du dépôt. Mais Git vérifie plusieurs emplacements, et une règle dans un répertoire plus profond remplace celle d'un niveau supérieur :

• Un .gitattributes dans n'importe quel répertoire s'applique aux fichiers de ce répertoire et des sous-répertoires.
• $GIT_DIR/info/attributes contient des règles qui ne sont pas versionnées (locales à votre clone).
• core.attributesFile (souvent ~/.config/git/attributes) définit les valeurs par défaut par utilisateur.

Lorsque deux règles peuvent correspondre au même fichier, le chemin le plus spécifique l'emporte, et au sein d'un même fichier la dernière ligne correspondante l'emporte. Vous pouvez inspecter le résultat pour n'importe quel chemin avec git check-attr :

git check-attr -a README.md
# README.md: text: auto

Normalisation des fins de ligne

L'utilisation la plus courante de .gitattributes est de mettre fin au problème "chaque ligne a changé" qui survient lorsque des développeurs Windows et Unix partagent un dépôt. Marquer les fichiers comme text permet à Git de normaliser les fins de ligne en LF dans le dépôt et de les convertir à la récupération :

* text=auto
*.sh text eol=lf
*.bat text eol=crlf

text=auto laisse Git décider quels fichiers sont du texte et les stocke avec LF dans le dépôt ; les paramètres eol explicites forcent ensuite une terminaison spécifique à la récupération pour les fichiers qui en ont besoin (les scripts shell doivent rester en LF, les fichiers batch Windows doivent rester en CRLF). Les règles étant versionnées, c'est plus fiable que de s'appuyer sur le paramètre core.autocrlf de chaque développeur, qui diffère d'une machine à l'autre.

Si vous ajoutez * text=auto à un dépôt existant, les fichiers déjà validés avec CRLF ne seront pas renormalisés automatiquement. Effectuez un nettoyage ponctuel pour que le prochain commit les corrige :

git add --renormalize .
git commit -m "Normalize line endings"

Marquage des fichiers comme binaires

Indiquer à Git qu'un fichier est binaire l'empêche d'essayer d'afficher un diff textuel ou de le fusionner ligne par ligne :

*.pdf binary
*.png binary

L'attribut binary est une macro intégrée qui se développe en -text -diff, ce qui désactive la conversion des fins de ligne et le diff textuel. Cela empêche Git de corrompre un fichier par des réécritures de fins de ligne et évite que git diff déverse de l'octet illisible dans le terminal.

Pour les gros binaires tels que les vidéos, les jeux de données ou les fichiers de conception, les marquer comme binaires ne suffit pas — ils gonflent quand même l'historique du dépôt. Stockez-les avec Git LFS à la place, que .gitattributes sert également à configurer.

Comportement de diff et de fusion personnalisés

.gitattributes peut acheminer certains fichiers vers des pilotes de diff ou de fusion personnalisés, mais un pilote personnalisé doit être défini dans votre configuration Git d'abord — l'attribut y fait seulement référence par son nom.

Un cas courant est un fichier de verrouillage généré : lors d'un conflit de fusion, vous souhaitez conserver intégralement la version de votre branche plutôt que de fusionner ligne par ligne. Enregistrez un pilote ours une fois, puis pointez le chemin vers lui :

git config merge.ours.driver true

# .gitattributes
package-lock.json merge=ours

Définir driver à true signifie "la fusion réussit toujours et le résultat est la version de la branche courante." (Cet attribut merge=ours par fichier est indépendant de la stratégie de fusion -s ours, qui s'applique à une fusion entière.)

Un pilote de diff personnalisé fonctionne de la même manière et est utile pour les formats non textuels. Git embarque également des pilotes de diff intégrés qui produisent des en-têtes de section significatifs pour les langages courants, de sorte qu'un diff montre quelle fonction a changé :

*.c diff=cpp
*.py diff=python

Consultez git diff pour voir comment ces pilotes façonnent la sortie.

Export-ignore

Lorsque quelqu'un télécharge une archive de version via git archive, vous souhaitez souvent exclure les fichiers de développement. L'attribut export-ignore fait exactement cela :

/tests       export-ignore
/.github     export-ignore
.gitattributes export-ignore

Cela exclut les suites de tests, la configuration CI et les fichiers d'éditeur du tarball produit par git archive, afin que les utilisateurs ne téléchargent que ce dont ils ont besoin. Un attribut connexe, export-subst, développe des espaces réservés comme $Format:%H$ dans les fichiers exportés afin qu'une archive puisse enregistrer le commit à partir duquel elle a été construite.

Attributs courants

Quand l'utiliser

Utilisez .gitattributes chaque fois que le comportement de Git par fichier doit être identique pour tous les membres de l'équipe plutôt que laissé aux paramètres locaux. Les avantages courants sont la normalisation des fins de ligne sur une équipe mixte Windows/Unix, la suppression des diffs inutiles sur les binaires, et l'allègement des archives de version. Les avantages avancés — pilotes de fusion/diff personnalisés et Git LFS — résolvent des problèmes spécifiques lorsqu'un projet les rencontre. Commencez par * text=auto et ajoutez des règles à mesure que des problèmes concrets apparaissent.

Pratique