Nivel inicial20 min de lectura · Publicado el

Git Commitizen y Conventional Commits: cómo usar git cz

Git Commitizen: un historial de commits sin convención (wip, ahora sí) frente a mensajes con Conventional Commits: feat(calculadora), fix y docs. Cada commit dice qué cambiórubentejera.com wipahora sífeat(calculadora):añade la función sumafix:docs:
Sin convención, el historial es un diario: «wip», «arreglo», «ahora sí». Commitizen (cz) te pregunta tipo, ámbito y descripción, y lo convierte en un índice: feat(calculadora): añade la función suma, fix, docs.

Abres el historial de un proyecto y encuentras esto: «cambios», «arreglo», «wip», «ahora sí». Nadie sabe qué cambió en cada commit sin abrirlo, y preparar las notas de una versión se convierte en arqueología.

Es como un diario: todo está apuntado, pero para encontrar algo tienes que leerlo entero. Un índice, en cambio, dice en cada línea qué hay, y encuentras lo que buscas sin abrir cada commit.

Commitizen facilita la homogeneidad y la estandarización en los mensajes de commit: en lugar de una línea en blanco, te pregunta qué tipo de cambio es, a qué parte afecta y qué hace, y escribe la etiqueta por ti.

Qué es Commitizen

Commitizen (a veces se busca como «commitzen» o «comitizen») es una herramienta de línea de comandos que sustituye a git commit por un pequeño asistente. Hay dos herramientas con el mismo nombre y la misma idea:

Para Node (cz-cli) Para Python (commitizen-tools)
Repositorio commitizen/cz-cli commitizen-tools/commitizen
Instalación npm install -D commitizen pip install commitizen (o pipx, uv)
Hacer un commit npx cz, git cz o npm run commit cz commit o cz c
Versiones y changelog No (se combina con otras herramientas) Sí: cz bump y cz changelog
Validar mensajes Con commitlint cz check

La de Python sirve para cualquier proyecto, no solo de Python: solo necesita Python 3.10 o superior y Git.

Qué es Conventional Commits: formato, tipos y ejemplos

Conventional Commits 1.0.0 es una especificación: unas pocas reglas sobre cómo escribir el mensaje de cada commit. Las dos versiones de Commitizen la siguen por defecto, y commitlint la comprueba. Según la propia especificación, sirve para generar el changelog automáticamente, decidir el siguiente número de versión a partir de los commits, contar a los demás qué tipo de cambio es cada uno y lanzar procesos de build y publicación.

Es como el remite y el asunto de un sobre: con leer la primera línea ya sabes de qué va la carta y si te toca abrirla.

El formato

<tipo>[ámbito opcional]: <descripción>

[cuerpo opcional]

[nota(s) al pie opcional(es)]

Cada parte tiene sus reglas:

  • Tipo: la palabra del principio (feat, fix…), seguida de dos puntos y un espacio. Es obligatorio.
  • Ámbito: opcional. Un sustantivo entre paréntesis que dice a qué parte del código afecta: fix(parser):, feat(calculadora):.
  • Descripción: va justo después de los dos puntos y el espacio, y resume el cambio en una línea.
  • Cuerpo: opcional. Empieza tras una línea en blanco y es texto libre, con los párrafos que hagan falta. Es el sitio para explicar el porqué.
  • Pies (footers): opcionales. Van tras otra línea en blanco y tienen la forma Token: valor o Token #valor, al estilo de los trailers de Git. El token usa guiones en lugar de espacios (Reviewed-by, Refs); la única excepción es BREAKING CHANGE.

La especificación no distingue mayúsculas y minúsculas en ninguna parte, salvo en BREAKING CHANGE, que va siempre en mayúsculas. Para el resto recomienda ser coherente.

Los tipos

La especificación solo define dos tipos y los hace obligatorios para su caso: feat cuando el commit añade una funcionalidad y fix cuando corrige un error. Permite usar otros y, como ejemplo, cita los que recomienda @commitlint/config-conventional, basado en la convención de Angular: build, chore, ci, docs, style, refactor, perf y test. En sus preguntas frecuentes sugiere además revert para deshacer commits.

Tipo Cuándo se usa Efecto en la versión
feat Añades una funcionalidad nueva Sube la versión menor (1.2.0 → 1.3.0)
fix Corriges un error Sube el parche (1.2.0 → 1.2.1)
docs Solo cambia documentación Ninguno
style Formato, espacios, punto y coma; el código hace lo mismo Ninguno
refactor Cambias el código sin añadir funcionalidad ni corregir errores Ninguno
perf Mejoras el rendimiento Ninguno
test Añades o corriges tests Ninguno
build, ci, chore Dependencias, integración continua, tareas de mantenimiento Ninguno
revert Deshaces un commit anterior Ninguno

Lo que dice cada tipo, salvo feat y fix, viene de la convención de Angular, que es la que muestran Commitizen y commitlint, no de la especificación. Tu equipo puede añadir los suyos.

Cambios incompatibles: BREAKING CHANGE y !

Un cambio incompatible (breaking change) obliga a quien usa tu código a adaptarse: quitas una función, cambias un parámetro, cambias un valor por defecto. La especificación exige marcarlo, de una de estas dos formas o con las dos:

  • Con ! justo antes de los dos puntos: feat!: o feat(api)!:. Entonces la descripción explica el cambio y el pie se puede omitir.
  • Con un pie que empiece por BREAKING CHANGE: en mayúsculas, seguido de la explicación. BREAKING-CHANGE: vale lo mismo.

Puede ir en un commit de cualquier tipo, no solo en feat.

La relación con SemVer

Semantic Versioning (SemVer) numera las versiones como MAYOR.MENOR.PARCHE. Conventional Commits encaja con él así:

El commit lleva… Versión que toca Ejemplo
fix Parche 1.2.0 → 1.2.1
feat Menor 1.2.0 → 1.3.0
! o BREAKING CHANGE, sea del tipo que sea Mayor 1.2.0 → 2.0.0
Cualquier otro tipo, sin cambio incompatible Ninguna 1.2.0

Esa tabla es la base que usan herramientas como cz bump, que verás más abajo, para calcular la versión sola. Cada herramienta puede afinarla: cz bump, por ejemplo, también sube el parche con refactor y perf.

Ejemplos

Son los ejemplos de la especificación, traducidos. Con ámbito:

feat(lang): añade el idioma polaco

Sin cuerpo:

docs: corrige la ortografía de CHANGELOG

Cambio incompatible marcado con !, con o sin ámbito:

feat(api)!: envía un correo al cliente cuando se envía un producto

Cambio incompatible explicado en el pie:

feat: permite que un objeto de configuración extienda otros

BREAKING CHANGE: la clave `extends` de la configuración ahora sirve para extender otros ficheros

Con las dos marcas a la vez:

feat!: deja de dar soporte a Node 6

BREAKING CHANGE: usa funciones de JavaScript que no existen en Node 6.

Cuerpo de varios párrafos y varios pies:

fix: evita la carrera entre peticiones

Añade un identificador a cada petición y una referencia a la última.
Descarta las respuestas que no sean de la última petición.

Quita los tiempos de espera que se usaban para mitigarlo, que ya no hacen falta.

Reviewed-by: Z
Refs: #123

Todos pasan commitlint con la configuración convencional. Un tipo mal escrito, no:

echo "feet: añade la resta" | npx commitlint
⧗   --- input ---
feet: añade la resta
✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]

✖   found 1 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

La lista de tipos de ese error es la de @commitlint/config-conventional, no la de la especificación. La especificación admite otros tipos además de feat y fix, pero en sus preguntas frecuentes pone feet como ejemplo de tipo que no la cumple: no es grave, aunque las herramientas basadas en ella pasarían ese commit por alto. Lo mismo pasa con el límite de 100 caracteres por línea que aplica esa configuración: la especificación no fija ninguno.

Si un commit encaja en dos tipos a la vez, la especificación recomienda dividirlo en varios commits. Y si te equivocas de tipo antes de fusionar la rama, sugiere corregirlo reescribiendo el historial con git rebase -i.

Un buen historial se lee como un índice, no como un diario.

Commitizen en un proyecto Node (cz-cli)

  1. Instala Commitizen en el proyecto.
  2. Elige el adaptador de Conventional Commits.
  3. Añade un script y haz commits con él.

1. Instálalo en el proyecto

Mejor como dependencia de desarrollo que de forma global: así todo el equipo usa la misma versión.

npm install --save-dev commitizen

2. Configura el adaptador

Commitizen necesita un adaptador, que define qué preguntas hace y qué formato tiene el mensaje. El de Conventional Commits es cz-conventional-changelog:

npx commitizen init cz-conventional-changelog --save-dev --save-exact
Attempting to initialize using the npm package cz-conventional-changelog

Instala el adaptador y añade esto a tu package.json:

"config": {
  "commitizen": {
    "path": "./node_modules/cz-conventional-changelog"
  }
}

Si usas Yarn o pnpm, la documentación indica --yarn --dev --exact o --pnpm --save-dev --save-exact.

3. Haz commits con npm run commit

Añade el script:

npm pkg set scripts.commit=cz

Prepara tus cambios con git add y, en lugar de git commit, ejecuta npm run commit (o npx cz). Esta es la salida real en un repositorio de prueba:

> [email protected] commit
> cz

[email protected], [email protected]

? Select the type of change that you're committing: (Use arrow keys)
❯ feat:     A new feature
  fix:      A bug fix
  docs:     Documentation only changes
  style:    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  refactor: A code change that neither fixes a bug nor adds a feature
  perf:     A code change that improves performance
(Move up and down to reveal more choices)

Eliges el tipo con las flechas y respondes al resto de preguntas. Las que no necesites se saltan con Enter:

? Select the type of change that you're committing: feat:     A new feature
? What is the scope of this change (e.g. component or file name): (press enter to skip) calculadora
? Write a short, imperative tense description of the change (max 81 chars):
 (21) añade la función suma
? Provide a longer description of the change: (press enter to skip)

? Are there any breaking changes? No
? Does this change affect any open issues? No
[main (commit-raíz) acb6476] feat(calculadora): añade la función suma
 4 files changed, 2021 insertions(+)

Si el commit falla (por ejemplo, porque no pasan los tests de un hook), no hace falta responder otra vez a todo: npx cz --retry reutiliza las respuestas del último intento. Desde el script es npm run commit -- --retry.

Commitizen en Python (commitizen-tools)

La versión de Python hace lo mismo y además calcula la siguiente versión del proyecto a partir de los commits y escribe el changelog.

Instalación

La documentación recomienda instalarlo como herramienta global con pipx install commitizen o uv tool install commitizen. Para un proyecto concreto, dentro de un entorno virtual:

python3 -m venv .venv
.venv/bin/pip install -U commitizen
.venv/bin/cz version
4.19.3

Configuración con cz init

cz init te guía para crear la configuración. Con las opciones por defecto en un proyecto con pyproject.toml:

Welcome to commitizen!
Answer the following questions to configure your project.
? Please choose a supported config file:  pyproject.toml
? Please choose a cz (commit rule): (default: cz_conventional_commits) cz_conventional_commits
? Choose the source of the version: pep621: Get and set version from pyproject.toml:project.version field
? Choose version scheme:  pep440
? Please enter the correct version format: (default: "$version")
? Create changelog automatically on bump Yes
? Keep major version zero (0.x) during breaking changes Yes
You can bump the version running:
	cz bump
Configuration complete 🚀

Y añade esto a pyproject.toml:

[tool.commitizen]
name = "cz_conventional_commits"
tag_format = "$version"
version_scheme = "pep440"
version_provider = "pep621"
update_changelog_on_bump = true
major_version_zero = true

Si prefieres etiquetas como v1.2.0, cambia tag_format a "v$version".

Hacer un commit con cz commit

cz commit (o su atajo cz c) hace las mismas preguntas:

? Select the type of change you are committing feat: A new feature. Correlates with MINOR in SemVer
? What is the scope of this change? (class or file name): (press [enter] to skip) calculadora
? Write a short and imperative summary of the code changes: (lower case and no period) añade la función suma
? Provide additional contextual information about the code changes: (press [enter] to skip)
? Is this a BREAKING CHANGE? Correlates with MAJOR in SemVer No
? Footer. Information about Breaking Changes and reference issues that this commit closes: (press [enter] to skip)

feat(calculadora): añade la función suma
[main (commit-raíz) b6f9335] feat(calculadora): añade la función suma
 3 files changed, 14 insertions(+)
Commit successful!

Subir la versión y generar el changelog con cz bump

Aquí se ve por qué compensa el formato. Con dos commits feat y uno docs desde la versión 0.1.0, cz bump deduce que toca una versión menor, actualiza pyproject.toml, escribe el changelog, hace el commit y crea la etiqueta:

.venv/bin/cz bump --yes
bump: version 0.1.0 → 0.2.0
tag to create: 0.2.0
increment detected: MINOR

[main a6f6af4] bump: version 0.1.0 → 0.2.0
 2 files changed, 7 insertions(+), 1 deletion(-)
 create mode 100644 CHANGELOG.md

Done!

El CHANGELOG.md generado:

## 0.2.0 (2026-11-07)

### Feat

- añade la función resta
- **calculadora**: añade la función suma

El commit docs no aparece porque no cambia el comportamiento. --yes responde que sí a la pregunta de si es la primera etiqueta; prueba antes con cz bump --dry-run para ver qué haría sin tocar nada.

Que nadie se lo salte: valida los mensajes

Commitizen ayuda a quien lo usa, pero nada impide hacer git commit -m "arreglo". Para eso se valida el mensaje en un hook de Git, un script que Git ejecuta automáticamente antes de guardar el commit.

En Node, con commitlint y Husky

commitlint comprueba que el mensaje sigue Conventional Commits, y Husky instala el hook:

npm install -D @commitlint/cli @commitlint/config-conventional husky
echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.mjs
npx husky init
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

Ahora un mensaje sin formato se rechaza:

git commit -m "cambios varios"
⧗   --- input ---
cambios 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

husky - commit-msg script failed (code 1)

Y uno correcto pasa sin más:

git commit -m "chore: añade commitlint y husky"
[main 9782890] chore: añade commitlint y husky

En Python, con cz check

La versión de Python trae su propio validador:

cz check --message "cambios varios"
commit validation: failed!
please enter a commit message in the commitizen format.
commit "": "cambios varios
"pattern: (?s)(build|bump|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\(\S+\))?!?: ([^\n\r]+)((\n\n.*)|(\s*))?$
cz check --message "fix(calculadora): corrige el redondeo"
Commit validation: successful!

Para revisar varios commits de golpe, por ejemplo en la integración continua, usa cz check --rev-range origin/main..HEAD. Para hacerlo en cada commit, la documentación explica cómo configurarlo como hook con pre-commit.

Mensajes de commit escritos por un agente de IA

Cuando un agente de IA hace los commits, el mensaje lo escribe él, y si nadie le ha dicho el formato, puede usar cualquiera. Funciona como con una persona nueva en el equipo: primero le explicas la norma y después compruebas que la cumple, sin dar por hecho que la ha entendido.

  1. Pídeselo en sus instrucciones. Los agentes de código leen un fichero de instrucciones del proyecto, como AGENTS.md o CLAUDE.md (qué son y qué poner en cada uno). Basta con una regla corta:
## Commits

- Usa Conventional Commits 1.0.0: `<tipo>[ámbito]: descripción`.
- Tipos: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
- Marca los cambios incompatibles con `!` o con un pie `BREAKING CHANGE:`.
- Un commit por cambio. Si encaja en dos tipos, divídelo.
  1. Compruébalo con commitlint, no te fíes. Una instrucción es una petición, no una garantía. El hook commit-msg de Husky se ejecuta con cualquier git commit, lo lance una persona o un agente, y rechaza el mensaje que no cumpla. Como git commit --no-verify se lo salta, repite la comprobación en la integración continua. La guía de commitlint propone, en una pull request:
npx commitlint --from <commit-base> --to <commit-final> --verbose

En un repositorio de prueba con un commit «arreglos» detrás de uno correcto, falla y dice cuál es:

⧗   --- input ---
arreglos
✖   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

⧗   --- input ---
feat: añade a
✔   found 0 problems, 0 warnings

En GitHub Actions, <commit-base> y <commit-final> son ${{ github.event.pull_request.base.sha }} y ${{ github.event.pull_request.head.sha }}; en un push, la guía usa npx commitlint --last --verbose. [SIN EJECUTAR en GitHub Actions: solo se ha probado el comando en local.]

commitlint comprueba el formato, no el contenido: fix: arreglo pasa aunque no diga nada. Que la descripción cuente de verdad qué cambia sigue siendo cosa de quien revisa. Que las mismas normas valgan para el código de una persona y el de un agente es una de las ideas de la IA Limpia.

Lo que Commitizen no hace por ti

  • No escribe buenas descripciones. fix: arreglo cumple el formato y no dice nada. La descripción sigue siendo tuya: qué cambia, en imperativo y en pocas palabras.
  • No ordena tus commits. Si un commit mezcla una funcionalidad y una corrección, ningún tipo le encaja. Mejor commits pequeños, de una sola cosa. Y si una rama acumula varios «wip», puedes juntarlos antes de la PR con squash.
  • Se puede saltar. git commit --no-verify se salta los hooks. Si quieres una garantía, valida también en la integración continua.

¿Te sirve?

Encaja si:

  • Trabajas en equipo y cada persona escribe los commits a su manera.
  • Quieres generar el changelog o las versiones a partir de los commits.
  • Estás empezando con Conventional Commits y aún no te sabes los tipos de memoria.

Sobra si ya te sabes el formato: escribir git commit -m "fix: …" a mano es más rápido que responder al asistente, y con commitlint basta para que nadie se equivoque. Las preguntas del asistente están en inglés; los mensajes puedes escribirlos en español.

Alternativas

  • commitlint solo: sin asistente. Escribes el mensaje como siempre y el hook lo rechaza si no cumple el formato.
  • semantic-release (licencia MIT, v25 en noviembre de 2026): lee los commits en la integración continua, calcula la versión, genera las notas y publica el paquete sin intervención.
  • release-please (de Google, Apache 2.0, v17): a partir de los Conventional Commits abre una pull request con la nueva versión y el changelog; la versión se publica cuando la aceptas.

Las dos últimas no escriben commits: aprovechan los que ya siguen el formato, así que se combinan bien con Commitizen o commitlint.

Tu chuleta

Con Node:

Quiero… Comando
Instalar npm install -D commitizen
Configurar npx commitizen init cz-conventional-changelog --save-dev --save-exact
Hacer un commit npx cz o npm run commit
Repetir un commit fallido npx cz --retry
Validar mensajes npx commitlint --from HEAD~1 --to HEAD
Subir versión y changelog Otra herramienta

Con Python:

Quiero… Comando
Instalar pip install commitizen
Configurar cz init
Hacer un commit cz commit o cz c
Repetir un commit fallido cz commit --retry
Validar mensajes cz check --rev-range HEAD~1..HEAD
Subir versión y changelog cz bump

Commitizen encaja bien con un modelo de ramas como Git Flow: ramas con nombre claro y commits con mensaje claro. Y si prefieres ver el historial en un cliente gráfico, GitKraken lo muestra de forma visual.

Fuentes

Comprobado el 7 de noviembre de 2026 en la documentación oficial, y ampliado el 14 de noviembre:

  • Conventional Commits 1.0.0 (leída el 14 de noviembre de 2026): estructura, reglas del ámbito, el cuerpo y los pies, tipos feat y fix, tipos de ejemplo de @commitlint/config-conventional, revert en las preguntas frecuentes, ! y BREAKING CHANGE, mayúsculas, relación con SemVer y los ejemplos.
  • commitizen/cz-cli (README): instalación, commitizen init, script commit, git cz y --retry. Versiones en npm: commitizen 4.3.2 y cz-conventional-changelog 3.3.0.
  • commitizen-tools/commitizen y su documentación: instalación, requisito de Python 3.10+, cz init, cz commit, cz check y cz bump. Versión 4.19.3 en PyPI.
  • commitlint: Getting started, Local setup y CI setup (esta, leída el 14 de noviembre de 2026): instalación, configuración, hook commit-msg con Husky y comprobación en la integración continua. Versiones: @commitlint/cli y @commitlint/config-conventional 21.2.4, y Husky 9.1.7.
  • Alternativas, comprobadas en sus repositorios de GitHub el 7 de noviembre de 2026: semantic-release (v25.0.9, MIT) y release-please (v17.11.2, Apache 2.0). No se han ejecutado.

Todas las salidas del artículo se han ejecutado en repositorios de prueba con Node 24.21.0, npm (incluido en Node 24), Python 3.14.4 y Git 2.53.0 en Linux. La instalación de Python se hizo en un entorno virtual. Los ejemplos de Conventional Commits y los rangos de commits se validaron el 14 de noviembre de 2026 con @commitlint/cli 21.2.4 y @commitlint/config-conventional 21.2.4, Node 24.21.0 y Git 2.53.0. cz commit --retry, la configuración con pre-commit y el flujo de GitHub Actions se han comprobado en la documentación, no ejecutado.