Commits Triángulo
Un asunto tiene este aspecto:
<área><comportamiento o intención>[modificador] <ticket> (ámbito): <resumen>
🧩👔 #412 (servidor): permitir una apelación en un plazo de 30 días tras la denegación
🎨💄 — (tokens): tomar los nuevos matices de Figma
Los emojis son los primeros caracteres de la línea, sin nada alrededor. El último ejemplo es un commit realizado por un trabajo: no tiene ticket, por lo que lleva una raya em.
El vocabulario es extenso a propósito y no necesitas tenerlo en la cabeza. El
comando gitmoji lo entrega en pequeñas partes. Lee solo la parte que necesites.
El comando
Usa el comando gitmoji. Si no está en el PATH, lee references/vocabulary.txt en la carpeta de esta habilidad
para obtener todo el vocabulario e informa a la persona de que falta el comando.
| Cuándo | Ejecuta |
|---|---|
| Necesitas la lista de áreas | gitmoji guide areas |
| Conoces el área | gitmoji guide 🧩 (cualquier emoji o nombre de área) |
| Nada en la guía del área encaja | gitmoji guide groups, luego un grupo: gitmoji guide "reparación" |
| Dos entradas parecen encajar | gitmoji guide 🛡️, o el grupo: gitmoji guide "protección" |
| El trabajo es una prueba, un apaño o un cambio incompatible | gitmoji guide modifiers |
| Necesitas los nombres de los ámbitos | gitmoji guide scopes |
| Estás a punto de escribir el resumen o el cuerpo | gitmoji guide message |
Antes de git commit | gitmoji staged, luego gitmoji check -m '<asunto>' para la primera línea, o gitmoji check <archivo> para un mensaje completo |
Escribiste códigos cortos como :jigsaw::necktie: | Nada: el hook escribe los emojis por ti |
| Estás deshaciendo un commit | git revert <commit>; la primera línea de git permanece como está |
| El hook rechazó un asunto | Lee su mensaje; nombra la corrección |
| Quieres revisar los commits de tu rama antes de fusionarla | gitmoji history trunk..HEAD (la rama en la que se fusionará, luego la tuya) |
| El hook dice que el repositorio adoptó otra versión | Lee qué cambió en la dirección que proporciona e informa al usuario antes de cambiar la configuración |
Antes de escribir código: planifica los commits
Lee el ticket y escribe los asuntos que esperas hacer, como una lista. Cada uno es una
decisión que un revisor podría aceptar por sí sola, y cada uno es algo que el ticket solicita.
El ámbito de cada uno es el paquete que posee la decisión (gitmoji guide scopes).
Estas son indicaciones, no una pila que haya que llenar. Planifica un commit solo cuando el ticket dé una respuesta a la pregunta:
- ¿Qué decide la empresa (
👔) y qué ocurre con el tiempo (⛓️)? - ¿Qué se rechaza antes de probar un paso (
🛡️)? Cuando un paso falla, ¿cómo se recupera, qué código de error reporta y qué se le dice a las personas (🥅)? - ¿Qué forma se acuerda entre las piezas (
🏷️) y qué se almacena (💾)? - ¿Qué ven y hacen los usuarios, y en qué commit lo obtienen por primera vez (
✨)? - ¿Cómo sabremos que un usuario lo consigue en el producto real (
✅, su propio commit, añadido una vez que el producto se pueda ejecutar de esa manera)?
Cuando el recorrido no se pueda ejecutar aún, lanza la funcionalidad y di en el ticket que su ✅
está pendiente. No pongas ✅ en una verificación más pequeña para llenar el vacío; eso es ☑️.
Comprueba si existe un propietario antes de planificar un nuevo endpoint, almacenamiento o política. Si falta una decisión de producto y cambiaría lo que se lanza, escribe la pregunta y pregunta. No la resuelvas dentro de un commit.
Una funcionalidad que es una decisión, con su único llamador y las comprobaciones que necesita, es un commit. Planifica más líneas solo cuando el ticket contenga más de una decisión que un revisor pudiera tomar por separado. Una línea que el ticket nunca pidió es demasiado fina.
Antes de cada commit: cuatro preguntas
- ¿De qué área forma parte o trata el cambio? Una prueba, un documento y un entorno de pruebas toman el área de la cosa sobre la que tratan.
- ¿Qué es diferente ahora, o qué hiciste? Si el commit cambia lo que se promete, nombra el comportamiento (un sustantivo). En caso contrario, nombra la intención (un verbo).
- ¿El trabajo no está resuelto? Solo entonces añade un tercer emoji:
🧪una prueba,🚧un apaño,💥los consumidores deben adaptarse. Una prueba mantiene🧪en cada commit hasta🏁(conservada) o⚰️(descartada), y nada resuelto puede depender de ella antes de eso. Construir la dirección que un ticket ha elegido no es una prueba. - ¿Qué ticket? Usa el formato de ticket del repositorio. Solo un trabajo escribe
—.
Luego ejecuta gitmoji check -m '<asunto>'.
Antes de preparar los cambios, lee el cambio como alguien que no estuvo allí. Cuando la razón no se pueda deducir del código, escribe un comentario junto al código: por qué es como es, qué no debe cambiarse, de dónde viene un valor. Di por qué, no qué hace la línea. Un comentario casi no te cuesta nada y le ahorra al siguiente lector, una persona, un junior o un agente sin tu contexto, tener que adivinar.
Cuando un par no encaja
Esa es la señal para mirar de nuevo, no para elegir la etiqueta más cercana.
- Cuando encajan dos etiquetas, nombra lo que el revisor podría aceptar ahora y lo que podría
aplazar. Divide cuando esas dos decisiones puedan diferir y lo que se conserva siga funcionando por
sí solo. Prepara por ruta o por fragmento (
git add -p). - Mantén juntos el único llamador, su cableado y las comprobaciones de rechazo que necesita cuando ninguno de ellos tenga una promesa propia. Etiqueta el commit por su punto; el resto va de acompañamiento.
gitmoji stagedinforma de dos ámbitos: haz la misma pregunta. Si el cambio solo tiene sentido completo, como una forma reflejada en dos lenguajes, mantenlo junto y nombra el paquete que posee la decisión.- Las partes que son forzadas por el cambio principal van de acompañamiento: sus tipos, su prueba, una historia, un archivo de bloqueo.
Cada commit debe seguir compilando y pasando las pruebas por sí solo. Si dividirlo rompiera eso, mantén juntas las partes forzadas y dilo en el cuerpo.
Cómo escribirlo
- Resumen: lo que el sistema hace ahora, en las palabras del dominio, comenzando con un verbo
en minúsculas. Toda la primera línea cabe en 140 caracteres, emojis, ticket y ámbito
incluidos, y cuanto más corto, mejor;
gitmoji check -m '<asunto>'lo cuenta por ti antes de que hagas el commit. Sin nombres de archivos, sin números de ticket, sin "cómo". - Descripción: cada commit que escribes tiene una, y el hook rechaza un commit sin
ella. Solo un marcador (
🔖,🔺), un commit hecho por un trabajo y un mensaje escrito por git no necesitan ninguna. Debajo de la primera línea, una línea vacía, luego por qué se hizo el cambio: la razón, por qué de esta manera y no la obvia, o el valor que elegiste. Una o dos líneas suelen ser suficientes; seis son el máximo. Mantén las referencias a tickets dentro de la oración (por ejemplo, "Ver #42 para la decisión"). Git puede eliminar una línea que comience con#42cuando alguien edita el commit. No vuelvas a contar el diff, no enumeres archivos ni describas tu proceso. - Emojis, no códigos cortos. Solo los caracteres se confirman.
Quién lo escribió
Nunca te añadas a ti mismo como autor o coautor. Sin línea Co-Authored-By:, sin identidad de agente
en git config user.* o --author. El autor es la persona responsable, y
el hook rechaza a un agente allí. Algunas herramientas añaden una línea de coautor por sí mismas sin
que se lo pidan; cuando el hook rechaza un commit por eso, elimina la línea y vuelve a hacer el commit.
En su lugar, termina el cuerpo con una línea vacía y una firma que diga qué contribuyó al commit:
_
modelo-ejemplo (alto), editor
Claude Code (sesión-ejemplo)
Sub-agentes: 2 × ayudante-ejemplo (medio)
Equipo: revisor, probador
Investigación: 3 búsquedas, 12 páginas
Las tres primeras líneas están siempre presentes. Las tres últimas aparecen solo cuando corresponden.
Cuando se realiza el commit, el hook reemplaza el guion bajo por △ y, entre acentos graves,
la versión del vocabulario contra la que se verificó el mensaje, por lo que una firma almacenada tiene este aspecto:
△ `1.2.3`
modelo-ejemplo (alto), editor
Claude Code (sesión-ejemplo)
Escribe el guion bajo; nunca escribas la línea △ tú mismo. El hook cierra cada mensaje
con él, también el de una persona, que entonces tiene esa única línea y ninguna firma.
gitmoji history lo lee para saber qué commits están en qué versión.
Los proyectos pueden establecer signature = "agents" bajo [rules] para requerir las líneas de modelo y herramienta
cuando una sesión de agente compatible ejecuta el hook de commit. Un humano puede hacer un commit con la descripción ordinaria. Los marcadores de versión y los mensajes generados por Git mantienen sus exenciones existentes.
| Línea | Qué dice |
|---|---|
_ | La firma comienza aquí. El hook la convierte en △ `<version>` . |
| línea del modelo | El modelo y su esfuerzo. Después de una coma, tu nombre, solo si una persona te ha dado uno. |
| línea de la herramienta | La herramienta y, entre paréntesis, el id de sesión, si lo hay. |
Sub-agentes: | Cuántos subagentes hicieron parte del trabajo de este commit, por modelo y esfuerzo. |
Equipo: | Los otros agentes con los que intercambiaste mensajes para este commit. |
Investigación: | Búsquedas web, páginas leídas y consultas de documentación para este commit. |
No escribas nada de esto de memoria. Ejecuta el script para tu herramienta en scripts/
de esta carpeta de habilidad y pega lo que imprima. La ruta es relativa a la carpeta en la que
se encuentra este archivo, dondequiera que esté instalada la habilidad:
python3 scripts/claude-code.py
En Claude Code, esa carpeta es ${CLAUDE_SKILL_DIR}. El script lee el registro propio de la herramienta
de la sesión. Si tu herramienta no tiene un script allí, scripts/README.md dice cómo
elaborar uno una vez y añadirlo. Cuando no se pueda encontrar ningún registro, el script imprime
unknown. Un repositorio puede pedirte que omitas una línea, como el id de sesión; sus propias
instrucciones lo indican.
Si la sesión abarca varias tareas o repositorios, verifica las líneas de actividad opcionales con respecto a este commit. Conserva solo las contribuciones que puedas atribuirle.
Líneas que el cuerpo puede llevar
🩹necesitaLimitación: <lo que la dependencia no puede hacer>.📥necesitaFuente: <la ejecución, herramienta o sistema del que provino>.🏁y⚰️dicen qué lo decidió.🐛puede nombrar la causa:Roto-por: <sha>.
Al actualizar Gitmoji
El CLI, la habilidad y el vocabulario comparten un número de versión. El hook advierte cuando la configuración del repositorio nombra otra versión que la que habla
el comando. Informa al usuario y lee qué cambió en la dirección que da la advertencia. Cuando el
usuario quiera la nueva versión, establécelo bajo [vocabulary] en la configuración y haz un commit de eso
solo, con la versión entre acentos graves:
🔺 gitmoji `<version>`: <qué cambia para este repositorio>
No reescribas un historial que ya está compartido a menos que el usuario lo pida: los commits
hechos bajo reglas anteriores pueden permanecer como están. gitmoji history --unmigrated muestra
cuáles de ellos no pasarían hoy. Ejecuta gitmoji init después de cambiar el pin para actualizar la habilidad instalada y los flujos de trabajo gestionados.
Fusionar pull requests y actualizar el historial
Habilita el flujo de trabajo de título de PR y selecciona Pull request title and description como mensaje de fusión predeterminado. Escribe el título humano. Gitmoji mantiene su prefijo de emoji a medida que cambian los commits. Usa Create a merge commit con el mensaje sugerido. GitHub conserva los commits con autoría y añade el número de PR integrador.
Para un historial existente, usa la guía de actualización
y el script instalado scripts/gitmoji-upgrade-history.py. Inspecciona la ejecución de prueba
antes de crear un candidato local. Los enlaces requieren evidencia de qué PR aterrizó.
Un reemplazo de rama compartida es una decisión separada para los propietarios del repositorio.
Mensajes que Git escribe
Una fusión puede tener cualquier título. El hook conserva el archivo de mensaje de Git durante una fusión
pendiente, y gitmoji history reconoce una fusión almacenada por sus múltiples padres.
Un check -m solo de texto solo tiene el asunto con el que trabajar. Reconoce los
encabezados habituales de fusión de rama, etiqueta y commit de Git, los encabezados de fusión de pull request de GitHub,
los títulos numerados Merge #N, los asuntos citados de revertir y reaplicar de Git,
los títulos numerados Revert #N y Reapply #N con un título, el encabezado de registro de squash
predeterminado de Git y los prefijos de autosquash fixup! , squash! y amend! .
Una fusión squash con un título de PR personalizado produce un commit ordinario de un padre. Los cherry-picks y rebases también pueden trasladar asuntos ordinarios. Verifica esos como otros commits con autoría. Un número de PR por sí solo no identifica una fusión.
Durante la adopción, un proyecto puede establecer [rules] → untagged = "warn" en
gitmoji.toml para aceptar asuntos simples y marcarlos para revisión. El valor predeterminado
es "error". Con "off", la etiqueta faltante se acepta silenciosamente. Otras comprobaciones
siguen aplicándose. Usa gitmoji history trunk..HEAD en tu rama para encontrar asuntos
que reformular antes de compartir. El historial siempre comprueba los asuntos sin etiqueta de forma estricta.
Cuando nada encaja
No fuerces una entrada. Usa la más honesta que tengas cerca, añade una línea en el cuerpo
Falta: <lo que querías decir> e informa al usuario. Las faltas son cómo se corrige el vocabulario.