Les fichiers magiques de Git

(nesbitt.io)

45 points par GN⁺ 2026-02-24 | 2 commentaires | 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

Exemple :

[gerrit]
host=review.opendev.org
port=29418
project=openstack/nova.git
defaultbranch=master

.gitlint : définit les règles de lint des messages de commit
- Exemple :
```
[general]
ignore=body-is-missing
[title-max-length]
line-length=72
```
.jj/ : répertoire d’état de Jujutsu, un VCS compatible Git, qui peut coexister avec .git/

L’écosystème des dotfiles au-delà de Git

.editorconfig : maintient un style de code cohérent entre éditeurs
- Définit l’indentation, les fins de ligne, l’encodage ou encore la suppression des espaces superflus
- Pris en charge par les principaux éditeurs comme VS Code, Vim et Emacs
.ruby-version, .node-version, .python-version : lus par des outils de gestion de versions de langage (rbenv, nodenv, pyenv, etc.) pour basculer automatiquement
.tool-versions : fichier de gestion multilangage des versions pour asdf
.dockerignore : liste les fichiers à exclure lors du build Docker
- Utilise la même syntaxe de motifs que .gitignore, ce qui améliore la vitesse de build et évite d’inclure des informations sensibles

Points à prendre en compte lors du développement d’outils intégrés à Git

Un outil qui manipule un dépôt Git doit impérativement reconnaître les fichiers suivants
- .gitignore : appliquer les motifs d’exclusion lors de l’exploration des fichiers
- .gitattributes : distinguer les fichiers binaires et générés
- .mailmap : afficher des informations auteurs unifiées
- .gitmodules : gérer les sous-modules
Le format des fichiers de configuration Git suit la structure [section "subsection"] key = value et peut être lu ou écrit avec la commande git config
La plupart des bibliothèques Git disponibles dans les différents langages savent parser ce format

2 commentaires

wedding 2026-02-24

Je ne connaissais pas gitmessage, mais je vais l’essayer.

GN⁺ 2026-02-24

Commentaires sur Hacker News

Il était dit que GitHub, GitLab et Gitea respectent tous .gitignore et n’affichent donc pas les fichiers ignorés dans l’interface web, mais cela semble être une explication erronée
En réalité, ils ne s’affichent pas parce qu’ils ne font pas partie du dépôt. Si un fichier a déjà été commit, il devrait au contraire être visible
- Ce n’est pas le cas. Si on ajoute plus tard un fichier déjà poussé à .gitignore, il reste visible dans l’UI. Ce fichier fait toujours partie du repo
  À l’inverse, on peut aussi forcer le commit d’un fichier ignoré dès le départ, mais cela demande un petit truc
- Oui, le commentaire d’origine est faux. .gitignore ne fait que décider si les fichiers non suivis doivent être masqués ou non. On peut commit des fichiers ignorés si on le souhaite
- Je me dis qu’un réglage du style showinwebui=(true|false) serait bien 😄
- J’ai eu l’impression qu’aucun humain n’avait pu écrire une telle erreur, donc j’ai arrêté de lire à ce moment-là
Je veux mettre en avant .git/info/exclude. C’est un gitignore purement local, donc un réglage rien que pour moi
Par exemple, c’est utile quand on crée des fichiers temporaires pendant l’analyse d’un bug et qu’on veut les conserver en changeant de branche
J’utilise un alias shell comme celui-ci
```
git-ignore-local () {
  echo "$1" >> .git/info/exclude
}
```
Cela permet ensuite d’ajouter simplement un fichier avec git-ignore-local myfile.ext
- J’en ai fait une version un peu plus magique, qui marche même si on n’est pas dans le répertoire racine
  Sur MacOS, il suffit d’adapter la partie readlink
```
git-ignore-local () {
  root=$(git rev-parse --show-toplevel)
  path=$(readlink -f "$1")
  relpath=$(relpath -m --relative-to="$root" "$path")
  echo "$relpath" >> "${root}.git/info/exclude"
}
```
  Si on enregistre cette fonction dans le PATH sous le nom git-ignore-local, on peut l’utiliser comme git ignore-local
- .git/info/exclude est aussi mentionné au début de l’explication de .gitignore
- Je découvre cette fonction. De petits fichiers temporaires compliquaient mes PR dans mon projet, et ça devrait régler le problème
En ajoutant /test export-ignore dans .gitattributes, on peut exclure les fichiers de test lors du déploiement en production
Quand un outil de déploiement comme Capistrano utilise git export, cela s’applique automatiquement et les fichiers de test ne montent pas sur le serveur
Cela n’a aucun effet pendant le développement tout en économisant de l’espace disque
- C’est une bonne fonctionnalité, mais la plupart des gens semblent à peine connaître git archive lui-même
  Je l’ai très rarement vu utilisé, même dans les outils CI de base. Capistrano a été pour moi le premier exemple d’usage concret
  À noter que l’option export-subst permet aussi d’insérer directement dans un fichier des informations similaires à git describe
En utilisant jj, je voulais exclure complètement le dossier .jj du repo et de toutes les opérations Git
Y compris pour éviter qu’il soit supprimé par git clean -xdf. Pour l’instant, je m’en sors avec un alias temporaire git clean -e .jj
- Il suffit d’utiliser .git/info/exclude
Le graphe des contributeurs de GitHub ne prend pas en charge .mailmap
La discussion associée est ici : GitHub Community Discussion
Je pense que le réglage package-lock.json merge=ours est risqué
Parce que le sens de ours/theirs n’est pas clair lors d’un merge ou d’un rebase
Ce type de réglage n’a vraiment de sens que pour des outils de fusion automatisée, comme la branche git-annex
Références : explication du sens de ours/theirs, structure interne de git-annex
.git-blame-ignore-revs est une bonne fonctionnalité, mais elle devrait plutôt aller dans la section « autres conventions »
Si ce fichier n’est pas configuré côté client Git, alors git blame échoue dans les dépôts qui ne l’ont pas
- Depuis git 2.52, on peut utiliser l’option (:optional) pour éviter une erreur quand le fichier n’existe pas
  Explication ici : réponse Stack Overflow
Dans l’ensemble, je trouve que c’est une liste bien organisée
C’est juste dommage que tous les outils ne prennent pas en charge .mailmap. Par exemple, dans IntelliJ, cela reste encore au stade de bug / demande de fonctionnalité
Et .git-blame-ignore-revs n’est qu’une simple convention : il faut la configurer soi-même pour que cela fonctionne
Un peu hors sujet, mais j’ai découvert récemment que VS Code reconnaît aussi les fichiers .ignore
Je pensais que seul .gitignore s’appliquait, mais en modifiant la configuration ripgrep dans .ignore, les résultats de recherche ont changé. Au final, c’était un comportement logique
L’auteur a aussi publié un billet de suivi sur les dossiers de dépôt spécifiques aux forge (une sorte de « dossiers magiques »)
Lien : article sur nesbitt.io