commitgen

README

commitgen

AI-written commit messages from your staged diff. Local-first, private, and fast.

Features • Installation • Quick Start • Usage • Providers • Configuration • FAQ

---

$ git add .
$ commitgen

  feat(auth): add refresh token rotation

  - rotate refresh tokens on every use to limit replay attacks
  - store token family id so reuse revokes the whole chain

[c]ommit  [e]dit  [r]egenerate  [q]uit (c):

Why commitgen?

You commit many times a day, so writing good messages shouldn't slow you down or send your code to someone else's server.

• Private: it runs against a local model through Ollama by default. Your code stays on your machine.
• Fast: a single static binary with zero dependencies and no runtime to install.
• Your rules: Conventional Commits, your scopes, your language and your team's style.

Features

🔒 Local-first	Works out of the box with Ollama, LM Studio, or llama.cpp. No API key required.
🔌 Any provider	Any OpenAI-compatible API (OpenAI, Groq, OpenRouter, vLLM), plus Anthropic.
🛡️ Secret masking	API keys, tokens, passwords, and private keys are redacted before anything is sent.
🧠 Smart diffs	Skips lockfiles, minified files, and build output. Big diffs are trimmed while keeping every file header.
🎯 Style matching	Learns from your recent commits and branch name to match your repo's conventions.
🪝 Git hook	commitgen hook install, then plain git commit opens with a drafted message.
🎲 Multiple candidates	-n 3 generates three options to pick from.
⚙️ Configurable	Global config plus per-repo .commitgen.toml for scopes, style, language, and custom rules.

Installation

With Go (1.22+)

go install github.com/onetwothird/commitgen@latest

From source

git clone https://github.com/onetwothird/commitgen.git
cd commitgen
go build -o commitgen .         # Windows: go build -o commitgen.exe .

Move the binary to a directory on your PATH.

Adding commitgen to PATH on Windows

$p = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$p;C:\path\to\commitgen", "User")

Restart your terminal afterwards.

Quick Start

1. Get a local model (one-time):

ollama pull qwen2.5-coder:7b

2. Stage your changes and run:

git add -A
commitgen

3. Optional: let git commit do it for you:

commitgen hook install
git commit          # opens your editor with a drafted message

Usage

commitgen [flags]
commitgen hook install | uninstall
commitgen config init | path | show
commitgen version

Flag	Description
-c	Generate, then open git commit in your editor to review
-y	With -c: commit immediately without opening the editor
-p	Print the message only (for scripts and aliases)
-n <num>	Generate several candidates and pick one
-m "<text>"	Give the model extra context, e.g. -m "closes #42"
--dry-run	Show exactly what would be sent to the model, then exit
--model <name>	Override the model
--url <url>	Override the API base URL
--provider <name>	openai or anthropic
--style <name>	conventional or simple
--lang <language>	Language of the message
--max <chars>	Max diff characters sent to the model
--no-redact	Disable secret masking
-v	Verbose output

Tip: add a git alias:

git config --global alias.ai '!commitgen -c'
git ai

Providers

commitgen talks to any OpenAI-compatible endpoint, plus Anthropic's native API.

Provider	base_url	Example model	API key env var
Ollama (default)	http://localhost:11434/v1	qwen2.5-coder:7b	—
LM Studio	http://localhost:1234/v1	(loaded model)	—
OpenAI	https://api.openai.com/v1	gpt-4o-mini	OPENAI_API_KEY
Groq	https://api.groq.com/openai/v1	llama-3.1-8b-instant	COMMITGEN_API_KEY
OpenRouter	https://openrouter.ai/api/v1	meta-llama/llama-3.1-8b-instruct	COMMITGEN_API_KEY
Anthropic	(set provider = "anthropic")	claude-haiku-4-5	ANTHROPIC_API_KEY

Example: OpenAI

# macOS / Linux
export COMMITGEN_BASE_URL=https://api.openai.com/v1
export COMMITGEN_MODEL=gpt-4o-mini
export OPENAI_API_KEY=sk-...

# Windows PowerShell
$env:COMMITGEN_BASE_URL = "https://api.openai.com/v1"
$env:COMMITGEN_MODEL    = "gpt-4o-mini"
$env:OPENAI_API_KEY     = "sk-..."

Example: Anthropic

export COMMITGEN_PROVIDER=anthropic
export COMMITGEN_MODEL=claude-haiku-4-5
export ANTHROPIC_API_KEY=sk-ant-...

Configuration

Create a starter config with:

commitgen config init     # writes the global config
commitgen config path     # shows where it lives
commitgen config show     # shows the effective settings

Add a .commitgen.toml to a repository root to set project rules:

style        = "conventional"
scopes       = ["api", "ui", "cli"]
exclude      = ["*.snap", "docs/generated/*"]
instructions = "Reference the Jira ticket from the branch name, e.g. PROJ-123."

Precedence: defaults → global config → repo .commitgen.toml → environment variables → flags

All options

Key	Default	Description
provider	openai	openai (any OpenAI-compatible API) or anthropic
base_url	http://localhost:11434/v1	API base URL
model	qwen2.5-coder:7b	Model name
api_key	—	Prefer env vars: COMMITGEN_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY
style	conventional	conventional or simple
language	English	Language of the message
max_diff	12000	Max diff characters sent
history	10	Recent commit subjects used for style matching
temperature	0.2	Sampling temperature
timeout	120	Request timeout in seconds
exclude	—	Extra pathspecs to leave out of the diff
scopes	—	Allowed Conventional Commit scopes
instructions	—	Extra rules for the model

Environment variables: COMMITGEN_PROVIDER, COMMITGEN_BASE_URL, COMMITGEN_MODEL, COMMITGEN_API_KEY, COMMITGEN_STYLE, COMMITGEN_LANGUAGE, COMMITGEN_CONFIG.

How it works

git diff --cached  →  filter noise  →  mask secrets  →  build prompt  →  LLM  →  clean output  →  git commit

1. Reads your staged changes only. Nothing unstaged is ever sent.
2. Drops lockfiles, minified assets, and build output, then trims oversized diffs.
3. Redacts anything that looks like a secret.
4. Adds the file summary, branch name, and recent commit subjects for context.
5. Cleans the model's reply (strips code fences, quotes, and preambles) and hands it to git commit.

FAQ

Does my code leave my machine?

Not with the default setup. commitgen talks to a local Ollama server. If you configure a cloud provider, the filtered and redacted diff is sent to that provider. Run commitgen --dry-run to see exactly what would be sent.

Which local model should I use?

qwen2.5-coder:7b is a good default. On machines with less memory, try qwen2.5-coder:3b or llama3.2:3b.

"could not reach http://localhost:11434"

Ollama isn't running. Start the Ollama app or run ollama serve.

Will the git hook block my commits if something fails?

No. If generation fails, the hook exits quietly and git continues as normal. It also skips merges, amends, and commits made with -m.

Development

go test ./...
go vet ./...
go build -o commitgen .

Project layout:

.
├── main.go              # CLI entry point and commands
└── internal/
    ├── config/          # config files and env vars
    ├── git/             # git commands (diff, log, branch)
    ├── llm/             # OpenAI-compatible and Anthropic clients
    ├── prompt/          # prompt building and output cleanup
    └── redact/          # secret masking

Contributing

Contributions are welcome.

1. Fork the repo and create a branch: git checkout -b feat/my-feature
2. Make your changes and add tests
3. Run go test ./...
4. Commit (with commitgen, of course) and open a pull request

License

Released under the MIT License.

Documentation

Overview

commitgen — generate git commit messages from your staged diff with a local or API-based LLM.