Husky : installation

Husky installe des hooks Git à l’échelle du projet : des commandes exécutées automatiquement avant un commit, un push ou à d’autres moments (formatage, analyse, tests, vérification du message). Les hooks étant versionnés dans le dépôt, toute l’équipe les partage. Les exemples utilisent des noms génériques.

Rappel : les hooks Git

Git exécute des scripts placés dans un dossier de hooks à certains événements :

Hook	Quand	Usage typique
pre-commit	Avant la création du commit	Formatage et analyse des fichiers modifiés
commit-msg	Après la saisie du message	Vérifier le format du message
pre-push	Avant l’envoi vers le dépôt distant	Lancer les tests
post-merge, post-checkout	Après une fusion, un changement de branche	Réinstaller les dépendances si le fichier de verrouillage a changé

Par défaut, ces scripts vivent dans .git/hooks/, non versionné : Husky les remplace par un dossier .husky/ versionné, en configurant core.hooksPath.

Installer

npm install -D husky
npx husky init

husky init fait trois choses :

1. ajoute le script "prepare": "husky" dans package.json ;
2. crée le dossier .husky/ avec un hook pre-commit d’exemple ;
3. configure Git pour utiliser ce dossier (core.hooksPath).

{
  "scripts": {
    "prepare": "husky"
  },
  "devDependencies": {
    "husky": "^9.0.0"
  }
}

Le script prepare s’exécute à chaque npm install : tout développeur qui installe les dépendances active les hooks automatiquement.

git config core.hooksPath          # affiche .husky/_
ls .husky

Le premier hook

.husky/pre-commit (un simple script shell, sans en-tête ni husky.sh depuis la version 9) :

npm test

Tester :

git add .
git commit -m "test: vérifier le hook"        # les tests se lancent avant le commit

Si la commande du hook échoue (code de sortie non nul), le commit est refusé.

Écrire un hook

.husky/pre-commit

npx lint-staged

Règle	Détail
Un fichier par hook	Nom exact du hook (pre-commit, commit-msg, pre-push…)
Un script shell	Commandes ordinaires, set -e implicite pour la première erreur
Code de sortie	0 : continuer ; autre valeur : refuser l’opération
Rapidité	Un pre-commit doit durer quelques secondes au plus

Créer un hook :

echo "npx lint-staged" > .husky/pre-commit
echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg

Voir Hooks et lint-staged et Messages de commit avec commitlint.

Dans le dépôt

monprojet/
├── .husky/
│   ├── pre-commit
│   ├── commit-msg
│   └── pre-push
├── package.json
└── ...

Versionner .husky/ (les fichiers de hook), pas le sous-dossier généré .husky/_ (Husky y ajoute son propre .gitignore). Commiter :

git add .husky package.json
git commit -m "chore: ajouter husky"

Désactiver ponctuellement

git commit --no-verify -m "wip"           # ignore pre-commit et commit-msg
git push --no-verify                      # ignore pre-push
HUSKY=0 git commit -m "wip"               # désactive Husky pour cette commande

À réserver à un cas exceptionnel (commit de sauvegarde sur une branche personnelle) : contourner les hooks revient à contourner les contrôles qualité.

Avec un gestionnaire de paquets différent

Gestionnaire	Installation
npm	npm install -D husky && npx husky init
pnpm	pnpm add -D husky && pnpm exec husky init
Yarn (v1 et suivantes)	yarn add -D husky && yarn husky init

Dans les hooks, appeler les outils par le gestionnaire du projet : pnpm exec lint-staged, pnpm test. Voir Node.js : pnpm et Yarn.

Husky ou hooks natifs ?

Husky simplifie l’installation pour les projets Node.js. Sans Node.js, ou pour un contrôle total, les hooks Git natifs avec core.hooksPath suffisent : voir Alternative : hooks Git natifs.

Désinstaller

npm uninstall husky
git config --unset core.hooksPath
rm -rf .husky

Retirer aussi le script prepare de package.json.

Dépannage

Symptôme	Piste
Les hooks ne se lancent pas	git config core.hooksPath doit afficher .husky/_ : relancer npm install (script prepare), ou npx husky
husky: command not found	Dépendances non installées (npm install)
.husky/pre-commit: Permission denied	Hook non exécutable : chmod +x .husky/pre-commit
husky - DEPRECATED à chaque commit	Hooks écrits pour Husky 4 à 8 (. "$(dirname "$0")/_/husky.sh") : supprimer ces lignes
Le commit passe sans lancer les contrôles	--no-verify, HUSKY=0, ou core.hooksPath écrasé
Hooks inactifs dans un nouveau clone	npm install non exécuté (script prepare)

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune propre à Ubuntu : Husky s’exécute avec Node.js et le Git du système. Les hooks sont des scripts exécutés par le shell sh : écrire des commandes compatibles avec dash (le sh d’Ubuntu), sans syntaxe propre à bash (ou ajouter #!/usr/bin/env bash en tête du hook).

Pour aller plus loin

• Documentation : typicode.github.io/husky
• Suite : Hooks et lint-staged

Dans la même rubrique

• Installation
• Hooks et lint-staged
• Messages de commit avec commitlint
• Pre-push et tests
• Intégration continue et équipes
• Alternative : hooks Git natifs
• Dépannage