Git Hooks con Husky: Automatizar Linting, Formato y Tests antes de Commitear
Cómo impedir que código con errores tipográficos, imports rotos o pruebas fallidas llegue jamás a tu repositorio de GitHub.
Los Git Hooks (Ganchos de Git) son scripts personalizados que Git ejecuta de forma automática antes o después de eventos clave en el ciclo de vida del repositorio (como hacer un commit, enviar un push o cambiar de rama). Por ejemplo, un hook de tipo `pre-commit` puede revisar tu código en milisegundos y, si encuentra un error de sintaxis o un test roto, **cancela el commit inmediatamente** impidiendo que el error se grabe. El problema histórico de los hooks nativos de Git es que se guardan en la carpeta `.git/hooks/`, la cual **nunca se sube a GitHub** al clonar. Cada desarrollador del equipo tendría que copiar y pegar los scripts a mano. **Husky** es una herramienta estándar de la industria que soluciona esto por completo: permite versionar y compartir tus Git Hooks dentro del repositorio en una carpeta accesible (`.husky/`), asegurando que todos los miembros del equipo y los nuevos programadores tengan las mismas reglas de calidad activas de forma automática.
- ✓Filtro en la Fuente: Impide que código mal formateado o con errores tipográficos llegue al repositorio remoto.
- ✓Ahorro de Tiempo y Dinero en CI/CD: Es mucho más barato y rápido que el hook falle en 2 segundos en la laptop del programador a esperar 15 minutos a que falle en el pipeline de GitHub Actions en la nube.
- ✓Formateo Transparente con lint-staged: Formatea con Prettier únicamente los archivos modificados que están en el área de staging (`git add`), sin tocar el resto del proyecto.
- •Elimina las discusiones de estilo y espacios en las revisiones de código (Pull Requests).
- •Evita que alguien suba por error contraseñas, archivos `.env` o credenciales a GitHub.
- •Garantiza que el comando `npm test` pase al 100% antes de permitir un `git push`.
Imagina que vas a abordar un vuelo internacional (hacer un `git push` a la rama principal de producción). Tienes que pasar obligatoriamente por el escáner de seguridad de la aduana (el **Pre-Commit Hook**). El oficial de aduanas inspecciona tu maleta antes de dejarte subir al avión. Si detecta que llevas una botella de líquido prohibido o un objeto punzocortante (un error de ESLint o una prueba unitaria rota), te dice amablemente: *'Usted no puede abordar el avión hasta que saque este objeto prohibido de su maleta'*. No importa cuánto le ruegues, la puerta no se abre hasta que el equipaje esté limpio y seguro.
Explicación Paso a Paso del Tema
Instalar y Configurar Husky en un Proyecto
Inicializa Husky en tu proyecto Node.js / TypeScript ejecutando el comando de instalación automática.
Esto configurará la directiva `core.hooksPath` de Git hacia la carpeta `.husky/`.
npx husky-init && npm install
| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| husky-init | Script CLI | Crea la carpeta .husky, añade el hook pre-commit de ejemplo y actualiza package.json. |
El script `prepare: "husky install"` en tu `package.json` asegurará que cualquiera que clone el proyecto e instale paquetes tenga los hooks activos de inmediato.
Combinar Husky con lint-staged para Máxima Velocidad
Si tienes 5,000 archivos, correr el linter en todo el proyecto antes de cada commit tomaría 40 segundos. Instala `lint-staged` para revisar exclusivamente los archivos que estás a punto de commitear.
Configura las reglas en tu `package.json`.
// En package.json:
{
"lint-staged": {
"*.{js,ts,tsx}": [
"prettier --write",
"eslint --fix"
],
"*.json": [
"prettier --write"
]
}
}| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| prettier --write | Comando | Corrige sangrías, comillas y formatos de código automáticamente. |
| eslint --fix | Comando | Corrige advertencias y errores de buenas prácticas de programación. |
Escribir `npm test` en el pre-commit si tu suite de pruebas tarda más de 3 minutos: los desarrolladores se cansarán de esperar y usarán `--no-verify`. Deja las pruebas pesadas para el pre-push o para GitHub Actions.
Crear un Pre-Push Hook para Pruebas Unitarias
Puedes crear un hook de tipo `pre-push` que se dispare únicamente cuando el programador intente enviar sus cambios a GitHub.
Si las pruebas unitarias fallan, el push se cancela evitando romper la rama compartida.
npx husky add .husky/pre-push "npm test"
| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| pre-push | Tipo de Gancho | Se ejecuta justo antes de que los paquetes viajen por la red hacia el servidor remoto. |
En casos de extrema emergencia donde necesites commitear sin ejecutar los hooks, puedes usar `git commit -m "mensaje" --no-verify`, pero úsalo con máxima precaución.
Casos Prácticos Reales en Producción
Situaciones de ingeniería reales sin mención de presupuestos ficticios.
1La Prevención de Subida de Claves API de AWS a un Repositorio Público
Una empresa sufrió en el pasado una fuga de seguridad de 20,000 dólares cuando un programador subió accidentalmente una clave secreta de AWS a un repositorio público de GitHub.
Instalaron Husky junto con la herramienta `git-secrets` y `gitleaks` como pre-commit hook obligatorio.
Fichas Nemotécnicas de Conceptos Clave
Glosario rápido para recordar los términos fundamentales de la lección.
Script que Git dispara de forma nativa ante eventos como pre-commit, commit-msg, pre-push o post-merge.
Herramienta de desarrollo que permite versionar, compartir y ejecutar Git Hooks de forma automática en equipos de desarrollo.
Utilidad que filtra y ejecuta formateadores y linters únicamente sobre los archivos que están en el área de staging de Git.
Git Hooks con Husky: Automatizar Linting, Formato y Tests antes de Commitear
Selecciona una opción para autoevaluarte al instante. La respuesta se califica de inmediato.
¿Por qué los Git Hooks nativos ubicados en .git/hooks/ no se comparten con el equipo al hacer git push?
¿Cuál es la principal ventaja de utilizar 'lint-staged' en lugar de ejecutar ESLint sobre todo el proyecto en cada commit?
¿Qué bandera de Git permite saltear la ejecución de los hooks en una emergencia excepcional?
Preguntas Frecuentes (FAQ)
¿Qué es el hook 'commit-msg'?
Es un hook que se dispara justo después de que escribes el mensaje del commit pero antes de crearlo. Se utiliza frecuentemente con herramientas como `commitlint` para asegurar que el mensaje cumpla con estándares como Conventional Commits (`feat: ...`, `fix: ...`).
¿Los Git Hooks sustituyen a las comprobaciones de GitHub Actions (CI/CD)?
No. Los hooks son tu primera línea de defensa rápida en la máquina del programador. Pero un desarrollador siempre puede usar `--no-verify` o desinstalar Husky en su PC local. Por ello, GitHub Actions en la nube actúa como el juez final obligatorio antes de aceptar cualquier Pull Request.