Aller au contenu

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

icône Git Hook

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 :


Fonctionnement#

icône globe matiere

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;

Modifications automatiques

Certains hooks peuvent directement modifier les fichiers. Ces modifications ne sont pas ajoutées automatiquement à l'index et il faut donc que l'auteur du commit les ajoute manuellement (git add).


Utilisation#

logo pre-commit

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

Astuce dont il ne faut pas abuser

Pour committer en outre-passant les git hooks ajouter l'option --no-verify à la commande git commit.

Exécution automatisée sur la CI#

icône GitHub Actions

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 :

PR GitHub - Check pre-commit

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

Exemple de résultat sur pre-commit ci


  1. étape où un contributeur propose d'intégrer ses modifications dans le socle principal du projet. Voir la documentation de GitHub

Commentaires


Ce contenu est sous licence Creative Commons BY-NC-SA 4.0 International Pictogramme Creative Commons Pictogramme Creative Commons BY Pictogramme Creative Commons NC Pictogramme Creative Commons SA