Generando mensajes de commit significativos a partir de diffs con OpenCommit
Todos hemos estado ahí: final del día laboral, una docena de cambios en cinco archivos diferentes, el cansancio aparece, y otro masterpiece como git commit -m "fix", wip 2 o refactor vuela hacia el historial del repositorio. Luego, un par de meses después, abres git log intentando descubrir por qué se rompió la autorización, solo para ver un muro de líneas de una sola línea.
El autor de OpenCommit decidió automatizar esta rutina. El proyecto toma tus cambios staged (staged changes), analiza el diff del código usando un modelo de lenguaje, y produce una descripción adecuada y clara siguiendo el estándar Conventional Commits.
Cómo funciona en la práctica
La herramienta se instala como un paquete CLI global a través de npm. Haces cambios en tu proyecto, y en lugar del comando commit usual, llamas a oco:
npm install -g opencommit
Luego, necesitas configurar una API key. Por defecto, la utilidad está configurada para modelos OpenAI (por ejemplo, gpt-4o-mini):
oco config set OCO_API_KEY=sk-...
Después de eso, el flujo de trabajo se simplifica al extremo. Haces cambios a los archivos y ejecutas:
git add .
oco
El comando oco llamará al modelo, pasará el diff de cambios, y sugerirá texto listo para usar. Si todo está bien, presionas Enter y el commit se crea. Si quieres omitir la confirmación manual, existe el flag oco --yes.
Trabajando sin enviar código a la nube
Muchos desarrolladores no pueden enviar código fuente a servidores de terceros debido a requisitos de seguridad o políticas corporativas. OpenCommit tiene integración con ejecutores locales para esto.
La herramienta puede comunicarse con Ollama y llama.cpp. Para trabajo local, solo necesitas iniciar Ollama con el modelo requerido (por ejemplo, Llama 3 o Mistral) y cambiar la configuración:
oco config set OCO_AI_PROVIDER='ollama' OCO_MODEL='llama3:8b'
Si el servidor GPU está en una máquina separada en la red local, solo necesitas especificar la dirección del endpoint:
oco config set OCO_API_URL='http://192.168.1.10:11434/api/chat'
El mismo esquema funciona para llama.cpp ejecutando el servidor HTTP integrado llama-server.
Configurando para estándares del equipo
OpenCommit tiene varios ajustes útiles que hacen que los mensajes generados sean adecuados para desarrollo real en equipo.
Conventional Commits y commitlint
Por defecto, la utilidad genera mensajes en formato Conventional Commits (feat: ..., fix: ..., chore: ...). Si tu repositorio ya tiene @commitlint configurado, puedes cambiar la utilidad para usar reglas del linter local:
oco config set OCO_PROMPT_MODULE=@commitlint
En la primera ejecución, el comando creará un archivo local .opencommit-commitlint, del cual el modelo tomará ejemplos y restricciones para la generación de texto.
Ignorando archivos innecesarios
Enviar miles de líneas de archivos lock cambiados al prompt es inútil y costoso en términos de tokens. Los archivos *.lock y *-lock.* se excluyen automáticamente, y para otros puedes crear .opencommitignore:
path/to/large-asset.zip
**/*.jpg
dist/**
Plantillas con números de ticket
A menudo necesitas incluir el número de tarea de Jira o GitHub Issues al principio del mensaje. Para esto, hay soporte de plantilla a través del placeholder $msg:
oco '#1042: $msg'
La utilidad substituirá la descripción generada en lugar de $msg, dejando el prefijo de la tarea intacto.
Integración con Git Hook
La forma más conveniente de trabajar con OpenCommit es conectarlo al hook prepare-commit-msg. Entonces ni siquiera necesitarás recordar el comando oco.
El hook se activa con:
oco hook set
Ahora cuando llames a git commit (o presiones el botón de commit en la interfaz de VS Code / WebStorm), OpenCommit generará automáticamente texto y lo insertará en la ventana de entrada del editor. Podrás ajustar la redacción de inmediato si el modelo perdió algún detalle importante.
Matices y limitaciones
Al usar la utilidad, hay un par de cosas a tener en cuenta:
- Tamaño del diff. Si has cambiado cientos de archivos a la vez, la solicitud puede alcanzar el límite de contexto del modelo o generar una descripción demasiado genérica. OpenCommit funciona mejor con commits pequeños y atómicos.
- GitHub Action. El repositorio tiene una action lista para corregir commits automáticamente al hacer push a una rama. Debes tener cuidado con esto: la action realiza un rebase interactivo, reescribiendo los SHAs de los commits. Este escenario no puede usarse para ramas compartidas (
main,dev).
A quién le será útil
OpenCommit resuelve el problema de la gestión descuidada del historial de commits en proyectos personales y equipos pequeños. Si eres demasiado perezoso para formatear manualmente los commits según las pautas, la herramienta ahorra mucho tiempo.
La forma más sencilla de comenzar es con una instalación global y Ollama local: así puedes probar inmediatamente la calidad de la generación en tus repositorios sin gastar en tokens.
Proyectos relacionados