Git Hooks : garde-fous de l'hétérogénéité de Geotribu#

Afin de garantir un minimum de qualité et surtout de cohérence entre les différentes contributions (appelées commits dans un contexte Git), une série de git hooks est configurée sur le dépôt du site Geotribu.

Ils sont exécutés lors de chaque contribution (commit) :

• soit par l'auteur au moment du commit
• soit par l'intégration continue (CI) sur GitHub

Définition#

Un git hook est l'une des possibilités offertes par Git pour personnaliser son utilisation. Concrètement c'est un script configuré pour se lancer automatiquement lors d'une étape du workflow de travail avec Git (typiquement au moment d'un commit), précisément entre le déclenchement de cette étape et son achèvement. On dit que cela fait faire un crochet (hook en anglais ).

Ressources externes sur le sujet :

• les crochets Git dans le manuel officiel
• Git Hooks ou la revanche du crochet Git
• Git Hooks pour s’assurer de la qualité du code produit

Fonctionnement#

Sur Geotribu, les crochets sont configurés pour intervenir au moment du commit, c'est-à-dire entre le moment ou la commande git commit est lancée et l'inscription du commit (= modification) dans l'historique. On parle donc de pre-commit. Cela permet d'effectuer les éventuelles corrections avant que les erreurs ne soient enregistrées et d'éviter ainsi un commit correctif.

Ils sont d'abord pensés pour s'utiliser côté client (lors de l'édition par un/e contributeur/ice) mais ils sont également exécutés automatiquement pendant la CI (voir plus bas).

Sans les crochets git (hooks) activés#

Voici le processus de commit normal :

flowchart TD
    A[Modification du fichier mon_article.md] --> B
    B(git add) --> |Référence les changements| C
    C(git commit) --> |Enregistre les changements indexés| D
    D[Modification enregistrée\ndans l'historique Git]

Avec les crochets git (hooks) activés#

Lorsque que les hooks sont activés, ils bloquent le commit jusqu'à tant que le contenu passe les vérifications :

flowchart TD
    A[Modification du fichier mon_article.md] --> B
    B(git add) --> |Référence les changements| C
    C(git commit) --> |Lance les crochets| D
    D(Scripts de vérification) --> |Tout est OK| E[Modification enregistrée\ndans l'historique Git]
    D --> |Problème détecté\nSANS modification| B
    D --> |Problème détecté\nAVEC modifications automatiques| A

    linkStyle 3 color:green;
    linkStyle 4 stroke:#FF0000,stroke-width:4px,color:red;
    linkStyle 5 stroke:#EE82EE,stroke-width:4px,color:purple;

Utilisation#

Pour faciliter la maintenance, nous utilisons l'outil pre-commit qui est une sorte de gestionnaire de git hooks. Il est développé en Python mais peut exécuter des hooks dans de nombreux autres langages (NodeJS, shell, etc.).

Crochets Git configurés sur Geotribu#

Les git hooks sont listés dans le fichier de configuration de pre-commit situé dans le dépôt du site : .pre-commit-config.yaml.

Voici une liste non exhaustive :

• vérificateur de syntaxe Markdown (voir la page dédiée)
• correction automatique de l'encodage des fichiers, notamment les fins de ligne
• vérifie qu'il n'y a pas de conflit sur le nom des fichiers, y compris en gérant la casse des différents systèmes de fichiers
• empêche l'ajout de fichiers volumineux pour éviter que l'historique Git ne devienne obèse et ingérable
• supprime les espaces inutiles en fin de ligne
• vérifie que la syntaxe des fichiers YAML est correcte (utilisée pour Mkdocs, les GitHub Actions...)

Edition en local#

Pour installer les git hooks, il faut donc disposer d'un interpréteur Python puis :

# installer pre-commit
pip install -U pre-commit
# installer les git hooks
pre-commit install

Exécution automatisée sur la CI#

Etant donné que la très grande majorité des contributeur/ices n'utilisent pas l'édition locale ou n'installent pas les git hooks, ces derniers sont automatiquement exécutés dans l'intégration continue, via le service pre-commit.ci (du même auteur que l'outil).

Ainsi, pour chaque commit publié sur le dépôt du site, le service exécute les git crochets sur l'ensemble du contenu du site et non pas seulement sur ce qui a été modifié dans le commit ou dans la Pull Request (ce qui équivaut à un pre-commit run --all).
Dans l'interface de GitHub, cela se manifeste par un check sur le commit, visible en bas d'une Pull Request :

Au clic sur Details, on accède au détail de l'exécution où l'on peut ce qui a été modifié :

Commentaires