GitBot Commit

AI-powered commit message generator for VS Code, powered by OpenRouter.

---

🇺🇸 English

• Features
• Requirements
• Installation
• Configuration
• Usage
• Customizing the Prompt
• FAQ

---

🇧🇷 Português (Brasil)

• Funcionalidades
• Requisitos
• Instalação
• Configuração
• Como usar
• Customizando o Prompt
• Perguntas Frequentes

---

---

🇺🇸 English

✨ Features

• One-click generation — click the ✨ button in the Source Control panel to generate a commit message from your staged changes.
• OpenRouter integration — use any model available on OpenRouter (Claude, GPT-4o, Gemini, Llama, Mistral, and hundreds more).
• Conventional Commits + Emojis — messages follow the Conventional Commits standard, with emojis for quick visual scanning.
• Chain-of-Thought support — works correctly with reasoning models (e.g. DeepSeek R1, o1) that return intermediate reasoning steps before the final answer.
• Bilingual — generate messages in English or Brazilian Portuguese.
• Fully customizable prompt — replace the default system prompt with your own for any team convention.
• Secure API Key storage — your key is stored in VS Code's encrypted Secret Storage, never in plain text.
• Editable preview — review, edit, copy or apply the generated message before committing.

---

📋 Requirements

• VS Code 1.85.0 or later
• An OpenRouter account and API Key — get one at openrouter.ai/keys
• Git installed and available in your system PATH

---

📦 Installation

From the Marketplace

1. Open VS Code.
2. Press Ctrl+Shift+X to open the Extensions panel.
3. Search for GitBot Commit.
4. Click Install.

From a .vsix file

code --install-extension gitbot-commit-x.x.x.vsix

---

⚙️ Configuration

All settings are accessible through the GitBot: Settings command.

Opening Settings

Three ways to open the settings panel:

Method	Steps
Source Control button	Ctrl+Shift+G → click the ⚙ icon in the panel toolbar
Command Palette	Ctrl+Shift+P → type GitBot: Configurações
VS Code Settings UI	Ctrl+, → search gitbotcommit

Available Settings

🔑 API Key

Your OpenRouter API Key. Stored securely using VS Code's built-in Secret Storage — it is never written to settings.json or any plain-text file.

How to set:

1. Run GitBot: Configurações → select API Key.
2. Paste your key (sk-or-...).
3. Press Enter.

🤖 Model

The OpenRouter model used to generate the commit message.

How to set:

1. Run GitBot: Configurações → select Modelo.
2. A list of available models is fetched live from the OpenRouter API.
3. Search by name or model ID and select.

Alternatively, type the model ID directly (e.g. anthropic/claude-3.5-sonnet, openai/gpt-4o, google/gemini-pro).

Default: anthropic/claude-3.5-sonnet

🌐 Language

Language of the generated commit messages.

Value	Description
PT_BR	Brazilian Portuguese (default)
EN	English

How to set:

1. Run GitBot: Configurações → select Idioma.
2. Choose the desired language.

📝 Custom Prompts

Override the default system prompt with a custom one. Useful when your team uses a different commit convention.

• gitbotcommit.promptPtBr — custom prompt for PT-BR messages.
• gitbotcommit.promptEn — custom prompt for EN messages.

Leave empty to use the built-in default prompt.

How to edit:

1. Run GitBot: Configurações → select Prompt PT-BR or Prompt EN.
2. VS Code Settings will open focused on that field.
3. Edit the multiline text field.

To restore the default, run the same option and select Restaurar prompt padrão.

---

🚀 Usage

Step 1 — Stage your changes

In the Source Control panel (Ctrl+Shift+G), stage the files you want to include in the commit (click the + icon next to each file, or stage all with the + at the top).

Step 2 — Generate the message

Click the ✨ sparkle button at the top of the Source Control panel.

A progress notification will appear while the AI processes your diff.

You can cancel the generation at any time by clicking Cancel in the notification.

Step 3 — Review in the preview panel

A panel opens on the side with the generated message:

Button	Action
Aplicar	Applies the message to the Source Control input box
Copiar	Copies the message to the clipboard
Fechar	Closes the panel without applying

You can also edit the message directly in the preview panel before applying.

Step 4 — Commit

After applying, the commit message is filled in the Source Control input box. Review it and press Ctrl+Enter (or click the ✔ Commit button) to commit.

---

🧠 Customizing the Prompt

The default prompt instructs the AI to:

• Follow Conventional Commits (feat, fix, refactor, etc.)
• Prefix each type with an emoji (✨, 🐛, ♻️, 📝, 🔧, 🧪, 🎨)
• Prioritize the highest-impact type when the diff contains multiple change types
• Keep lines under 72 characters
• Write a body explaining what was done and why

To use a custom prompt, open GitBot: Configurações → Prompt PT-BR (or Prompt EN) and paste your convention in the multiline text field.

Example of a minimal custom prompt in English:

You are a Git commit message generator.
Write a single-line commit message summarizing the diff.
Use imperative mood. Maximum 72 characters. No emojis.

---

❓ FAQ

Q: The ✨ button is not visible in the Source Control panel. A: Make sure you have at least one staged change. The button requires scmProvider == git.

Q: I get "No staged changes found". A: Stage your files first using the + button in the Source Control panel, or run git add in the terminal.

Q: The model list is empty / failed to load. A: Check that your API Key is valid. You can verify it at openrouter.ai/keys. You can also type the model ID manually.

Q: The generated message is cut off or empty. A: Some reasoning models (e.g. DeepSeek R1) return intermediate reasoning before the final answer. GitBot Commit handles this automatically with up to 8 Chain-of-Thought iterations. If the issue persists, try a different model.

Q: Can I use models that are not on OpenRouter? A: Not currently. The extension is built exclusively on the OpenRouter API. Any model available on OpenRouter can be used.

Q: Where is my API Key stored? A: In VS Code's SecretStorage, which is encrypted by the OS keychain. It is never written to settings.json.

---

---

🇧🇷 Português (Brasil)

✨ Funcionalidades

• Geração com um clique — clique no botão ✨ no painel de Source Control para gerar a mensagem a partir das alterações staged.
• Integração com OpenRouter — use qualquer modelo disponível no OpenRouter (Claude, GPT-4o, Gemini, Llama, Mistral e centenas de outros).
• Conventional Commits + Emojis — mensagens seguem o padrão Conventional Commits, com emojis para identificação visual rápida.
• Suporte a Chain-of-Thought — funciona corretamente com modelos de raciocínio (ex: DeepSeek R1, o1) que retornam etapas intermediárias antes da resposta final.
• Bilíngue — gere mensagens em Português (Brasil) ou Inglês.
• Prompt totalmente customizável — substitua o prompt padrão pelo da sua equipe.
• Armazenamento seguro da API Key — sua chave fica no Secret Storage criptografado do VS Code, nunca em texto plano.
• Preview editável — revise, edite, copie ou aplique a mensagem gerada antes de commitar.

---

📋 Requisitos

• VS Code 1.85.0 ou superior
• Uma conta no OpenRouter com API Key — obtenha em openrouter.ai/keys
• Git instalado e disponível no PATH do sistema

---

📦 Instalação

Pelo Marketplace

1. Abra o VS Code.
2. Pressione Ctrl+Shift+X para abrir o painel de extensões.
3. Pesquise GitBot Commit.
4. Clique em Instalar.

Por arquivo .vsix

code --install-extension gitbot-commit-x.x.x.vsix

---

⚙️ Configuração

Todas as configurações ficam acessíveis pelo comando GitBot: Configurações.

Abrindo as Configurações

Três formas de abrir:

Método	Passos
Botão no Source Control	Ctrl+Shift+G → clique no ícone ⚙ na barra do painel
Paleta de Comandos	Ctrl+Shift+P → digite GitBot: Configurações
Settings do VS Code	Ctrl+, → pesquise gitbotcommit

Configurações Disponíveis

🔑 API Key

Sua chave de API do OpenRouter. Armazenada com segurança no Secret Storage do VS Code — nunca escrita no settings.json ou em qualquer arquivo de texto.

Como configurar:

1. Execute GitBot: Configurações → selecione API Key.
2. Cole sua chave (sk-or-...).
3. Pressione Enter.

🤖 Modelo

O modelo do OpenRouter utilizado para gerar a mensagem de commit.

Como configurar:

1. Execute GitBot: Configurações → selecione Modelo.
2. Uma lista de modelos disponíveis é buscada em tempo real da API do OpenRouter.
3. Pesquise pelo nome ou ID do modelo e selecione.

Você também pode digitar o ID do modelo diretamente (ex: anthropic/claude-3.5-sonnet, openai/gpt-4o, google/gemini-pro).

Padrão: anthropic/claude-3.5-sonnet

🌐 Idioma

Idioma das mensagens de commit geradas.

Valor	Descrição
PT_BR	Português (Brasil) — padrão
EN	Inglês

Como configurar:

1. Execute GitBot: Configurações → selecione Idioma.
2. Escolha o idioma desejado.

📝 Prompts Customizados

Substitua o prompt padrão por um personalizado. Útil quando sua equipe utiliza uma convenção diferente de commits.

• gitbotcommit.promptPtBr — prompt customizado para mensagens em PT-BR.
• gitbotcommit.promptEn — prompt customizado para mensagens em EN.

Deixe vazio para usar o prompt padrão embutido.

Como editar:

1. Execute GitBot: Configurações → selecione Prompt PT-BR ou Prompt EN.
2. O VS Code abrirá as configurações focado nesse campo.
3. Edite o campo de texto multilinha.

Para restaurar o padrão, execute a mesma opção e selecione Restaurar prompt padrão.

---

🚀 Como usar

Passo 1 — Faça o stage das alterações

No painel Source Control (Ctrl+Shift+G), adicione ao stage os arquivos que deseja incluir no commit (clique no + ao lado de cada arquivo, ou use o + geral no topo para fazer stage de tudo).

Passo 2 — Gere a mensagem

Clique no botão ✨ (sparkle) no topo do painel Source Control.

Uma notificação de progresso será exibida enquanto a IA processa seu diff.

Você pode cancelar a geração a qualquer momento clicando em Cancel na notificação.

Passo 3 — Revise no painel de preview

Um painel abre ao lado com a mensagem gerada:

Botão	Ação
Aplicar	Preenche a caixa de mensagem do Source Control com o texto gerado
Copiar	Copia a mensagem para a área de transferência
Fechar	Fecha o painel sem aplicar

Você também pode editar a mensagem diretamente no painel antes de aplicar.

Passo 4 — Commite

Após aplicar, a mensagem de commit é preenchida automaticamente na caixa de texto do Source Control. Revise e pressione Ctrl+Enter (ou clique no botão ✔ Commit) para commitar.

---

🧠 Customizando o Prompt

O prompt padrão instrui a IA a:

• Seguir o padrão Conventional Commits (feat, fix, refactor, etc.)
• Prefixar cada tipo com um emoji (✨, 🐛, ♻️, 📝, 🔧, 🧪, 🎨)
• Priorizar o tipo de maior impacto quando o diff contiver múltiplos tipos de mudança
• Manter linhas com no máximo 72 caracteres
• Escrever um body explicando o que foi feito e por quê

Para usar um prompt customizado, abra GitBot: Configurações → Prompt PT-BR (ou Prompt EN) e cole sua convenção no campo de texto multilinha.

Exemplo de prompt customizado minimalista em PT-BR:

Você é um gerador de mensagens de commit Git.
Escreva uma mensagem de uma linha resumindo o diff.
Use modo imperativo. Máximo 72 caracteres. Sem emojis.

---

❓ Perguntas Frequentes

P: O botão ✨ não aparece no painel Source Control. R: Certifique-se de ter pelo menos uma alteração em staged. O botão requer scmProvider == git.

P: Aparece "Nenhuma alteração staged encontrada". R: Faça o stage dos arquivos primeiro usando o botão + no painel Source Control, ou execute git add no terminal.

P: A lista de modelos está vazia / falhou ao carregar. R: Verifique se sua API Key é válida em openrouter.ai/keys. Você também pode digitar o ID do modelo manualmente.

P: A mensagem gerada está incompleta ou vazia. R: Alguns modelos de raciocínio (ex: DeepSeek R1) retornam etapas de raciocínio antes da resposta final. O GitBot Commit trata isso automaticamente com até 8 iterações de Chain-of-Thought. Se o problema persistir, tente outro modelo.

P: Posso usar modelos fora do OpenRouter? R: Não atualmente. A extensão é construída exclusivamente sobre a API do OpenRouter. Qualquer modelo disponível no OpenRouter pode ser utilizado.

P: Onde minha API Key fica armazenada? R: No SecretStorage do VS Code, criptografado pelo keychain do sistema operacional. Nunca é gravada no settings.json.

---

📄 License / Licença

MIT © Felipe Rosa