Generare messaggi di commit significativi dai diff con OpenCommit

Ci siamo passati tutti: fine della giornata lavorativa, una dozzina di modifiche in cinque file diversi, la stanchezza arriva, e un altro capolavoro come git commit -m "fix", wip 2 o refactor vola nella cronologia del repository. Poi, un paio di mesi dopo, apri git log cercando di capire perché l'autorizzazione si è rotta, solo per vedere una parete di one-liner.

L'autore di OpenCommit ha deciso di automatizzare questa routine. Il progetto prende le tue modifiche staged (staged changes), analizza il diff del codice usando un modello linguistico e produce una descrizione corretta e chiara seguendo lo standard Conventional Commits.

Come funziona in pratica

Lo strumento si installa come pacchetto CLI globale tramite npm. Fai le modifiche al tuo progetto, e invece del solito comando commit, chiami oco:

npm install -g opencommit

Successivamente, devi impostare una API key. Di default, l'utility è configurata per i modelli OpenAI (per esempio, gpt-4o-mini):

oco config set OCO_API_KEY=sk-...

Dopo di che, il flusso di lavoro è semplificato all'estremo. Fai le modifiche ai file ed esegui:

git add .
oco

Il comando oco chiamerà il modello, passerà il diff delle modifiche e suggerirà del testo pronto. Se va tutto bene, premi Invio e il commit viene creato. Se vuoi saltare la conferma manuale, c'è il flag oco --yes.

Lavorare senza inviare codice nel cloud

Molti sviluppatori non possono inviare codice sorgente a server di terze parti per requisiti di sicurezza o policy aziendali. OpenCommit ha integrazione con runner locali per questo.

Lo strumento può comunicare con Ollama e llama.cpp. Per il lavoro locale, devi solo avviare Ollama con il modello richiesto (per esempio, Llama 3 o Mistral) e cambiare la configurazione:

oco config set OCO_AI_PROVIDER='ollama' OCO_MODEL='llama3:8b'

Se il server GPU è su una macchina separata nella rete locale, devi solo specificare l'indirizzo dell'endpoint:

oco config set OCO_API_URL='http://192.168.1.10:11434/api/chat'

Lo stesso schema funziona per llama.cpp eseguendo il server HTTP integrato llama-server.

Configurazione per gli standard del team

OpenCommit ha diverse impostazioni utili che rendono i messaggi generati adatti allo sviluppo reale in team.

Conventional Commits e commitlint

Di default, l'utility genera messaggi in formato Conventional Commits (feat: ..., fix: ..., chore: ...). Se il tuo repository ha già @commitlint configurato, puoi passare l'utility a usare le regole del linter locale:

oco config set OCO_PROMPT_MODULE=@commitlint

Al primo avvio, il comando creerà un file .opencommit-commitlint locale, da cui il modello prenderà esempi e vincoli per la generazione del testo.

Ignorare file non necessari

Inviare migliaia di righe di lock file modificati al prompt è inutile e costoso in termini di token. I file *.lock e *-lock.* sono esclusi automaticamente, e per altri puoi creare .opencommitignore:

path/to/large-asset.zip **/*.jpg dist/**

Template con numeri di ticket

Spesso devi includere il numero del task da Jira o GitHub Issues all'inizio del messaggio. Per questo, c'è il supporto ai template tramite il placeholder $msg:

oco '#1042: $msg'

L'utility sostituirà la descrizione generata al posto di $msg, lasciando intatto il prefisso del task.

Integrazione con Git Hook

Il modo più comodo per lavorare con OpenCommit è agganciarlo all'hook prepare-commit-msg. Così non dovrai nemmeno ricordare il comando oco.

L'hook si abilita con:

oco hook set

Ora quando chiami git commit (o premi il pulsante commit nell'interfaccia di VS Code / WebStorm), OpenCommit genererà automaticamente il testo e lo inserirà nella finestra di input dell'editor. Potrai perfezionare la formulazione seduta stante se il modello ha perso qualche dettaglio importante.

Sfumature e limitazioni

Quando usi l'utility, ci sono un paio di cose da tenere a mente:

1. Dimensione del diff. Se hai modificato centinaia di file in una volta, la richiesta potrebbe raggiungere il limite di contesto del modello o generare una descrizione troppo generica. OpenCommit funziona meglio con commit piccoli e atomici.
2. GitHub Action. Il repository ha un'action pronta per correggere automaticamente i commit quando si fa push su un branch. Devi fare attenzione: l'action esegue un rebase interattivo, riscrivendo gli SHA dei commit. Questo scenario non può essere usato per branch condivisi (main, dev).

A chi tornerà utile

OpenCommit risolve il problema della gestione negligente della cronologia dei commit in progetti personali e team piccoli. Se sei troppo pigro per formattare manualmente i commit secondo le linee guida, lo strumento fa risparmiare un sacco di tempo.

Il modo più semplice per iniziare è con un'installazione globale e Ollama locale: così puoi testare subito la qualità della generazione sui tuoi repository senza spendere in token.