Hooks Git

Les hooks Git (crochets) sont des scripts qui s'exécutent automatiquement à des moments précis du cycle de vie de Git (commit, push, merge, etc.). Ils permettent d'automatiser des tâches, d'imposer des standards de qualité ou de renforcer la sécurité.

🚀 Fonctionnement général

Un hook Git est un fichier exécutable situé dans le dossier caché .git/hooks/ de votre dépôt local.

• Déclenchement : Git surveille certains événements. Lorsqu'un événement survient, Git cherche un script correspondant dans le dossier hooks.
• Code de sortie :
  • Si le script retourne 0, l'action Git continue.
  • Si le script retourne une valeur différente de 0, l'action Git est interrompue.

📍 Portée et limites

Hooks Locaux vs Serveur

⚠️ Attention : Les hooks situés dans .git/hooks/ ne sont pas versionnés. Ils ne sont pas envoyés sur le dépôt distant lors d'un git push. Chaque développeur doit les configurer sur sa machine.

🛠️ Configuration

Par défaut, Git remplit le dossier .git/hooks/ avec des exemples (fichiers .sample).

Activer un hook

1. Allez dans .git/hooks/.
2. Renommez le fichier en supprimant l'extension .sample (ex: pre-commit.sample → pre-commit).
3. Assurez-vous que le fichier est exécutable :

   chmod +x .git/hooks/pre-commit
   

Langages supportés

Un hook peut être écrit dans n'importe quel langage supporté par votre machine, tant que le fichier commence par un "Shebang" (#!) valide :

• Bash : #!/bin/bash
• PHP : #!/usr/bin/php
• Python : #!/usr/bin/python

📋 Hooks les plus utiles

pre-commit

Exécuté avant la création du commit. Idéal pour :

• Vérifier la syntaxe (linting).
• Empêcher de commiter des secrets (mots de passe, clés API).
• Lancer les tests unitaires rapides.

prepare-commit-msg

Exécuté juste avant l'ouverture de l'éditeur de message de commit. Utile pour :

• Insérer automatiquement le numéro de ticket (ex: CDX-123).

commit-msg

Exécuté après la rédaction du message. Sert à :

• Valider le format du message (ex: vérifier le préfixe feat:, fix:, docs:).
• Imposer les Conventional Commits (voir git-conventions.md).

post-merge

Exécuté après un git pull ou git merge réussi. Utile pour :

• Lancer un composer install si composer.lock a changé.
• Vider le cache de l'application.

pre-push

Exécuté avant l'envoi vers le distant (échec = push bloqué). Idéal pour rejouer en local les vérifs de la CI (échec rapide avant de pousser).

Codexia fournit scripts/hooks/pre-push (qui lance scripts/check-doc-links.sh — liens Markdown internes). Activation une fois :

git config core.hooksPath scripts/hooks

💡 Partager les hooks dans l'équipe

Puisque .git/hooks/ n'est pas versionné, voici les stratégies courantes dans Codexia :

1. Dossier de templates : Créer un dossier scripts/hooks/ à la racine du projet (versionné) et demander aux développeurs de créer un lien symbolique :

   ln -s ../../scripts/hooks/pre-commit .git/hooks/pre-commit
   

2. Configuration Git (Git 2.9+) : Rediriger le dossier des hooks vers un dossier versionné :

   git config core.hooksPath scripts/hooks