Gerando mensagens de commit significativas a partir de diffs com OpenCommit

Todos já passamos por isso: fim do dia de trabalho, uma dúzia de alterações em cinco arquivos diferentes, o cansaço aparece, e mais uma obra-prima como git commit -m "fix", wip 2 ou refactor voa para o histórico do repositório. Então, alguns meses depois, você abre git log tentando descobrir por que a autorização quebrou, só para ver uma parede de mensagens de uma linha.

O autor do OpenCommit decidiu automatizar essa rotina. O projeto pega suas alterações staged (staged changes), analisa o diff do código usando um modelo de linguagem e produz uma descrição adequada e clara seguindo o padrão Conventional Commits.

Como funciona na prática

A ferramenta é instalada como um pacote CLI global via npm. Você faz alterações no seu projeto e, em vez do comando commit usual, chama oco:

npm install -g opencommit

Em seguida, você precisa definir uma API key. Por padrão, o utilitário está configurado para modelos OpenAI (por exemplo, gpt-4o-mini):

oco config set OCO_API_KEY=sk-...

Depois disso, o fluxo de trabalho é simplificado ao extremo. Você faz alterações nos arquivos e executa:

git add .
oco

O comando oco chamará o modelo por conta própria, enviará o diff das alterações e sugerirá um texto pronto. Se tudo estiver bom, você pressiona Enter e o commit é criado. Se quiser pular a confirmação manual, existe a flag oco --yes.

Trabalhando sem enviar código para a nuvem

Muitos desenvolvedores não podem enviar código-fonte para servidores de terceiros devido a requisitos de segurança ou políticas corporativas. O OpenCommit tem integração com executores locais para isso.

A ferramenta pode se comunicar com Ollama e llama.cpp. Para trabalho local, você só precisa iniciar o Ollama com o modelo necessário (por exemplo, Llama 3 ou Mistral) e mudar a configuração:

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

Se o servidor GPU estiver em uma máquina separada na rede local, você só precisa especificar o endereço do endpoint:

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

O mesmo esquema funciona para llama.cpp executando o servidor HTTP embutido llama-server.

Configurando para padrões da equipe

O OpenCommit tem várias configurações úteis que tornam as mensagens geradas adequadas para desenvolvimento real em equipe.

Conventional Commits e commitlint

De fábrica, o utilitário gera mensagens no formato Conventional Commits (feat: ..., fix: ..., chore: ...). Se seu repositório já tem @commitlint configurado, você pode mudar o utilitário para usar as regras do linter local:

oco config set OCO_PROMPT_MODULE=@commitlint

Na primeira execução, o comando criará um arquivo local .opencommit-commitlint, do qual o modelo pegará exemplos e restrições para geração de texto.

Ignorando arquivos desnecessários

Enviar milhares de linhas de lock files alterados para o prompt é inútil e custoso em termos de tokens. Os arquivos *.lock e *-lock.* são excluídos automaticamente, e para outros você pode criar .opencommitignore:

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

Templates com números de ticket

Frequentemente você precisa incluir o número da tarefa do Jira ou GitHub Issues no início da mensagem. Para isso, existe suporte a templates via o placeholder $msg:

oco '#1042: $msg'

O utilitário substituirá a descrição gerada no lugar de $msg, deixando o prefixo da tarefa intacto.

Integração com Git Hook

A forma mais conveniente de trabalhar com o OpenCommit é conectá-lo ao hook prepare-commit-msg. Então você nem precisará lembrar do comando oco.

O hook é habilitado com:

oco hook set

Agora quando você chamar git commit (ou pressionar o botão de commit na interface do VS Code / WebStorm), o OpenCommit gerará automaticamente o texto e o inserirá na janela de input do editor. Você poderá ajustar a redação imediatamente se o modelo tiver perdido algum detalhe importante.

Nuances e limitações

Ao usar o utilitário, há algumas coisas para ter em mente:

1. Tamanho do diff. Se você mudou centenas de arquivos de uma vez, a requisição pode atingir o limite de contexto do modelo ou gerar uma descrição muito genérica. O OpenCommit funciona melhor com commits pequenos e atômicos.
2. GitHub Action. O repositório tem uma action pronta para corrigir commits automaticamente ao fazer push para uma branch. Você precisa ter cuidado com isso: a action realiza um rebase interativo, reescrevendo os SHAs dos commits. Esse cenário não pode ser usado para branches compartilhadas (main, dev).

Para quem é útil

O OpenCommit resolve o problema do gerenciamento descuidado do histórico de commits em projetos pessoais e pequenas equipes. Se você é preguiçoso demais para formatar commits manualmente de acordo com as diretrizes, a ferramenta economiza muito tempo.

A forma mais fácil de começar é com uma instalação global e Ollama local: assim você pode testar imediatamente a qualidade da geração nos seus repositórios sem gastar com tokens.