describe

README

describe

A command-line tool that generates git commit messages from staged changes using AI.

How it works

The tool reads your staged git changes, sends them to an AI provider (Ollama, OpenRouter, or Gemini), and returns a formatted commit message in your chosen style.

Installation

go install github.com/perbu/describe@latest

Configuration

Quick Start with Ollama (Default)

1. Install and run Ollama
2. Pull a model: ollama pull llama3.2
3. Run describe - it works out of the box!

Using OpenRouter

Set the OPENROUTER_API_KEY environment variable:

export OPENROUTER_API_KEY="your-api-key"
describe -provider openrouter

Using Gemini

Set the GEMINI_API_KEY environment variable (or GOOGLE_API_KEY):

export GEMINI_API_KEY="your-api-key"
describe -provider gemini

Using vLLM

You can use vLLM's OpenAI-compatible API by using the openrouter provider:

describe -provider openrouter -endpoint http://your-vllm-host:8000/v1 -model your-model-name

Or via config file (see below).

Config File (Optional)

Create a config file at: ~/.config/describe/config.yaml

Ollama example:

provider: ollama
model: llama3.2
commit_style: detailed
api_endpoint: http://localhost:11434
debug: false
max_lines: 10000

OpenRouter example:

provider: openrouter
model: anthropic/claude-4.5-sonnet
commit_style: detailed
api_endpoint: https://openrouter.ai/api/v1
api_key: "your-api-key-here"
debug: false
max_lines: 10000

Gemini example:

provider: gemini
model: gemini-2.0-flash
commit_style: detailed
api_endpoint: https://generativelanguage.googleapis.com/v1beta
api_key: "your-gemini-api-key"
debug: false
max_lines: 10000

vLLM example:

provider: openrouter  # Use openrouter provider for vLLM's OpenAI-compatible API
model: Qwen/Qwen2.5-Coder-32B-Instruct-AWQ  # Your vLLM model name
commit_style: detailed
api_endpoint: http://your-vllm-host:8000/v1
api_key: "not_needed"  # vLLM doesn't require auth by default
debug: false
max_lines: 10000

See config.yaml.example for a complete example.

Commit Message Styles

• detailed (default): classic summary + blank line + explanation body
• conventional: Conventional Commits (type(scope): summary)
• gitmoji: first line starts with a gitmoji code (for example :sparkles:)

Usage

Stage your changes and run:

git add .
describe

Command-line Options

# Use a different model
describe -model codellama

# Use OpenRouter instead of Ollama
describe -provider openrouter -model anthropic/claude-4.5-sonnet

# Use Gemini
describe -provider gemini -model gemini-2.0-flash

# Use a custom endpoint
describe -endpoint http://localhost:8080

# Use Conventional Commits style
describe -style conventional

# Use gitmoji style
describe -style gitmoji

# Enable debug logging
describe -debug

# Adjust maximum lines to process
describe -max-lines 5000

Requirements

• Go 1.24 or later
• Git repository with staged changes
• One of the following AI providers:
  • Ollama installed and running locally (default)
  • OpenRouter API key for cloud-based models
  • Google Gemini API key for cloud-based models
  • vLLM server with OpenAI-compatible API

License

BSD 3-Clause