Git Commit Organizer: de un working tree caótico a commits que se entienden solos

¿Qué es git-commit-organizer? ¶

git-commit-organizer coge ese momento en que terminas de currar y tienes el working tree lleno de cambios mezclados —una feature a medias, un bug que arreglaste de paso, un par de dependencias que subiste— y lo convierte en un historial limpio: commits atómicos, cada uno con sentido propio, fáciles de revisar, revertir y cherry-pick.

No es un alias de git commit -m. Es un compañero que lee de verdad tus diffs (no solo los nombres de fichero), entiende qué hace cada cambio y los agrupa por intención. Sigue la especificación Conventional Commits en inglés, te propone los mensajes y espera tu aprobación explícita antes de tocar nada. Y hay una regla que no se salta jamás: nunca hace git push.

Cómo agrupa tus cambios ¶

La idea es un commit por cambio lógico, de forma que cada uno se sostenga solo y no rompa el build. Para eso:

• Lee los diffs, no los nombres. Un fichero tocado puede ser una feature, un fix o un refactor: solo el diff lo dice. Agrupa por intención, así que primero entiende la intención.
• Separa lo que no va junto. Un bug fix y una feature nueva van en commits distintos. Un cambio y los tests que lo cubren van juntos. Config, build y dependencias agrupan de forma natural.
• Elige type y scope. feat, fix, refactor, perf, test, docs, style, build, ci, chore, revert — con un scope corto y en minúscula (el área que tocas).
• No sobre-divide. Si todo es un único cambio cohesionado, un solo commit es la respuesta correcta. No parte por partir.

Las tres reglas que no se saltan ¶

Organizar el historial es cómodo, pero solo si confías en que la herramienta no va a hacer nada raro. Por eso:

• Nunca hace push. Publicar es siempre tu decisión. No ejecuta git push bajo ningún concepto.
• Nunca hace commit sin tu visto bueno. Te enseña el plan —el mensaje de cada commit y los ficheros exactos que va a stagear— y espera un sí explícito. Esta puerta no se negocia.
• Sin firmas de IA. Los commits representan a los autores humanos del proyecto: nada de Co-authored-by, Signed-off-by ni cualquier referencia a una herramienta de IA en los metadatos.

Cómo queda un commit ¶

Este es exactamente el formato que produce la skill: cabecera type(scope): descripción, gitmoji opcional y un cuerpo con bullets que explican el porqué cuando el diff no es obvio. De hecho, así se ve el historial de este mismo repositorio, el de webreactiva.com:

feat(react-to-text): ✨ Add function to convert ReactNode to plain text
feat(webmcp-inspector): ✨ Add WebMCP inspector skill and polyfill
feat(clusters): 🧩 add thematic clusters page and related components
fix(saved-sessions): 🐛 improve session directory resolution
feat(translations): ✨ add Spanish translations for Vidstack layouts

Y un commit con su cuerpo, cuando merece la pena contar qué cambió y por qué:

feat(react-to-text): ✨ Add function to convert ReactNode to plain text

- Introduced `reactToPlainText` function to serialize ReactNode elements.
- Handles strings, numbers, arrays, and React elements.
- Ensures compatibility with WebMCP agent requirements for text serialization.

Cabecera en imperativo, sin punto final, por debajo de ~72 caracteres; cuerpo en bullets que se saltan el ruido tipo “updated imports”. Con gitmoji activado, cada type lleva su emoji: feat ✨ · fix 🐛 · refactor ♻️ · perf ⚡ · test ✅ · docs 📝 · style 🎨 · build 📦 · ci 👷 · chore 🔧 · revert ⏪

Cómo instalar git-commit-organizer ¶

Funciona con cualquier agente compatible con el estándar abierto de Agent Skills (Claude Code, Cursor, Codex, OpenCode, Gemini CLI…). Pega esto en tu terminal y listo:

npx skills add webreactiva/skills --skill git-commit-organizer

¿La quieres disponible en todos tus proyectos? Añade -g para instalarla global en la carpeta de skills de tu agente (~/.agents/skills, o ~/.claude/skills si usas Claude Code):

npx skills add webreactiva/skills --skill git-commit-organizer -g

Es open source. Puedes ver el código fuente en GitHub antes de instalarla.

Preguntas frecuentes ¶

¿En qué idioma escribe los mensajes de commit? ¶

En inglés, en imperativo y siguiendo Conventional Commits. Es el estándar más portable para un historial que van a leer otras personas (y otras herramientas). Tú puedes pedirle los cambios en español: lo que sale en inglés es el commit.

¿Va a commitear o pushear algo sin que me entere? ¶

No. Te enseña el plan completo —el mensaje y los ficheros exactos de cada commit— y espera tu sí explícito antes de stagear nada. Y git push no lo toca nunca: publicar es siempre tu decisión.

¿Puedo dejar fuera una carpeta o añadir el número de issue? ¶

Sí. Dile exclude <carpetas> y las deja sin stagear (sin borrarlas). Para la issue, pásale #412 o deja que la detecte sola desde el nombre de la rama (feature/412, 412-add-search…). Nunca se inventa un número que no encuentre.

¿Con qué agentes funciona? ¶

Con cualquiera compatible con el estándar abierto de Agent Skills: Claude Code, Cursor, OpenAI Codex, OpenCode, Gemini CLI y más. La instalas una vez y la usas donde quieras.

¿Tiene coste? ¶

Es open source. La descargas e instalas gratis; el código está en GitHub.