conventional commits · guía rápida

Mensajes de commit con sentido

Un pequeño cambio en el formato de tus mensajes de commit puede transformar la legibilidad del historial de tu proyecto.

Generador de Commits

Interactivo
git commit -m "feat: "

Formato general

estructura

git commit -m"<tipo>(<ámbito opcional>): <descripción>" \
  -m"<cuerpo opcional>" \
  -m"<pie de página opcional>"

commit inicial

chore: init

commit de merge

Merge branch '<nombre-rama>'

commit de revert

Revert "<mensaje original>"

Tipos de commit

10 tipos
⌕
feat
Añade, ajusta o elimina una funcionalidad del API o la UI
fix
Corrige un bug en el API o la UI
refactor
Reescribe o restructura código sin alterar el comportamiento observable
perf
Refactor enfocado específicamente en mejorar el rendimiento
style
Estilo de código: espacios, formato, punto y coma omitidos… sin cambio de lógica
test
Añade tests que faltan o corrige los existentes
docs
Cambios exclusivamente en la documentación
build
Afecta al sistema de build, herramientas, dependencias o versión del proyecto
ops
Infraestructura, scripts de despliegue, CI/CD, backups, monitoreo o recuperación
chore
Tareas de mantenimiento: commit inicial, modificar .gitignore, etc.

Ámbito (scope)

opcional
◆ El ámbito aporta contexto adicional sobre la zona del código afectada
◆ Es una parte opcional del mensaje
◆ Los ámbitos permitidos varían por proyecto y suelen definirse en las guías del equipo
◇ No uses identificadores de issues como ámbito — p.ej. #123

Breaking changes

⚠

Cambios incompatibles

Un commit que introduce un cambio incompatible debe marcarse con ! antes del : en el asunto.

Ejemplo: feat(api)!: eliminar endpoint de estado

El pie de página debe incluir: BREAKING CHANGE: <descripción>

🔥

Hotfix

Una corrección urgente aplicada directamente sobre producción sin pasar por el flujo habitual. Usa fix como tipo. Si rompe compatibilidad, añade !.

fix(auth): corregir bypass de autenticación en /admin

BREAKING CHANGE: la sesión ahora expira en 30 min por defecto.

Si tu equipo usa ramas dedicadas (hotfix/nombre), haz el merge con el mensaje estándar de git y el commit de fix dentro de esa rama.

Trailers (Metadatos)

◆ Se añaden al final del commit, tras una línea vacía.
◆ Cerrar tickets: Resolves #123 o Fixes JIRA-456.
◆ Autoría compartida: Co-authored-by: Nombre <email>.
◆ Referencias: Refs: #890 para enlazar a un ticket sin cerrarlo automáticamente.

Redactar la descripción

◆ La descripción es obligatoria
◆ Usa imperativo en presente: "change" no "changed" ni "changes"
◆ Piensa: «Este commit va a…» o «Este commit debería…»
◇ No empieces la descripción con mayúscula
◇ No termines con punto — .

Versionado semántico

Si el commit contiene… Incrementa Ejemplo
Breaking changes — ! o BREAKING CHANGE MAJOR 1.0.0 → 2.0.0
Cambios de API/UI — feat o fix MINOR 1.0.0 → 1.1.0
Cualquier otro tipo PATCH 1.0.0 → 1.0.1

¿Qué tipo uso?

¿Corrige un bug?
sí → fix
no ↓
¿Cambia funcionalidad o UI?
sí → feat
no ↓
¿Mejora de rendimiento?
sí → perf
no ↓
¿Restructura código sin cambiar comportamiento?
sí → refactor
no ↓
¿Solo formato o estilo de código?
sí → style
no ↓
¿Añade o corrige tests?
sí → test
no ↓
¿Solo documentación?
sí → docs
no ↓
¿Afecta al build, dependencias o versión?
sí → build
no ↓
¿Afecta a infra, CI/CD o despliegue?
sí → ops
no ↓
Mantenimiento o tarea sin código de producto
→ chore

Ejemplos

haz clic en cualquier ejemplo para copiarlo

feat feat: añadir notificaciones por email en nuevos mensajes directos copiar
feat feat(carrito): añadir el botón de compra exprés copiar
feat! feat!: eliminar endpoint de listado de tickets
refs JIRA-1337 · BREAKING CHANGE: el endpoint ya no lista todas las entidades copiar
fix fix(carrito): evitar hacer pedido con carrito vacío copiar
fix fix(api): corregir cálculo incorrecto del checksum del body copiar
perf perf: reducir uso de memoria en visitantes únicos usando HyperLogLog copiar
refactor refactor: implementar cálculo de Fibonacci como recursión copiar
style style: eliminar línea vacía sobrante copiar
test test(auth): añadir tests unitarios para el middleware de sesión copiar
docs docs(readme): añadir ejemplos de uso del CLI copiar
build build: actualizar dependencias copiar
build build(release): bump version to 1.0.0 copiar
ops ops(ci): añadir paso de lint al pipeline de GitHub Actions copiar