CÓMO ESCRIBIR MEJORES MENSAJES DE COMMIT EN GIT: UNA GUÍA PASO A PASO

August 5, 2025

Aprende a comunicar tus cambios de código con mensajes de commit claros y concisos

En Git, los mensajes de commit son fundamentales para comunicar los cambios realizados en el código. Más allá de simples comentarios, estos mensajes permiten un registro detallado de quién hizo qué cambios y por qué, facilitando la colaboración y el mantenimiento del proyecto.

La frustración surge cuando al revisar el historial de un repositorio encontramos mensajes de commit cortos e ininteligibles como “corrección de errores” o “actualización del código”. Estos mensajes no aportan suficiente información para que otros desarrolladores comprendan los cambios realizados.

Por ello, es crucial aprender a escribir mensajes de commit claros y concisos. A continuación, presentamos una guía paso a paso para ayudarte a escribir mensajes de commit efectivos.

1. Comienza con un resumen breve

El resumen debe ser breve y explicar en una o dos oraciones qué se ha modificado o mejorado en el código. Por ejemplo, “Agregar función de búsqueda” o “Actualizar la página de inicio de sesión”.

2. Cambia el verbo del inicio a tiempo presente

El verbo que inicie el mensaje de commit debe estar en tiempo presente para hacer más evidente quién llevó a cabo los cambios. Por ejemplo, en vez de “corregí un error en la función de búsqueda”, debe decir “corrige un error en la función de búsqueda”.

3. Agrega detalles sobre los cambios efectuados

Proporciona detalles en el mensaje de commit explicando los cambios realizados. Si el cambio está relacionado con un problema actual, incluye números o enlaces a los issues relacionados. Es importante ser conciso pero informativo.

4. Sé detallado pero breve

Describe lo modificado con detalle, pero asegúrate de que el mensaje no sea demasiado extenso para evitar que se vuelva tedioso de leer.

Siguiendo estas pautas, mejoramos la calidad de los mensajes de commit. Aunque parezcan pequeños, estos mensajes son esenciales para que el equipo comprenda claramente los cambios y avance adecuadamente en el desarrollo.

Ejemplo:

“Agregar función de búsqueda”

Ahora se ha agregado una función de búsqueda a la página principal para facilitar la búsqueda de artículos por parte de los lectores. Este cambio responde a una necesidad de los usuarios y mejorará la experiencia en nuestra plataforma. Se corrigieron pequeños errores encontrados en la implementación de dicha función.

Siguiendo estos pasos, podemos comunicar mejor los cambios en nuestro código a través de mensajes de commit, impactando positivamente en la eficiencia y eficacia del proyecto.

Identifica qué información debe incluirse en un mensaje de commit efectivo

Git es un sistema de control de versiones que permite a los desarrolladores trabajar en equipo y llevar un registro de todos los cambios en el código. Un mensaje de commit claro y efectivo ayuda a rastrear cambios y entender qué se hizo en cada versión.

Para crear un mensaje efectivo, debe incluir:

Una descripción breve y concisa de la tarea o problema abordado, usando un verbo en tiempo presente que comunique claramente el objetivo. Por ejemplo, “Corrige errores de ortografía en la sección de inicio”.
Información sobre cómo se modificó el código para resolver el problema, incluyendo cambios en la estructura, lógica, o archivos añadidos/eliminados.
Señalización de si el cambio afecta algún requisito o función relacionada, para que el equipo comprenda su impacto en el proyecto.

El mensaje debe ser corto y fácil de entender, usando palabras sencillas y transmitiendo la información eficientemente. No es necesario un párrafo extenso salvo que el cambio sea complejo.

Crear mensajes claros y efectivos es fundamental para un buen control de versiones. Incluye descripción breve, explicación de la solución y relación con otras partes del proyecto. Con práctica, esto se vuelve un hábito que mejora la colaboración y calidad del proyecto.

Utiliza un lenguaje claro y específico para describir los cambios realizados en el código

Para escribir buenos mensajes de commit es esencial usar un lenguaje claro y específico que describa con precisión los cambios realizados. No asumas que las modificaciones son obvias o que pueden inferirse fácilmente.

Recomienda usar un lenguaje claro, preciso y específico para que otros desarrolladores entiendan qué se cambió y por qué.

El mensaje debe ser una frase corta y concisa que detalle lo modificado. Por ejemplo, en lugar de “varios cambios”, mejor “Corregido bug en la función X”, seguido del motivo.

Evita jerga técnica y usa palabras sencillas para que sea comprensible para desarrolladores de todos los niveles. Imagina explicar el cambio a un compañero que no está en el proyecto.

Contextualiza los cambios, explicando no solo qué se hizo, sino por qué. Por ejemplo, si se corrigió un bug, explica qué problemas causaba y por qué era necesario corregirlo.

Para escribir mejores mensajes de commit es esencial usar lenguaje claro, evitar jerga, contextualizar y justificar cada cambio. Esto facilita la revisión y mantenimiento del proyecto.

Asegúrate de que tu mensaje de commit sea fácilmente comprensible para otros desarrolladores

Es importante que cualquier desarrollador pueda entender fácilmente lo que se hizo y por qué.

Para lograrlo:

Usa palabras sencillas: evita términos técnicos complejos y usa frases cotidianas.
Sé específico: en lugar de “arreglando algunos errores”, especifica cuáles y si están relacionados con problemas de seguridad o versiones.
Sé consistente: mantén un formato uniforme, por ejemplo, iniciar con verbo en infinitivo (“Agregar”, “Eliminar”, “Actualizar”).
Sé breve: limita la información a lo esencial para evitar mensajes densos.

Ejemplo:

“Actualizar la función de inicio de sesión para corregir el problema de seguridad en la versión 2.0 de la aplicación”

Mensajes claros, concisos y fáciles de entender facilitan la colaboración y son valorados por el equipo.

Evita mensajes de commit genéricos o confusos que puedan dificultar la revisión y el seguimiento del código

En equipo, los mensajes deben ser claros, precisos y descriptivos para que otros entiendan qué se hizo y por qué.

Evita mensajes genéricos o confusos como “corrección de errores”. Detalla qué errores se corrigieron y dónde.

Incluye toda la información relevante, por ejemplo, qué hace una nueva funcionalidad y cómo interactuar con ella.

Consejos:

Mantén los mensajes cortos y concisos.
Usa el imperativo al inicio (“Agregar nueva función” en lugar de “He agregado…”).
Usa líneas adicionales para detalles cuando sea necesario.

Ejemplo:

Agregar función de búsqueda por categoría de producto

Este cambio agrega una funcionalidad que permite buscar productos por categoría (ej. "ropa", "electrónica"). Se implementó con la biblioteca XYZ para compatibilidad con navegadores.

Soluciona problema de acceso denegado en la API

Corrige un error que causaba fallos de acceso denegado para algunos usuarios. Se actualizó la lógica de autorización en API.php y se documentaron los cambios.

Siguiendo estos consejos, tus mensajes serán claros y eficientes, facilitando la contribución y revisión del código.

Conclusiones

Escribir mensajes de commit claros, concisos y específicos es una práctica esencial para el desarrollo colaborativo y el mantenimiento eficiente de proyectos. Utilizar un lenguaje sencillo, contextualizar los cambios y evitar mensajes genéricos mejora la comunicación entre desarrolladores y facilita la revisión del código. Adoptar estas buenas prácticas en el control de versiones con Git contribuye a la calidad del software y a la productividad del equipo.