Les fichiers magiques de Git

(nesbitt.io)

45 points par GN⁺ 2026-02-24 | Aucun commentaire pour le moment. | Partager sur WhatsApp

Git contrôle son comportement via certains fichiers spécifiques du dépôt, qui ne sont pas des réglages internes à .git/, mais des fichiers versionnés qui voyagent avec le code
.gitignore, .gitattributes, .lfsconfig, .gitmodules, .mailmap assurent respectivement l’exclusion du suivi de fichiers, la définition d’attributs, la configuration de LFS, la gestion des sous-modules et l’unification des auteurs
.git-blame-ignore-revs et .gitmessage permettent d’ignorer des commits de formatage et de fournir un modèle de message de commit, ce qui améliore la qualité de la collaboration
GitHub, GitLab, Gitea, etc. étendent leurs fonctionnalités via des dossiers de configuration propres à chaque forge comme .github/, .gitlab/, .gitea/, notamment pour la CI/CD ou l’assignation de reviewers
Cette structure s’applique aussi au-delà de Git, dans EditorConfig, Docker ou les outils de gestion de versions de langage, formant un écosystème de configuration automatique fondé sur les dotfiles

Principaux fichiers magiques de Git

Git reconnaît plusieurs fichiers spéciaux comme .gitignore, .gitattributes, .lfsconfig, .gitmodules et .mailmap pour piloter le comportement du dépôt
- Ces fichiers ne sont pas des réglages internes à .git/, mais des éléments de configuration versionnés et partagés, garantissant un comportement cohérent en équipe

.gitignore

Définit les motifs de fichiers que Git ne doit pas suivre
- Prend en charge les jokers (*.log), les répertoires (dist/) et les exceptions (!important.log)
- L’ordre d’application est .gitignore, .git/info/exclude, puis la configuration globale (~/.config/git/ignore)
Les fichiers déjà suivis continuent de l’être après l’ajout à .gitignore, et peuvent être retirés avec git rm --cached
GitHub, GitLab et Gitea permettent tout de même de commit des fichiers correspondant à des motifs ignorés, sans avertissement
GitHub fournit des modèles de .gitignore par langage dans son dépôt officiel

.gitattributes

Contrôle, fichier par fichier, les filtres, diff, merge, fins de ligne et détection de langage
- Ex. : *.psd filter=lfs, *.png binary, *.sh text eol=lf
text normalise les fins de ligne, binary désactive diff/merge, et merge=ours conserve la version locale en cas de conflit
GitHub Linguist lit .gitattributes pour exclure des statistiques de langage, replier du code généré ou ignorer de la documentation
Git reconnaît aussi les .gitattributes propres à chaque répertoire ainsi que .git/info/attributes

.lfsconfig

Permet de partager la configuration Git LFS avec le dépôt
- On peut y définir l’URL du serveur LFS, le nombre de tentatives de transfert, etc.
- Exemple :
```
[lfs]
    url = https://lfs.example.com/repo
[lfs "transfer"]
    maxretries = 3
```
.gitattributes désigne les fichiers à traiter via LFS, tandis que .lfsconfig gère les détails comme l’emplacement du serveur
Pour migrer des fichiers déjà commités vers LFS, il faut utiliser la commande git lfs migrate

.gitmodules

Stocke les informations de configuration des sous-modules
- Contient le chemin, l’URL et la branche de chaque module
- Exemple :
```
[submodule "vendor/lib"]
    path = vendor/lib
    url = https://github.com/example/lib.git
    branch = main
```
Créé lors de git submodule add, consulté lors de git submodule update
Lors d’un git clone, les sous-modules ne sont pas récupérés automatiquement ; l’option --recurse-submodules est nécessaire
Parmi les inconvénients : impossibilité de suivre une plage de versions et création de répertoires .git imbriqués

.mailmap

Sert à unifier les noms et adresses e-mail des auteurs
- Exemple :
```
Jane Developer <[email protected]> <[email protected]>
```
git log, git shortlog, git blame, etc. affichent alors le nom unifié
Le graphe des contributeurs de GitHub ne tient pas compte de mailmap
L’emplacement peut être défini via .mailmap ou le réglage mailmap.file

.git-blame-ignore-revs

Définit la liste des commits à ignorer dans git blame
- Permet d’exclure des changements sans valeur sémantique, comme l’exécution d’un formateur ou l’application d’un linter
- Exemple :
```
# Ran prettier on entire codebase
a1b2c3d4e5f6g7h8i9j0...
```
S’active avec git config blame.ignoreRevsFile .git-blame-ignore-revs
GitHub, GitLab (15.4+) et Gitea le reconnaissent automatiquement
En l’absence du fichier, une erreur peut se produire ; il est donc recommandé de conserver un fichier vide

.gitmessage

Définit un modèle de message de commit

Exemple :

# <type>: <subject>
#
# Types: feat, fix, docs, style, refactor, test, chore

Nécessite la configuration git config commit.template .gitmessage
Un réglage manuel est nécessaire après le clone, bien que certaines équipes l’automatisent avec husky, par exemple
Comme alternatives, on peut utiliser les hooks commit-msg ou prepare-commit-msg

Dossiers d’extension propres aux forges

GitHub, GitLab, Gitea, Forgejo, Bitbucket, etc. utilisent des dossiers de configuration spécifiques
- .github/, .gitlab/, .gitea/, .forgejo/, .bitbucket/
Ils peuvent contenir des workflows CI/CD, des modèles d’issue ou de PR, ainsi que des fichiers CODEOWNERS
Forgejo applique un fallback dans l’ordre .forgejo/ → .gitea/ → .github/, et Gitea dans l’ordre .gitea/ → .github/
SourceHut utilise .build.yml ou .builds/*.yml

Autres fichiers conventionnels

.gitkeep : utilisé comme fichier factice pour conserver un répertoire, puisque Git ne suit pas les répertoires vides
.gitconfig : permet de fournir un exemple de configuration Git propre au projet, mais n’est pas chargé automatiquement
.gitsigners : gère la liste des clés de signature GPG/SSH, pouvant être référencée avec gpg.ssh.allowedSignersFile

.gitreview : fichier de configuration pour le serveur de revue de code Gerrit