El módulo anterior terminó con un diagnóstico incómodo: el equipo de gestor-tareas tiene ya un proceso impecable —forks, pull requests, revisiones, ramas protegidas, integración continua— y aun así puede acabar con un historial que nadie sea capaz de leer. Empezamos a corregirlo por el punto más cotidiano y más descuidado de todos: el mensaje de confirmación.

Esta lección salda por fin dos deudas del curso. En la lección 02-04 aprendimos a confirmar cambios con git commit -m y dijimos que las convenciones de mensajes llegarían aquí. En la lección 06-01 escribimos un hook commit-msg que exigía un ticket con formato GT-NNN, pero validamos una convención que aún no habíamos explicado. Y en la 07-06 validamos esa misma convención en el CI. Es el momento de explicar de dónde sale todo eso.

Conviene entender la magnitud del asunto antes de empezar. Un desarrollador escribe entre cinco y veinte mensajes de confirmación al día. Son el único texto en prosa que produce el proyecto de forma sistemática, el único que sobrevive a los refactores, y el único que estará ahí cuando el autor original ya no esté en la empresa. El código dice qué hace el programa; el historial es el único sitio donde puede quedar escrito por qué lo hace así.

1. Para quién se escribe un mensaje de confirmación
2. El porqué importa más que el qué
3. Anatomía de un buen mensaje
4. La línea de asunto: las siete reglas
5. El cuerpo: motivación y contexto
6. El pie: referencias, tickets y coautoría
7. Mensajes malos y su versión buena
8. Conventional Commits
9. BREAKING CHANGE y la versión derivada
10. Plantillas con commit.template
11. Escribir en el editor, no con -m
12. Hacer cumplir la convención: hook y CI
13. El idioma del mensaje

Hay una respuesta intuitiva y equivocada: "para mí, para acordarme de lo que hice". Es equivocada porque tú, dentro de una semana, ya no necesitarás el mensaje: tendrás el contexto fresco. El mensaje existe para tres lectores que no lo tienen.

Lector 1: tu yo de dentro de dos años. No recuerda nada del contexto. No recuerda la reunión donde se decidió aquello, ni el cliente que se quejó, ni la limitación del navegador que obligó a hacer una cosa rara. El commit es lo único que queda.

Lector 2: quien ejecute git blame sobre una línea rara. Es el caso más frecuente y el más valioso. Alguien encuentra en app.js una condición absurda:

Su primer impulso será borrarla. En la lección 06-03 vimos que git blame responde qué commit introdujo esa línea. Si ese commit dice arreglos, el lector borrará la condición y reintroducirá el fallo. Si dice Evitar el filtro por fecha en Safari 14: su Intl.DateTimeFormat devuelve la zona horaria en un formato que rompe el parseo, no la borrará. La calidad del mensaje decide si el fallo vuelve.

Lector 3: quien revise tu pull request. En la lección 07-02 vimos que revisar bien exige entender la intención antes que el diff. Una PR con commits atómicos y bien descritos se revisa commit a commit y en la mitad de tiempo. Una PR con ocho commits llamados wip, wip2 y ahora sí obliga al revisor a leer un diff gigante sin ninguna guía.

Hay un cuarto lector que además es una máquina: las herramientas que generan changelogs, deducen versiones y filtran el historial. De eso trata el apartado 8.

Esta es la idea central de toda la lección, y la que más cuesta interiorizar.

El diff ya dice el qué. Está ahí, completo, exacto y para siempre. git show te lo enseña con precisión de carácter. Un mensaje que dice Cambia el color del botón a azul cuando el diff dice - color: #c00; / + color: #06c; es redundante: no aporta ni un bit de información nueva.

Lo que el diff no puede decir nunca:

Compara estos dos mensajes sobre exactamente el mismo diff de gestor-tareas:

El primero es información que ya estaba en el diff. El segundo contiene cuatro hechos que no están en ninguna otra parte del repositorio: de dónde venía el valor viejo, qué fallo concreto provocaba, cómo se eligió el nuevo y por qué no es mayor. Dentro de dos años, cuando alguien proponga bajarlo otra vez "porque 30 segundos es una barbaridad", ese mensaje es la respuesta.

La regla: si tu mensaje se puede deducir leyendo el diff, todavía no has escrito el mensaje.

Git no impone ningún formato, pero sí trata el texto de forma estructurada, y casi todas las herramientas del ecosistema asumen la misma convención. La estructura canónica tiene tres partes:

La línea en blanco entre el asunto y el cuerpo no es estética: es sintaxis. Git usa la primera línea como asunto en git log --oneline, en %s de --pretty, en el asunto de los correos de git format-patch y en el título por defecto de una pull request. Si te la saltas, el mensaje entero se convierte en asunto:

Todo el texto pegado, y el --oneline inservible.

No es una cifra mágica arbitraria: es el límite práctico para que git log --oneline, la lista de commits de una plataforma y el git shortlog quepan en una línea sin truncarse. Las plataformas de alojamiento cortan visualmente alrededor de los 72 caracteres, y GitHub avisa a partir de 50.

Si no cabe en 50 caracteres, casi siempre es una de estas dos cosas: el commit hace demasiadas cosas (lo veremos en la lección 08-02) o estás metiendo en el asunto lo que va en el cuerpo.

Escribe como si dieras una orden al repositorio. La prueba infalible es completar esta frase:

"Si se aplica, este commit _______"

No es capricho: el propio Git escribe así. Merge branch 'x', Revert "...", Initial commit. Si tus mensajes usan otro tiempo verbal, el historial mezcla dos voces.

Es un título, no una frase. Y en 50 caracteres, un carácter cuenta.

Salvo que uses Conventional Commits (apartado 8), donde la convención habitual es minúscula tras los dos puntos. Elige una y sé coherente.

Corrige el error no dice nada. Corrige el borrado de tareas con adjunto sí.

Cambia app.js es inútil: git log --stat ya lo dice. El ámbito, si hace falta, va con la sintaxis de Conventional Commits.

Añade el filtro por etiqueta y corrige el margen del pie describe dos cambios independientes. La lección 08-02 desarrolla esta idea a fondo.

El cuerpo es opcional para un cambio trivial y obligatorio para cualquier cambio no obvio. Se envuelve manualmente a 72 columnas por una razón muy concreta: git log indenta el cuerpo con cuatro espacios, así que 72 + 4 = 76, y cabe en un terminal de 80 columnas sin que Git reenvuelva el texto (no lo hace: Git nunca reformatea tu mensaje).

Un cuerpo útil responde a estas preguntas, no necesariamente todas:

1. ¿Cuál era el problema o la necesidad? El estado anterior y por qué no valía.
2. ¿Por qué esta solución? Y sobre todo, qué alternativas se descartaron.
3. ¿Qué efectos colaterales tiene? Rendimiento, compatibilidad, migraciones.
4. ¿Qué NO hace este cambio? Delimitar es tan útil como describir.
5. ¿Qué hay que saber para revisarlo? Un enlace, una medición, un comando de reproducción.

Ejemplo completo, sobre un cambio real de gestor-tareas que hizo Carla:

Fíjate en lo que aporta y que no está en el diff: la medición concreta, la alternativa descartada con su motivo, la fecha de caducidad del código de migración y el límite explícito del cambio.

El pie (trailer en la terminología de Git) es un bloque de líneas Clave: valor al final del mensaje, separado por una línea en blanco. Git lo entiende de forma nativa a través de git interpret-trailers, y las plataformas lo interpretan también.

La coautoría merece una mención especial, porque resuelve un problema real del equipo. Cuando Ana y Bruno programan en pareja, el commit lo firma solo quien lo escribe, y git blame (lección 06-03) atribuye todo a esa persona. Con el trailer, las plataformas reconocen a los dos:

Detalle importante: la línea Co-authored-by debe ir al final, precedida de una línea en blanco, y el correo debe ser el que la persona tiene registrada en la plataforma. Si no, el nombre aparece pero no se enlaza a la cuenta.

Puedes automatizarlo con git interpret-trailers:

Esta tabla recoge mensajes reales del historial temprano de gestor-tareas, cuando el equipo todavía no tenía convención, junto a lo que deberían haber sido.

Fíjate en el patrón: los mensajes malos casi siempre son cortos por prisa o dependientes de un contexto que se evapora ("ayer", "lo que comentó Carla", "ahora sí").

Hasta aquí hemos hablado de prosa para humanos. Conventional Commits es una convención que además hace el asunto legible por máquinas, sin perder legibilidad humana. Es la que usa el hook commit-msg que escribimos en la lección 06-01.

El formato:

Ejemplos sobre gestor-tareas:

El ámbito entre paréntesis es libre y lo define cada proyecto. En gestor-tareas el equipo acordó: filtros, sync, lista, ui, css, readme, deps, ci. Un ámbito estable convierte git log --oneline | grep '(sync)' en una consulta útil.

1. Filtrar el historial es trivial. git log --oneline --grep '^feat' te da todas las funcionalidades nuevas.
2. Changelog automático. Herramientas como git-cliff, standard-version o semantic-release agrupan los commits por tipo y generan CHANGELOG.md sin intervención humana.
3. Versión SemVer derivada. Esto enlaza directamente con la lección 05-05: allí acordamos MAJOR.MINOR.PATCH y etiquetas anotadas, pero decidíamos el número a mano. Con Conventional Commits, el número se deduce del historial.
4. Disciplina de granularidad. Si no sabes qué tipo poner, casi siempre es porque el commit hace más de una cosa.

Supón que desde v1.4.0 el historial de gestor-tareas contiene:

Hay un feat y ningún BREAKING CHANGE, así que la siguiente versión es v1.5.0. Si solo hubiera habido fix, sería v1.4.1. Si no hubiera habido ni feat ni fix, no habría versión que publicar.

Una ruptura de compatibilidad es un cambio que obliga a quien consume tu código a hacer algo. En SemVer sube el número MAJOR, y es el único caso en que la deducción automática no puede fallar sin consecuencias graves.

Se marca de dos formas equivalentes:

Forma 1 — con ! tras el tipo o el ámbito:

Forma 2 — con un trailer en el pie (permite explicar la migración):

La segunda es netamente mejor: el mensaje incluye la guía de migración, y las herramientas de changelog la copian tal cual a la sección de rupturas. Usa las dos a la vez si quieres que el ! sea visible en --oneline.

Cuidado con el aplastado. Si integras las pull requests con squash merge (lo veremos a fondo en la lección 08-02), el mensaje que cuenta para la deducción es el del commit aplastado, no los de la rama. Un BREAKING CHANGE escondido en el tercer commit de una rama desaparece si el título del squash es feat: mejoras varias. Es un argumento fuerte para revisar el título del squash antes de fusionar.

La forma más barata de que todo un equipo escriba mensajes mejores es poner el recordatorio delante de sus ojos en el momento exacto. Eso hace commit.template: un fichero cuyo contenido precarga el editor cada vez que confirmas.

Crea el fichero en el repositorio, para que Ana, Bruno y Carla usen el mismo:

Contenido de .gitmensaje:

Y se activa:

Tres detalles que importan:

• Las líneas que empiezan por # se descartan al guardar, así que las instrucciones no llegan al historial. El carácter de comentario se puede cambiar con core.commentChar si necesitas un # literal (por ejemplo, para escribir #123).
• commit.template no se versiona solo. El fichero .gitmensaje sí está en el repositorio, pero la configuración que lo activa vive en .git/config, que como vimos en la lección 01-05 es local. Documenta el git config --local commit.template .gitmensaje en el README.md, o añádelo al script de arranque del proyecto.
• La plantilla no se aplica con -m. Solo cuando Git abre el editor. Lo cual nos lleva al apartado siguiente.

git commit -m "..." es cómodo y por eso es el hábito por defecto de todo el mundo. También es la causa estructural de los mensajes malos, por tres motivos:

1. La comilla del terminal te presiona a ser breve. Escribir un párrafo entre comillas en la shell es incómodo, así que no lo escribes.
2. No ves el contexto. El editor te muestra, comentada, la lista de ficheros modificados. Muchas veces ahí descubres que has preparado un fichero que no querías.
3. No hay revisión. Con -m pulsas Intro y ya está. En el editor lees lo que has escrito antes de guardar.

Compara:

Al ejecutar git commit a secas, el editor (core.editor, lección 01-06) se abre con la plantilla y con esto debajo:

Y con -v ves además el diff completo dentro del editor, que es la mejor ayuda posible para escribir el porqué:

Actívalo siempre:

Cuándo sí usar -m: para commits verdaderamente triviales (docs: corrige una errata), en scripts, y para los --fixup de la lección 05-02, que van a desaparecer en el rebase.

Si el mensaje es largo y prefieres no depender del editor, hay una alternativa limpia:

Una convención que no se comprueba se erosiona en tres semanas. En la lección 06-01 escribimos un hook commit-msg; ahora que la convención está explicada, aquí está la versión completa y comentada.

Recuerda de la lección 06-01 los tres requisitos para que funcione:

Y recuerda también la advertencia, que la lección 07-06 convirtió en principio: un hook de cliente no es un control. git commit --no-verify lo salta. Por eso la misma comprobación tiene que estar en el CI, donde nadie manda:

Un matiz importante que se olvida siempre: si tu política de integración es squash merge, validar los commits individuales de la rama tiene poco sentido —van a desaparecer— y lo que hay que validar es el título de la pull request, que será el asunto del commit aplastado. Cuál de las dos políticas conviene es exactamente la pregunta que resuelve la lección siguiente.

Es una discusión que aparece en todos los equipos y que tiene una única respuesta correcta: elige uno y respétalo.

Lo verdaderamente malo no es elegir mal: es no elegir. Un historial donde se alternan feat: add tag filter y feat: añade el filtro por etiqueta es más difícil de buscar (--grep deja de funcionar), más difícil de leer y transmite desidia.

En gestor-tareas el equipo acordó, y lo escribió en el README.md: tipo y ámbito en inglés (porque son palabras clave de la convención y las entienden las herramientas), descripción, cuerpo y trailers en español (porque es la lengua de trabajo de los cuatro y permite explicar el porqué sin empobrecerlo). Es un compromiso muy común y funciona bien.

Diego, el colaborador externo, se encontró la decisión escrita en el README.md de su fork antes de abrir su primera pull request. Ese es el sitio donde va: en el repositorio, no en la cabeza de nadie.

Error 1: describir el qué en lugar del porqué. Es el error dominante. Cambia el valor a 30 no aporta nada; El valor de 5 s venía del prototipo y ya no cubre el envío de adjuntos lo aporta todo. Prueba de fuego: si el mensaje se deduce del diff, todavía no has escrito el mensaje.

Error 2: olvidar la línea en blanco tras el asunto. Rompe --oneline, los títulos de PR y el %s de --pretty. Es sintaxis, no estilo.

Error 3: contexto efímero. "Como hablamos ayer", "lo que pidió Carla", "según el correo de esta mañana". Dentro de seis meses no significan nada. Escribe el contenido, no el puntero.

Error 4: enlazar a un sistema externo en lugar de resumir. Ver GT-134 te deja vendido el día que se migre el gestor de tickets o alguien lo consulte sin acceso. Referencia el ticket además de resumir, nunca en lugar de.

Error 5: mensajes de proceso. Cambios pedidos en la revisión, Ahora sí, Otro intento. Describen tu jornada, no el código. Aplástalos con --fixup y rebase -i --autosquash (lección 05-02) antes de publicar.

Error 6: creer que se puede arreglar después. El mensaje de un commit publicado solo se cambia reescribiendo el historial, y eso choca con la regla de oro de la lección 05-01. Un mensaje malo publicado es permanente. (Si aún no lo has enviado, git commit --amend lo arregla; la lección 09-02 desarrolla los casos de deshacer.)

Error 7: aplicar Conventional Commits a medias. Media docena de commits con feat: y el resto con prosa libre produce lo peor de ambos mundos: la disciplina de la convención sin ninguno de sus beneficios automáticos, porque el changelog sale incompleto.

Consejo 1: escribe el mensaje antes que el código. Suena raro y funciona. Si no eres capaz de resumir en una línea lo que vas a hacer, el cambio todavía no está delimitado.

Consejo 2: activa commit.verbose hoy mismo. git config --global commit.verbose true pone el diff dentro del editor. Es la mejora de calidad más barata de todo el módulo.

Consejo 3: lee tu propio historial una vez al mes. git log --oneline -30. Si no entiendes tus commits de hace tres semanas, tienes un problema que crecerá.

Consejo 4: usa git shortlog -sn --no-merges y git log --oneline --grep. Si tus consultas al historial no devuelven nada útil, es señal de que los mensajes no lo son.

Consejo 5: en las revisiones, revisa también los mensajes. Es legítimo pedir en una PR "reescribe el mensaje del segundo commit". Es la única forma de que la convención sobreviva.

Consejo 6: la plantilla en el repositorio, no en tu $HOME. Así Diego la tiene al clonar el fork.

Para cada uno de estos mensajes reales del historial temprano de gestor-tareas, escribe la versión buena: asunto en imperativo de ≤50 caracteres y, cuando el caso lo pida, un cuerpo. Inventa el contexto verosímil que falte.

1. fix css
2. actualiza app.js
3. Añadido el buscador y arreglado el margen del pie de página
4. Ahora sí funciona
5. Sube la dependencia

En un repositorio de pruebas:

1. Crea un fichero de plantilla .gitmensaje con la estructura de Conventional Commits y actívalo con commit.template a nivel local.
2. Activa commit.verbose.
3. Instala el hook commit-msg del apartado 12 en .githooks/ y configura core.hooksPath.
4. Comprueba que rechaza arreglos varios, que rechaza feat: añade el filtro (falta el ticket) y que acepta feat(filtros): añade el filtro por etiqueta con Refs: GT-134 en el cuerpo.
5. Demuestra que --no-verify lo esquiva y explica qué barrera lo detendría.

Dado este historial desde la etiqueta v2.3.1 de gestor-tareas:

1. ¿Qué versión SemVer corresponde publicar y por qué?
2. Escribe el mensaje completo del commit 9182b3c con su trailer BREAKING CHANGE y su guía de migración.
3. Escribe el comando de git log que extraería solo los feat de ese rango.
4. Si el equipo integrara esta rama con squash merge y el título del squash fuera feat: mejoras de sincronización, ¿qué versión deduciría la herramienta? ¿Qué problema revela eso?

Solución 1:

Solución 2:

--no-verify es una opción del cliente: no viaja por la red y el servidor no se entera de que se usó. La barrera que sí lo detiene es la del CI (apartado 12) declarada como comprobación obligatoria en una rama protegida, tal como vimos en la lección 07-06. El hook local es una ayuda para el desarrollador; la rama protegida es el control.

Solución 3:

1. Corresponde v3.0.0. La presencia de feat(api)! marca una ruptura de compatibilidad, y en SemVer eso sube el número MAJOR y pone MINOR y PATCH a cero, independientemente de que haya además dos feat y un fix. La ruptura manda siempre.

2.

3.

Y para localizar específicamente las rupturas, que pueden estar en el cuerpo:

4. La herramienta deduciría v2.4.0 (un feat, ninguna ruptura visible), porque el BREAKING CHANGE estaba en el cuerpo de un commit que el aplastado hizo desaparecer. El resultado es grave: se publica como MINOR un cambio que rompe a todos los consumidores, y estos actualizan confiando en la garantía de compatibilidad de SemVer.

Lo que revela es que la política de integración no es una decisión estética: cambia qué mensajes sobreviven en la línea principal y, por tanto, qué información queda disponible para las personas y para las herramientas. Si se aplasta, el título del squash debe validarse con el mismo rigor que un commit, y los trailers relevantes deben propagarse a él. Esa política es justo el tema de la lección siguiente.

Lo esencial de esta lección:

• Un mensaje de confirmación se escribe para tres lectores sin contexto: tu yo de dentro de dos años, quien haga blame sobre una línea rara y quien revise tu PR. Y para un cuarto que es una máquina.
• El diff ya dice el qué; el mensaje existe para el porqué. Si tu mensaje se deduce del diff, todavía no lo has escrito. Lo que solo cabe en el mensaje es la motivación, las alternativas descartadas, los efectos colaterales y los límites del cambio.
• La anatomía es sintaxis, no estética: asunto de ≤50 caracteres en imperativo y sin punto, línea en blanco obligatoria, cuerpo a 72 columnas, y pie con trailers (Refs, Co-authored-by, BREAKING CHANGE).
• Conventional Commits hace el asunto legible por máquinas sin dejar de serlo para las personas: tipo(ámbito): descripción. A cambio de una disciplina mínima, obtienes filtrado del historial, changelog automático y, enlazando con la lección 05-05, la versión SemVer derivada del propio historial.
• Una plantilla con commit.template en el repositorio pone el recordatorio delante de los ojos en el momento justo. Y escribir en el editor con commit.verbose en lugar de con -m mejora la calidad más que ninguna otra medida individual.
• La convención se sostiene con el hook commit-msg de la lección 06-01 para la comodidad del desarrollador y con la validación en el CI sobre rama protegida de la lección 07-06 para lo innegociable, porque --no-verify existe.
• El idioma se elige una vez, se escribe en el README.md y no se discute más.

Queda un cabo suelto que el ejercicio 3 ha dejado a la vista: un mensaje excelente no sirve de nada si la política de integración lo borra. Y esa política —merge, squash o rebase— es exactamente la decisión que dejamos abierta en la lección 07-04 sobre GitHub Flow.

La resolvemos ahora, junto con todo lo demás que hace que un historial sea legible, bisecable y reversible, en la lección 08-02: Manteniendo un Historial Limpio.