Por qué conviene vigilar el historial de commits
Abre el historial de cualquier repositorio con varios meses de vida y lee los últimos cincuenta mensajes. En muchos proyectos verás cosas como “arreglos”, “cambios varios”, “wip” o “ahora sí”. Cada una de esas líneas fue cómoda de escribir y es inútil de leer seis meses después, cuando alguien intenta averiguar por qué se tocó el módulo de pagos o qué versión introdujo un cambio incompatible.
Un mensaje de commit es documentación que viaja pegada al código. Alimenta git log, las revisiones de pull requests, las herramientas de bisección, los generadores de notas de versión y, cada vez más, los sistemas de publicación automática que deciden si la próxima versión es un parche, una funcionalidad nueva o un cambio mayor. Para que todo eso funcione, los mensajes deben seguir una forma predecible, y la disciplina individual rara vez basta en un equipo de más de tres personas.
Aquí entra commitlint, un linter para mensajes de commit. De la misma manera que ESLint rechaza código que rompe las reglas de estilo, commitlint rechaza mensajes que no cumplen la convención acordada. Combinado con un hook de Git gestionado por Husky, el rechazo ocurre en el instante en que alguien ejecuta git commit, antes de que el mal mensaje entre en el historial. Y con una comprobación en integración continua se cubre el caso de quien se salta los hooks locales.
En este tutorial construirás todo el sistema desde cero: un proyecto de práctica, la instalación de commitlint y Husky con sus versiones actuales, la convención Conventional Commits explicada con ejemplos, reglas personalizadas, un flujo de GitHub Actions, y una sección final con los fallos más habituales y cómo resolverlos. Si todavía no dominas las opciones básicas de la orden git commit, conviene repasar antes Git commit explicado: opciones, mensajes y buenas prácticas, porque aquí damos por hecho que sabes crear y enmendar commits.
Versiones y requisitos que vamos a usar
Antes de escribir comandos conviene fijar el terreno, porque tanto commitlint como Husky cambiaron su forma de configurarse en los últimos años y muchos tutoriales antiguos ya no funcionan tal cual.
- commitlint: la línea estable actual es la 20.x, y los paquetes que usaremos son
@commitlint/cliy@commitlint/config-conventional. Pide una versión moderna de Node.js. - Husky: la línea estable es la 9.x. Su gran cambio frente a la 8 es que la instalación se reduce a
npx husky init, y los hooks son ficheros de texto planos sin la cabecera con el script auxiliar que antes era obligatoria. - Node.js: usa una versión con soporte a largo plazo (LTS). A fecha de este artículo, Node 24 y Node 26 son líneas recientes válidas; comprueba cuál figura como LTS activa en la página oficial de versiones antes de fijarla en tu equipo o en tu CI.
- Git: cualquier versión reciente sirve, ya que los hooks existen desde hace muchísimo tiempo.
Si quieres confirmar lo que se instalará realmente en tu máquina, el propio gestor de paquetes te lo dice sin salir de la terminal.
node --version
npm view @commitlint/cli version
npm view husky version
git --version
La salida variará según el día en que lo ejecutes, pero te servirá para dejar constancia de las versiones en la documentación interna del proyecto.
v24.0.0
20.x.x
9.x.x
git version 2.4x.x
Dos cambios de API merecen mención porque aparecen en guías antiguas. Primero, los pasos npx husky install y npx husky add pertenecen a la versión 8 y están en desuso; con la 9 se usa husky init y se escriben los hooks a mano. Segundo, la antigua configuración en un fichero .huskyrc y las variables que se cargaban desde el directorio personal se eliminan progresivamente, de modo que conviene no depender de ellas.
Preparar un proyecto de práctica
Trabajaremos con un proyecto mínimo para que puedas romper cosas sin consecuencias. Imagina una pequeña librería que formatea precios; la llamaremos formato-precios.
mkdir formato-precios
cd formato-precios
git init
npm init -y
El comando npm init -y genera un package.json con valores por defecto. Añade ahora un fichero de código sencillo, un .gitignore y una primera versión de la lógica.
printf "node_modules/\n" > .gitignore
// index.js
function formatearPrecio(valor, moneda = "EUR") {
return new Intl.NumberFormat("es-ES", {
style: "currency",
currency: moneda,
}).format(valor);
}
console.log(formatearPrecio(1234.5));
Ejecútalo para confirmar que funciona.
node index.js
1234,50 €
Todavía no hemos hecho ningún commit. Es intencionado: queremos que el primer commit ya pase por el sistema de validación y así comprobar que funciona desde el principio.
Instalar commitlint y su configuración base
commitlint se divide en dos piezas. El paquete @commitlint/cli es el programa que lee un mensaje y lo valida. El paquete @commitlint/config-conventional es un conjunto de reglas ya preparado que implementa la convención Conventional Commits. Instálalos como dependencias de desarrollo, porque solo los necesita quien contribuye al código, no quien lo ejecuta en producción.
npm install --save-dev @commitlint/cli @commitlint/config-conventional
Después crea el fichero de configuración en la raíz. El detalle que más confunde hoy es el sistema de módulos: si tu package.json declara "type": "module", un fichero .js se interpreta como ESM; si no, como CommonJS. Para evitar ambigüedades puedes usar la extensión explícita .mjs, que siempre es ESM.
// commitlint.config.mjs
export default {
extends: ["@commitlint/config-conventional"],
};
Si prefieres CommonJS, el equivalente es un fichero commitlint.config.cjs con module.exports.
// commitlint.config.cjs
module.exports = {
extends: ["@commitlint/config-conventional"],
};
commitlint también acepta configuración en package.json, en YAML, en JSON y en TypeScript, pero un fichero JavaScript dedicado es lo más flexible, porque permite comentarios y lógica.
Antes de conectar nada a Git puedes probar el linter directamente enviándole un texto por la entrada estándar. Es la forma más rápida de iterar sobre las reglas.
echo "arreglos varios" | npx commitlint
⧗ input: arreglos varios
✖ subject may not be empty [subject-empty]
✖ type may not be empty [type-empty]
✖ found 2 problems, 0 warnings
ⓘ Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint
Ahora un mensaje correcto.
echo "feat: añadir función para formatear precios" | npx commitlint && echo "mensaje válido"
mensaje válido
Observa que commitlint termina con código de salida distinto de cero cuando hay errores. Ese detalle es el que permitirá a Git y a los sistemas de CI detener la operación.
Conectar la validación a Git con Husky 9
Ya tenemos el validador, pero nadie lo invoca. Los hooks de Git son scripts que Git ejecuta en momentos concretos del flujo: antes de confirmar, después de confirmar, antes de enviar, etc. El hook que nos interesa se llama commit-msg: Git lo ejecuta después de que la persona escriba el mensaje y le pasa como argumento la ruta del fichero temporal que lo contiene. Si el script termina con error, el commit se cancela.
El problema práctico de los hooks es que viven en .git/hooks, una carpeta que no se versiona, así que no se comparten con el equipo. Husky resuelve eso moviendo los hooks a una carpeta .husky que sí entra en el repositorio y configurando Git para que la use.
npm install --save-dev husky
npx husky init
El comando husky init hace tres cosas: crea la carpeta .husky con un hook de ejemplo llamado pre-commit, añade al package.json un script prepare con el valor husky, y deja el proyecto listo. El script prepare es importante: npm lo ejecuta automáticamente tras npm install, de forma que cualquier persona que clone el repositorio y instale dependencias obtiene los hooks activados sin pasos manuales.
{
"name": "formato-precios",
"version": "1.0.0",
"scripts": {
"prepare": "husky"
},
"devDependencies": {
"@commitlint/cli": "^20.0.0",
"@commitlint/config-conventional": "^20.0.0",
"husky": "^9.0.0"
}
}
El hook de ejemplo que crea init ejecuta npm test, algo que no queremos por ahora. Puedes borrarlo o dejarlo si más tarde quieres lanzar pruebas antes de cada commit. Crea ahora el hook que sí necesitamos.
echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg
El contenido del fichero queda así.
# .husky/commit-msg
npx --no -- commitlint --edit "$1"
Analicemos la línea. npx --no -- le dice a npx que no intente descargar nada si commitlint no está instalado localmente, sino que falle; así evitamos que un hook descargue paquetes inesperados. --edit "$1" indica a commitlint que lea el mensaje desde el fichero cuya ruta Git pasa como primer argumento. Husky 9 ya no exige la primera línea con el script de arranque, de modo que el fichero puede ser una única orden.
Si trabajas con pnpm o Yarn, cambia el prefijo de ejecución por pnpm exec commitlint --edit "$1" o yarn commitlint --edit "$1". La idea es idéntica.
Probar un commit rechazado y otro aceptado
Con todo en su sitio, añade los ficheros y prueba un mensaje deficiente.
git add -A
git commit -m "primer commit"
⧗ input: primer commit
✖ subject may not be empty [subject-empty]
✖ type may not be empty [type-empty]
✖ found 2 problems, 0 warnings
husky - commit-msg script failed (code 1)
El commit no se creó. Puedes comprobarlo con git log, que informará de que no hay historial todavía. Repite con un mensaje que cumpla la convención.
git commit -m "chore: inicializar proyecto con formateador de precios"
git log --oneline
a1b2c3d chore: inicializar proyecto con formateador de precios
Ese rechazo inmediato es el corazón de todo el sistema y su mayor ventaja. El error aparece en el momento y lugar donde la persona puede corregirlo con un simple reintento, en lugar de descubrirse en una revisión días después.
Una nota sobre el entorno: si usas un cliente gráfico de Git o un editor con integración, el hook también se ejecuta, pero el mensaje de error puede mostrarse en un panel de registro y no en pantalla principal. Si un commit “no hace nada” desde la interfaz, revisa esa salida.
La convención Conventional Commits explicada
La configuración base implementa una especificación sencilla. Un mensaje se compone de una cabecera obligatoria, un cuerpo opcional y un pie opcional.
<tipo>(<ámbito opcional>)<!opcional>: <descripción>
<cuerpo opcional>
<pie opcional>
La cabecera lleva el tipo, que indica la naturaleza del cambio, seguido opcionalmente de un ámbito entre paréntesis que señala la parte del proyecto afectada, y después dos puntos, un espacio y una descripción breve. Los tipos que acepta la configuración convencional por defecto son estos:
feat: una funcionalidad nueva para quien usa el software.fix: la corrección de un error.docs: cambios solo en documentación.style: formato que no altera el significado del código, como espacios o punto y coma.refactor: reorganización del código sin añadir funciones ni corregir fallos.perf: mejoras de rendimiento.test: añadir o corregir pruebas.build: cambios en el sistema de compilación o dependencias.ci: cambios en la configuración de integración continua.chore: tareas de mantenimiento que no encajan en las anteriores.revert: reversión de un commit anterior.
Algunos ejemplos reales para nuestra librería de precios muestran la variedad de usos.
feat(moneda): admitir códigos ISO de tres letras
fix(redondeo): corregir el error con valores negativos
docs(readme): documentar los parámetros de formatearPrecio
refactor(formato): extraer la creación del formateador a una función
perf(cache): reutilizar instancias de Intl.NumberFormat
test(redondeo): cubrir casos con cero y números muy grandes
El ámbito es opcional pero muy útil cuando el repositorio tiene varias áreas. Si un cambio toca más de una, puedes separar ámbitos con comas, aunque es una señal de que quizá deberías haber hecho dos commits distintos.
Cambios incompatibles y pies de mensaje
Cuando un cambio rompe la compatibilidad con versiones anteriores, la convención exige señalarlo de forma explícita. Hay dos maneras, que se pueden combinar: añadir un signo de exclamación antes de los dos puntos, o incluir un pie que empiece por BREAKING CHANGE: seguido de la explicación.
feat(api)!: el segundo parámetro pasa a ser un objeto de opciones
BREAKING CHANGE: formatearPrecio(valor, moneda) ahora es
formatearPrecio(valor, { moneda, locale }). Actualiza las llamadas existentes.
Los pies también sirven para referenciar incidencias, por ejemplo Refs: #128 o Closes: #97, y para dar crédito con Co-authored-by. commitlint exige una línea en blanco antes del cuerpo y otra antes del pie; olvidarlas es una de las causas más frecuentes de fallo, como veremos más adelante.
Qué ganas con todo esto
Existen razones prácticas para el esfuerzo. Los generadores de registro de cambios pueden leer el historial y producir notas de versión ordenadas por tipo sin intervención humana. Las herramientas de publicación automática pueden aplicar versionado semántico: un fix incrementa el parche, un feat la versión menor y un cambio marcado como incompatible la mayor. Y las personas que revisan pueden filtrar el historial con precisión.
git log --oneline --grep="^feat"
git log --oneline --grep="^fix(redondeo)"
Esto último conecta con la forma en que el equipo organiza su trabajo; si estás decidiendo cómo estructurar ramas y entregas, la guía cómo elegir un flujo de trabajo en Git según tu equipo te ayuda a encajar estas convenciones con el modelo de ramas adecuado.
Ajustar las reglas a las necesidades del equipo
La configuración convencional es un punto de partida razonable, pero cada equipo tiene su vocabulario. Puedes sobrescribir cualquier regla en la propiedad rules. Cada regla se expresa como una lista de tres elementos: el nivel (0 desactivada, 1 advertencia, 2 error), la condición (always o never) y el valor de la regla.
Supongamos que tu equipo trabaja en una biblioteca de componentes de interfaz y quiere un tipo propio componente para cambios en ellos, además de deps para actualizaciones de dependencias. Hay que redefinir la lista completa de tipos permitidos, porque la regla reemplaza a la original en lugar de añadirse a ella.
// commitlint.config.mjs
export default {
extends: ["@commitlint/config-conventional"],
rules: {
"type-enum": [
2,
"always",
[
"feat",
"fix",
"docs",
"style",
"refactor",
"perf",
"test",
"build",
"ci",
"chore",
"revert",
"componente",
"deps",
],
],
},
};
Un truco para no copiar la lista a mano es importarla de la propia configuración, aunque eso exige conocer su estructura interna y puede romperse con una actualización mayor. Para la mayoría de equipos, escribir la lista explícita es más claro y estable.
Otras reglas que suelen ajustarse en la práctica:
export default {
extends: ["@commitlint/config-conventional"],
rules: {
// Límite de longitud de la cabecera: por defecto 100 caracteres
"header-max-length": [2, "always", 72],
// Obligar a que exista ámbito
"scope-empty": [2, "never"],
// Limitar los ámbitos a una lista cerrada
"scope-enum": [2, "always", ["api", "formato", "moneda", "docs", "ci"]],
// La descripción no debe terminar en punto
"subject-full-stop": [2, "never", "."],
// Permitir cualquier capitalización en la descripción
"subject-case": [0],
// El cuerpo no debe superar cierta anchura por línea
"body-max-line-length": [1, "always", 100],
},
};
La regla subject-case merece atención. La configuración convencional prohíbe ciertos estilos de mayúsculas, lo cual choca con descripciones en español que empiezan por un nombre propio o una sigla. Desactivarla con nivel 0 es habitual en equipos hispanohablantes. Para ver todas las reglas disponibles y sus valores por defecto, consulta la documentación de reglas de commitlint o imprime la configuración resuelta.
npx commitlint --print-config
Una vez aplicados los cambios, prueba que un tipo nuevo se acepta.
echo "componente: añadir botón con variante secundaria" | npx commitlint && echo "válido"
válido
Y que uno desconocido se rechaza.
echo "boton: añadir variante" | npx commitlint
⧗ input: boton: añadir variante
✖ type must be one of [feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, componente, deps] [type-enum]
✖ found 1 problems, 0 warnings
Al diseñar reglas propias, un consejo: empieza con pocas. Una lista de tipos de veinte elementos es difícil de recordar y la gente acabará eligiendo uno al azar para que el commit pase, que es peor que no tener regla. Revisa cada trimestre qué tipos se usan de verdad y poda los demás.
Comprobar los commits también en integración continua
Un hook local es una ayuda, no una garantía, y la comprobación en el servidor completa el sistema. Cualquiera puede saltárselo con git commit --no-verify, puede trabajar en una máquina donde npm install no se ejecutó, o puede editar desde una interfaz web que nunca dispara los hooks. Por eso la comprobación en el servidor es el segundo pilar: aunque el hook falle, la pull request no podrá fusionarse si el pipeline marca error.
Con GitHub Actions basta un fichero dentro de .github/workflows. La carpeta debe llamarse exactamente así, con punto inicial y en plural; un error de nombre hace que el flujo simplemente no se ejecute, y no se muestra ningún aviso.
# .github/workflows/commitlint.yml
name: Validar mensajes de commit
on:
pull_request:
push:
branches: [main]
jobs:
commitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: lts/*
cache: npm
- run: npm ci
- name: Validar los commits de la pull request
if: github.event_name == 'pull_request'
run: npx commitlint --from origin/main --to HEAD --verbose
- name: Validar el último commit del push
if: github.event_name == 'push'
run: npx commitlint --last --verbose
Hay varias decisiones que explicar. La opción fetch-depth: 0 descarga el historial completo; sin ella, el repositorio se clona con un solo commit y la comparación de rangos falla. El valor lts/* en setup-node selecciona la versión LTS vigente, lo que evita fijar un número que quede obsoleto, aunque en proyectos serios es mejor fijar una versión concreta en un fichero .nvmrc y leerla desde ahí. Usar npm ci en lugar de npm install garantiza instalaciones reproducibles a partir del fichero de bloqueo. Comprueba además la última versión mayor de cada acción en su página de publicación, ya que sus etiquetas avanzan con frecuencia.
Observa que usamos directamente nuestra propia dependencia en lugar de una acción de terceros: así el CI valida con exactamente la misma versión y la misma configuración que el hook local, y no hay dos fuentes de verdad.
Un detalle de las pull requests con fusión squash: si tu equipo fusiona aplastando commits, lo que acaba en la rama principal es el título de la pull request, no los mensajes individuales. En ese caso conviene validar también el título. Puedes hacerlo pasando el título a commitlint desde una variable de entorno del paso, sin interpolar texto no confiable directamente en el script.
- name: Validar el título de la pull request
if: github.event_name == 'pull_request'
env:
TITULO_PR: ${{ github.event.pull_request.title }}
run: printf '%s\n' "$TITULO_PR" | npx commitlint
Pasar el valor por env y no incrustarlo en la orden es una medida de seguridad: un título malicioso con comillas o comandos no puede inyectarse en la shell. Finalmente, marca este trabajo como comprobación obligatoria en las reglas de protección de la rama principal; de lo contrario, el aviso rojo será meramente informativo.
El mismo comando se traslada a otros sistemas. En un servidor de automatización como Jenkins, por ejemplo, basta con añadir una etapa que ejecute npx commitlint --from origin/main --to HEAD; si quieres ver cómo montar ese tipo de pipeline de principio a fin, consulta Jenkins desde cero: construye un pipeline CI/CD con Docker y GitHub.
Hacer que escribir el mensaje sea menos doloroso
Un sistema que solo rechaza genera frustración. Algunas ayudas reducen la fricción y aumentan la adopción.
La primera es una plantilla de mensaje de Git. Puedes crear un fichero con instrucciones en comentarios y activarlo para el repositorio, de modo que cada vez que se abre el editor aparezca la estructura esperada.
# <tipo>(<ámbito>): <descripción breve, imperativo, sin punto final>
#
# Cuerpo: explica qué cambia y por qué, no cómo.
#
# Pie: BREAKING CHANGE: ..., Refs: #número
#
# Tipos: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
git config commit.template .gitmessage
La segunda es usar un asistente interactivo. Existen herramientas que preguntan por el tipo, el ámbito y la descripción y componen el mensaje; funcionan bien con commitlint porque comparten la misma convención. Son opcionales: algunas personas prefieren escribir directamente.
La tercera es combinar commitlint con otros hooks. Husky puede ejecutar más de uno, así que un hook pre-commit puede lanzar el formateador y el linter de código solo sobre los ficheros preparados, mientras commit-msg valida el texto. Mantén los hooks rápidos: si un commit tarda diez segundos, la gente buscará la forma de saltárselo.
# .husky/pre-commit
npx --no -- lint-staged
Y la cuarta, quizá la más importante, es explicar el porqué al equipo. Una regla impuesta sin contexto se vive como burocracia; una regla con un objetivo visible, como “generamos las notas de versión automáticamente”, se vive como una inversión.
Errores frecuentes y cómo resolverlos
Aunque la configuración es breve, hay una lista corta de problemas que se repite casi siempre.
El hook no se ejecuta. Comprueba que Git apunta a la carpeta correcta.
git config core.hooksPath
.husky/_
Si la salida está vacía, Husky no se activó: ejecuta npm install para que corra el script prepare, o npx husky manualmente. Si el repositorio de Git está en una carpeta superior al package.json, por ejemplo en un monorepo, Husky debe invocarse indicando el directorio, de modo que el script prepare suele pasar a ser algo como cd .. && husky app/.husky.
Permiso denegado en sistemas Unix. Los hooks deben tener permiso de ejecución en algunas configuraciones antiguas. Si ves un mensaje de permisos, aplica el permiso a los ficheros de hooks.
chmod +x .husky/commit-msg
El comando no encuentra commitlint. Si usas un gestor de versiones de Node como nvm, los programas gráficos pueden no heredar tu entorno y el hook no localiza npx. Husky permite definir un fichero de arranque en el directorio personal para cargar el gestor; consulta su documentación de inicio si el fallo ocurre solo desde clientes gráficos.
Error de configuración con ESM y CommonJS. Si ves un mensaje sobre require no definido o sobre una exportación inesperada, es el choque de sistemas de módulos descrito antes. La solución más limpia es renombrar el fichero a .mjs o .cjs según la sintaxis que uses.
Falta la línea en blanco. Los mensajes con cuerpo deben separarse de la cabecera por una línea vacía, y los pies del cuerpo por otra. El mensaje de error lo indica con body-leading-blank o footer-leading-blank.
⧗ input: fix: corregir redondeo
Se usaba Math.round en lugar de toFixed
✖ body must have leading blank line [body-leading-blank]
Mensajes generados automáticamente. Las fusiones (Merge branch ...), las reversiones y los commits de herramientas de versionado producen textos que commitlint reconoce por defecto como ignorados, pero si un robot genera un formato propio, añade un patrón en la propiedad ignores de la configuración.
export default {
extends: ["@commitlint/config-conventional"],
ignores: [(mensaje) => mensaje.startsWith("Bump ")],
};
El pipeline falla solo en CI. Casi siempre es por el historial truncado. Verifica que el paso de checkout usa fetch-depth: 0 y que la rama base existe con el nombre que le pasas a --from. Si tu rama principal se llama master o develop, ajusta el nombre.
Se usa --no-verify con frecuencia. Es un síntoma, no un delito: o los hooks son demasiado lentos, o las reglas son demasiado estrictas, o la gente no entiende su utilidad. Atiende la causa; la comprobación en CI sigue protegiendo la rama.
Buenas prácticas para mantener el sistema a largo plazo
Una vez funcionando, la configuración requiere poco mantenimiento, pero algunas costumbres evitan que se degrade.
Versiona la configuración junto al código y revisa los cambios de reglas en pull request, igual que cualquier otro cambio. Cuando actualices commitlint o Husky a una versión mayor, lee las notas de migración: ya hemos visto que Husky 9 cambió la manera de definir hooks, y las versiones mayores de commitlint han subido el mínimo de Node requerido.
Escribe en el README una sección corta con los tipos permitidos, un par de ejemplos y la manera de saltar la validación en casos excepcionales. Quien contribuya por primera vez agradecerá no tener que descubrir las reglas a base de errores.
Procura que los mensajes describan la intención y no el mecanismo. Compara estos dos:
fix: cambiar toFixed por Intl.NumberFormat
fix(formato): mostrar dos decimales en importes con cero a la derecha
El primero informa de una línea de código que ya se ve en el diff; el segundo explica qué problema notará quien use la librería. Una descripción en modo imperativo y presente, de unos cincuenta a setenta y dos caracteres, y un cuerpo que explique la motivación cuando el cambio no es evidente, convierten el historial en una fuente de conocimiento real.
Haz commits pequeños y atómicos. Una convención que obliga a elegir un único tipo y ámbito te empuja de forma natural a separar cambios: si no puedes decidir si algo es feat o refactor, probablemente son dos commits. Esta práctica facilita las reversiones, las bisecciones y las revisiones.
Por último, automatiza las consecuencias. Una convención solo se mantiene viva si produce algo tangible. Conecta el historial con la generación del registro de cambios y con la publicación de versiones, y verás cómo el equipo cuida los mensajes por interés propio, porque su trabajo aparece en las notas de versión.
Alternativas y complementos
commitlint no es la única opción, y conviene conocer el panorama para decidir con criterio.
Para ejecutar hooks existen alternativas a Husky, como lefthook, que está escrito en Go, es rápido y no depende de Node, o simple-git-hooks, una opción minimalista basada en configuración dentro de package.json. Si tu proyecto no es JavaScript, lefthook o el marco de trabajo pre-commit de Python resultan más naturales, ya que evitan añadir un package.json solo para gobernar los commits. commitlint se puede invocar desde cualquiera de ellos, ya que es solo un ejecutable.
En cuanto al formato, no todo equipo adopta Conventional Commits. Algunos prefieren prefijos con el identificador de la incidencia, como PAY-231: corregir redondeo, y otros usan emojis como código de tipo. commitlint admite convenciones distintas mediante configuraciones compartidas o reglas personalizadas, por ejemplo con un patrón en references-empty o un plugin propio. Elige la convención que tu equipo sea capaz de mantener, no la más de moda.
Existen también servicios y comprobaciones en el lado del servidor que validan títulos de pull requests sin ejecutar nada en el repositorio. Son prácticos para proyectos de código abierto con muchas contribuciones externas, donde no puedes exigir que cada persona instale los hooks.
Para el paso siguiente tras la validación, existen herramientas que leen el historial convencional y automatizan el versionado y el registro de cambios. Funcionan bien porque el trabajo duro, que es tener mensajes homogéneos, ya lo hace commitlint.
Un flujo completo de principio a fin
Para fijar lo aprendido, recorramos una jornada típica en el proyecto de práctica. Creas una rama, haces un cambio y lo confirmas.
git switch -c feature/soporte-locale
Modificas index.js para aceptar un parámetro de idioma.
// index.js
function formatearPrecio(valor, moneda = "EUR", locale = "es-ES") {
return new Intl.NumberFormat(locale, {
style: "currency",
currency: moneda,
}).format(valor);
}
console.log(formatearPrecio(1234.5));
console.log(formatearPrecio(1234.5, "USD", "en-US"));
node index.js
1234,50 €
$1,234.50
Intentas un commit descuidado y el hook lo frena.
git commit -am "Soporte de locale"
⧗ input: Soporte de locale
✖ subject may not be empty [subject-empty]
✖ type may not be empty [type-empty]
✖ found 2 problems, 0 warnings
husky - commit-msg script failed (code 1)
Corriges el mensaje, esta vez con cuerpo y pie.
git commit -am "feat(formato): permitir elegir el idioma de salida" \
-m "El tercer parámetro de formatearPrecio acepta un locale BCP 47.
Por defecto se mantiene es-ES para no alterar el comportamiento actual." \
-m "Refs: #14"
[feature/soporte-locale 9f8e7d6] feat(formato): permitir elegir el idioma de salida
1 file changed, 5 insertions(+), 3 deletions(-)
Subes la rama y abres la pull request. El flujo de GitHub Actions comprueba los commits del rango y el título; si todo cumple, aparece la marca verde y la fusión queda permitida. Después de fusionar, una herramienta de publicación puede leer ese feat y proponer una versión menor con una entrada en el registro de cambios que diga exactamente lo que escribiste. Ese es el ciclo completo: un mensaje cuidadoso hoy se convierte en documentación y automatización mañana.
Conclusiones
Imponer una convención sobre los mensajes de commit no es un capricho estético. Con muy poca configuración obtienes un historial legible, filtrable y utilizable por máquinas, y reduces el tiempo que el equipo dedica a descifrar qué hizo cada cambio y por qué.
La receta se resume en cuatro piezas que se refuerzan entre sí. commitlint 20 define y valida las reglas; la configuración convencional te da un punto de partida sensato; Husky 9 activa el hook commit-msg en cada máquina mediante el script prepare; y un flujo de CI repite la comprobación en el servidor, donde nadie puede saltárselo. Sobre esa base puedes añadir tipos y ámbitos propios, plantillas, asistentes interactivos y automatización de versiones.
Para empezar hoy mismo, instala las dos dependencias, crea el fichero de configuración, ejecuta npx husky init y añade el hook de una línea. Después, activa la comprobación como obligatoria en la rama principal y comparte con tu equipo una explicación breve de los tipos admitidos. Ajusta las reglas con el uso real, mantén los hooks rápidos y revisa las notas de migración al actualizar. Con esa disciplina mínima, el historial de tu repositorio pasará de ser un cajón de sastre a convertirse en una de sus mejores piezas de documentación.
