Git

Cómo escribir un buen mensaje de commit en Git

El control de versiones en el mundo del desarrollo de software es algo totalmente necesario, y además debemos hacerlo escribiendo mensajes de commits que de gusto leer

Mario Pérez Esteso

27 de ene. de 2021 • 3 min read

Un mensaje de commit es una descripción corta de los cambios que has realizado en los archivos de un proyecto.

¿Por qué es importante escribir buenos mensajes de commit?

Escribir buenos mensajes de commit es muy importante tanto para las personas que trabajan contigo como para ti, ya que te servirán para saber exactamente qué ha pasado y qué cambios se han realizado en cada momento dentro de un proyecto.

Las buenas prácticas a la hora de programar y mantener código también aplican a cómo escribimos mensajes de commit, incluso siendo proyectos personales. Mi recomendación es que siempre utilices buenas prácticas incluso cuando sea un proyecto en el que solo tú estás participando.

Un mensaje de commit bien escrito es la mejor manera de proporcionar contexto sobre un cambio al resto de desarrolladores. Podríamos pensar que en el diferencial de código tenemos toda la información necesaria para saber qué ha cambiado pero, ¿cómo respondemos al porqué de dicho cambio? Ahí es donde entra en juego el mensaje en el commit.

Utiliza una guía de estilo

Es muy común encontrarse commit escritos de mil maneras en un repositorio, sobre todo cuando hay más de una persona trabajando en él. Para solucionar esto, podemos utilizar una guía de estilo, igual que se hace en varios repositorios conocidos como por ejemplo el de Angular.js, que personalmente es el que yo utilizo.

Todos los mensajes de commit tienen tres partes: header, body y footer. Además, la cabecera tiene un formato especial que contiene 3 partes diferenciadas: type, scope y subject.

<type>(<scope>): <subject>
<Línea en blanco>
<body>
<Línea en blanco>
<footer>

Escribir un header es obligatorio en los commits, pero el scope es opcional.

Type

Debe ser uno de los siguientes:

feat: una nueva funcionalidad
fix: una solución de un error
docs: cambios en la documentación
style: cambios que no afectan al funcionamiento del código como eliminar espacios en blando, formatear código, añadir un nuevo salto de línea...
refactor: un cambio en el código que ni añade una funcionalidad ni arregla un error
perf: un cambio en el código que mejora el rendimiento del código
test: añadir nuevos tests o arreglar los ya existentes
chore: cambios en el proceso de compilado o en el uso de herramientas externas

Scope

El scope se refiere a la parte del código en el que se está realizando un cambio, es decir, a qué clase o archivo afecta, si es para algún navegador específico, si es sobre una herramienta que se ha añadido, etc.

Subject

Esta es la parte que realmente describe lo que hemos cambiado dentro del scope. Debemos aplicar las siguientes reglas:

Utilizar el imperativo
No poner mayúscula en la primera letra
No añadir un punto (.) al final de la frase
Evitar escribir más de 50 caracteres

Algunos ejemplos de un subject bien escrito podrían ser:

update deployment documentation
remove deprecated method
merge pull request #312 from branch/name
release version 1.2.3

Algunos ejemplos de un subject mal escrito podrían ser:

refactored method to improve readability: no utiliza el imperativo
more changes to class X: tampoco utiliza el imperativo
I have released a new version.: no utiliza imperativo y tiene punto final

Body

El body sirve para explicar qué cambios hemos hecho y por qué los hemos hecho. No todos los commits son lo suficientemente complejos como para tener que escribir un body y a veces basta con escribir un buen header.

El footer también es opcional y suele utilizarse para añadir enlaces a algún issue tracker que estés utilizando como Jira, Redmine o Clubhouse.

Conclusión

Tanto si trabajamos solos en un proyecto como si trabajamos con un equipo, debemos tener siempre en mente que escribir buenos commits es muy importante para saber qué se ha hecho y por qué motivo. Tener una guía de estilo también viene muy bien y hará que el proyecto tenga una buena consistencia en cuanto a legibilidad e histórico de cambios.