Lenguaje natural para los mensajes de commit en Git

Acabas de corregir un bug. Escribes git commit -m "fix" y haces push. Seis meses después, alguien de tu equipo —o tú mismo— revisa el historial de commits para entender qué cambió y por qué. No encuentra nada útil. Solo «fix».

Este es el error más común que cometen quienes empiezan a usar Git, y se puede evitar por completo.

Los mensajes de commit en Git no son solo un registro administrativo. Son la historia de tu código, escrita una instantánea a la vez. Cuando aprendes a escribirlos bien, conviertes git log de una lista de etiquetas crípticas en una narrativa que explica cada decisión que tomó tu equipo.

Esta guía te muestra cómo escribir mensajes de commit en lenguaje natural, pensado para las personas, y cómo se relaciona esto con las convenciones de GitHub que los equipos usan todos los días.

Por qué los mensajes de commit se escriben para personas

Antes de entrar en la sintaxis, entiende el propósito: los mensajes de commit existen para las personas, no para las máquinas.

Cuando ejecutas git log, ves una línea de tiempo de los cambios. Cuando ejecutas git bisect para encontrar qué commit introdujo un bug, lees esos mensajes para orientarte. Cuando alguien revisa un pull request, el historial de commits le muestra cómo abordaste el problema, no solo cómo se ve el diff final.

Un commit como fix null pointer in data preprocessing se entiende en cinco segundos. Uno como fix stuff te obliga a abrir el diff y leer el código. Multiplica eso por 200 commits en un sprint y la diferencia de productividad se vuelve considerable.

El modo imperativo: el lenguaje natural de Git

La convención más importante para los mensajes de commit en Git es el modo imperativo: escribir como si estuvieras dando una instrucción.

En lugar de:

• «Corregí el bug de inicio de sesión» ❌
• «Corrige el bug de inicio de sesión» ❌
• «Yo corregí el bug de inicio de sesión» ❌

Escribe:

• «Corregir el bug de inicio de sesión» ✅

Un truco mental útil: tu mensaje de commit debe completar la frase «Si se aplica, este commit permitirá…»

Esta convención coincide con la que usa Git. Ejecuta git merge, git revert o git cherry-pick y observa los mensajes que genera Git: “Merge branch ‘feature/login’”, “Revert ‘Add user authentication’”. Siempre en imperativo.

Las tres partes de un mensaje de commit

Un commit bien estructurado tiene hasta tres secciones:

<subject line>

<body>

<footer>

Línea de asunto (obligatoria)

Una línea de 50 caracteres o menos, en modo imperativo, con la primera letra en mayúscula y sin punto final.

Fix null pointer exception in user profile loading

GitHub trunca todo lo que supere los 72 caracteres con puntos suspensivos, así que, si pasas de 50, no excedas los 72.

Cuerpo (opcional)

Después del asunto, deja una línea en blanco y escribe un párrafo que explique por qué se hizo el cambio. Limita las líneas a 72 caracteres. Concéntrate en el contexto, no en la implementación: el código muestra qué cambió; el cuerpo explica por qué.

Fix null pointer exception in user profile loading

The profile endpoint was returning null for users who registered
before the avatar field was added to the database schema.
Added a null check and a fallback to the default avatar URL.

Pie (opcional)

Se usa para metadatos: cerrar issues, marcar cambios incompatibles y hacer referencia a commits relacionados.

Fix null pointer exception in user profile loading

The profile endpoint was returning null for users who registered
before the avatar field was added to the database schema.
Added a null check and a fallback to the default avatar URL.

Fixes #214

En GitHub, la frase Fixes #214 cierra automáticamente el issue #214 cuando el commit llega a la rama predeterminada. GitHub también reconoce Closes, Resolves y Refs de la misma manera.

Conventional Commits: estructura para el lenguaje natural

Muchos equipos usan Conventional Commits, una especificación que agrega un prefijo corto de tipo a la línea de asunto. Se ve así:

<type>(<optional scope>): <description>

El tipo indica a quienes leen el mensaje —y a las herramientas automatizadas— qué clase de cambio es:

El scope opcional es un sustantivo entre paréntesis que delimita el contexto:

feat(auth): add OAuth2 login with GitHub
fix(cart): prevent duplicate items on rapid clicks
docs(api): document rate limiting headers

Cambios incompatibles

Si tu cambio rompe la compatibilidad con versiones anteriores, márcalo con un signo de exclamación o en el pie:

feat!: remove support for Node 14

BREAKING CHANGE: Node 14 reached end-of-life. Minimum required version is Node 18.

Esta notación permite generar changelogs automáticamente. Herramientas como semantic-release leen tus commits y determinan los incrementos de versión de forma automática: fix: → patch (1.0.1), feat: → minor (1.1.0), BREAKING CHANGE → major (2.0.0).

Ejemplos reales del día a día

Así podría verse una semana de commits para una persona que desarrolla una funcionalidad:

Lunes: crear una rama para una funcionalidad

git checkout -b feature/user-notifications

git commit -m "feat(notifications): scaffold notification model and migration"
git commit -m "feat(notifications): add API endpoint to fetch unread notifications"

Martes: conectar el frontend

git commit -m "feat(notifications): add notification bell icon to header"
git commit -m "feat(notifications): display unread count badge on bell"
git commit -m "style(notifications): align badge position with design spec"

Miércoles: detectar un bug durante las pruebas

git commit -m "fix(notifications): prevent duplicate notifications on page refresh"
git commit -m "test(notifications): add integration tests for notification API"

Jueves: recibir comentarios en la revisión de código

git commit -m "refactor(notifications): extract badge component to ui/NotificationBadge"
git commit -m "docs(notifications): add JSDoc comments to notification service"

Viernes: cerrar el trabajo

git commit -m "chore: update changelog for notifications feature"
git commit -m "fix(notifications): resolve edge case when user has zero notifications

The API was returning 404 instead of an empty array when a user had no
notifications. Changed response to return 200 with an empty array.

Fixes #312"

Cada uno de estos commits representa un único cambio lógico. Si algo falla, puedes identificar exactamente qué commit lo introdujo. Si necesitas revertir un paso, puedes hacerlo sin tocar trabajo que no está relacionado.

Qué sale mal sin buenos commits

Los historiales de commits reales de proyectos que no siguen estas convenciones suelen verse así:

wip
more stuff
fix
asdfsdf
working now
final
final v2
FINAL FINAL

El daño no es evidente hasta que necesitas:

• Depurar una regresión: no puedes usar git bisect de forma efectiva cuando los commits mezclan cambios sin relación
• Generar un changelog: las herramientas automatizadas producen resultados inútiles
• Incorporar a alguien al equipo: esa persona no tiene forma de entender la evolución del proyecto
• Revertir cambios de forma segura: revertir «final v2» podría deshacer tres funcionalidades sin relación a la vez

Reglas prácticas para empezar hoy

Si adoptar Conventional Commits de inmediato te parece demasiado, comienza con estas tres reglas:

1. Un cambio lógico por commit. No combines la corrección de un bug y una nueva funcionalidad en el mismo commit. Si tu diff toca tres archivos sin relación entre sí, divídelo en tres commits.

2. Responde «qué» en el asunto y «por qué» en el cuerpo. El diff ya muestra qué cambió. Usa el cuerpo para explicar la decisión detrás del cambio.

3. Escribe para la persona que leerá el mensaje dentro de 6 meses. Esa persona podrías ser tú. ¿Tendría sentido el mensaje sin abrir el diff?

Herramientas de IA que te ayudan a escribir mejores commits

Escribir buenos mensajes de commit es una habilidad que puedes aprender, pero las herramientas de IA pueden acelerar el proceso mientras desarrollas el hábito:

• AICommits — CLI que lee el diff de tus cambios preparados y genera un mensaje de commit. Admite formatos simples, conventional commits y gitmoji.
• AI-Commit — Integración como hook de Git; genera mensajes automáticamente para cada commit preparado. Admite modelos locales mediante Ollama para proteger la privacidad.
• GitKraken AI — Herramienta con interfaz gráfica que escribe mensajes de commit, descripciones de PR e incluso resuelve conflictos de merge con contexto de IA.
• Windsurf AI Commit Messages — Integración con el IDE que genera mensajes de commit a partir de los cambios preparados con un solo clic.
• Claude Code — Ejecutar git diff --staged y pedirle a Claude que redacte un mensaje de conventional commit es una opción rápida y flexible si ya lo usas en tu flujo de trabajo.

Estas herramientas son un apoyo, no un sustituto de tu criterio. Lee y edita las sugerencias antes de aceptarlas: el objetivo es desarrollar tu propio juicio sobre lo que hace útil a un mensaje.

Cómo lee GitHub tus mensajes

GitHub muestra los mensajes de commit en varios lugares, y saberlo cambia la forma en que los escribes:

• Línea de tiempo del pull request — Cada commit aparece con su línea de asunto. Un tipo de conventional commit claro les indica de inmediato a quienes revisan qué clase de cambio están viendo.
• Cierre de issues — Fixes #123 en el asunto o el cuerpo cierra el issue automáticamente cuando el cambio se integra en la rama predeterminada.
• Vista de blame — git blame muestra la línea de asunto junto a cada línea de código. Los asuntos breves y descriptivos hacen que la vista de blame sea mucho más útil.
• Releases — Las notas de release generadas automáticamente por GitHub agrupan los commits por tipo si usas conventional commits de forma consistente.
• Búsqueda — GitHub indexa los mensajes de commit. Un commit con un buen mensaje se puede encontrar meses después.

Configurar Commitlint (opcional, recomendado para equipos)

Una vez que te sientas cómodo escribiendo conventional commits manualmente, puedes hacer que se validen automáticamente con commitlint y Husky:

npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
npx husky init
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
echo "{ \"extends\": [\"@commitlint/config-conventional\"] }" > commitlint.config.json

Ahora Git rechazará cualquier commit que no siga la convención antes de que se cree. El mensaje de error te indica exactamente qué está mal:

⧗   input: fix thing
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

Esto convierte las buenas prácticas en un hábito para todo el equipo.

El modelo mental

Los mensajes de commit son una conversación con el futuro. Cada fix:, feat: y refactor: es una frase en una historia que escribes en colaboración con tu equipo y con tu yo del futuro.

Las convenciones no son reglas arbitrarias. El modo imperativo coincide con el lenguaje del propio Git. El límite de 50 caracteres permite que el mensaje quepa en la salida de la terminal sin saltos de línea. Los prefijos de tipo permiten automatizar los changelogs y los incrementos de versión. Cada convención existe porque resuelve un problema real que los equipos encontraron al trabajar a mayor escala.

Empieza poco a poco: elige tres reglas, aplícalas durante una semana y lee tu propio git log al final. Verás la diferencia de inmediato.

Fuentes: Conventional Commits v1.0.0 · Cómo escribir un mensaje de commit en Git — cbeams · Buenas prácticas para los mensajes de commit en Git — DataCamp · 8 buenas prácticas para los mensajes de commit en Git en 2025 — PullNotifier · Haz commits como profesional: guía de Conventional Commits para principiantes — DEV Community · Dominar Conventional Commits — DEV Community · AICommits — GitHub · Funciones de GitKraken AI · Mensajes de commit con Windsurf AI · Mensajes de commit — The Odin Project