Husky : dépannage
Procédure de diagnostic
Section intitulée « Procédure de diagnostic »git config core.hooksPath # doit afficher .husky/_ (Husky 9)ls -la .husky .husky/_cat package.json | grep -A2 '"prepare"'cat .husky/pre-commitsh -x .husky/pre-commit # exécute le hook à la main, avec traceGIT_TRACE=1 git commit -m "chore: essai" --allow-emptyExécuter le hook à la main (sh .husky/pre-commit) reproduit presque toutes les erreurs hors de Git.
Les hooks ne se lancent pas
Section intitulée « Les hooks ne se lancent pas »| Cause | Vérification et solution |
|---|---|
core.hooksPath non défini |
git config core.hooksPath vide : npx husky ou npm install (script prepare) |
| Dépôt cloné sans installation | npm install non exécuté |
--no-verify ou HUSKY=0 |
Variable d’environnement dans le profil du shell ou l’outil |
prepare absent de package.json |
Ajouter "prepare": "husky" |
npm install --ignore-scripts |
Scripts désactivés : exécuter npx husky |
Autre outil qui définit core.hooksPath |
Un seul outil de hooks à la fois |
| Hook mal nommé | Nom exact : pre-commit, commit-msg, pre-push… (sans extension) |
Dépôt avec .git dans un dossier parent |
husky lancé hors de la racine : cd .. && husky sous-dossier/.husky |
Erreurs d’exécution
Section intitulée « Erreurs d’exécution »| Message | Cause et solution |
|---|---|
.husky/pre-commit: Permission denied |
chmod +x .husky/pre-commit ; Husky 9 les rend exécutables à l’installation |
command not found: npx / node / npm |
PATH sans Node.js (client graphique, nvm) : voir plus bas |
husky - pre-commit script failed (code 1) |
La commande du hook a échoué : lire la sortie juste au-dessus |
.husky/_/husky.sh: No such file |
Anciennes lignes . "$(dirname "$0")/_/husky.sh" : les retirer |
husky - DEPRECATED |
Hook écrit pour Husky 4 à 8 : supprimer les deux premières lignes (#!/usr/bin/env sh et la ligne husky.sh) |
env: 'sh\r': No such file or directory |
Fins de ligne CRLF : convertir en LF, .gitattributes avec * text=auto eol=lf |
fatal: cannot exec '.husky/_/pre-commit' |
Installation incomplète : npx husky |
lint-staged: command not found |
Dépendance non installée, ou appeler npx lint-staged |
Node.js introuvable dans un client Git graphique
Section intitulée « Node.js introuvable dans un client Git graphique »Les éditeurs et clients Git graphiques lancent les hooks sans charger ~/.bashrc : Node.js installé avec nvm est introuvable. Créer ~/.config/husky/init.sh (exécuté avant chaque hook) :
export NVM_DIR="$HOME/.nvm"[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"Avec un Node.js installé par apt, snap ou NodeSource, le chemin est dans le PATH système : pas de réglage (voir Node.js : installation).
| Symptôme | Piste |
|---|---|
pre-commit de plusieurs dizaines de secondes |
Passer à lint-staged (fichiers indexés seulement), déplacer les tests dans pre-push |
Premier commit lent (npx) |
npx télécharge un paquet absent : l’installer en devDependency |
| Analyse de tout le projet | Commande sans lint-staged : lui confier le filtrage |
| Démarrage de Node.js lent sur disque réseau | Exécuter localement |
time sh .husky/pre-commitConflits et particularités
Section intitulée « Conflits et particularités »| Situation | Solution |
|---|---|
Dépôt avec pre-commit (outil Python) ou autre gestionnaire |
Choisir un seul outil, git config --unset core.hooksPath pour l’abandonner |
Hooks personnalisés dans .git/hooks/ |
Ignorés quand core.hooksPath est défini : les déplacer dans .husky/ |
| Worktrees Git | core.hooksPath partagé : fonctionne ; vérifier le chemin relatif |
| Commits automatiques d’un outil (release) | HUSKY=0 pour cet outil |
| Image Docker sans Git | "prepare": "husky || true" |
Migrer depuis Husky 4 à 8
Section intitulée « Migrer depuis Husky 4 à 8 »Husky 9 simplifie : plus de fichier husky.sh ni de configuration dans package.json ("husky": { "hooks": … } de la version 4).
- Mettre à jour :
npm install -D husky@latest. - Remplacer le script
prepare:"prepare": "husky"(ancien :"husky install"). - Dans chaque hook de
.husky/, supprimer les lignes :
#!/usr/bin/env sh. "$(dirname -- "$0")/_/husky.sh"- Exécuter
npm installpour réinstaller. - Pour une configuration de la version 4, recréer les hooks avec
npx husky initet déplacer les commandes.
Désactiver et réactiver
Section intitulée « Désactiver et réactiver »HUSKY=0 git commit -m "wip" # une commandegit config core.hooksPath .husky/_ # réactivernpx husky # réinstaller proprementQuand abandonner Husky
Section intitulée « Quand abandonner Husky »Si les hooks gênent plus qu’ils n’aident (équipe sans Node.js, hooks trop lents, contournements systématiques) : les remplacer par la vérification en intégration continue et, au besoin, des hooks Git natifs simples (Alternative : hooks Git natifs).
Ubuntu 24.04 et 26.04 : différences à connaître
Section intitulée « Ubuntu 24.04 et 26.04 : différences à connaître »/bin/sh est dash : un hook qui utilise des fonctions de bash ([[ ]], tableaux) échoue avec une erreur de syntaxe ; ajouter #!/usr/bin/env bash en tête du hook. Sur 26.04, sudo est fourni par sudo-rs, sans effet sur les hooks (qui ne devraient pas utiliser sudo).