🪶 gitquill

Privacy-first CLI for AI-generated commit messages & release notes.

Turn your git history into clean, Conventional-Commits-friendly narratives — with any OpenAI-compatible model, including fully local ones via Ollama.

---

✨ Why gitquill?

Writing good commit messages is a chore. Writing good release notes is a chore and a meeting. gitquill does both for you, without shipping your code to a third party if you don't want to.

• 🔒 Privacy-first by default — points at a local Ollama model out of the box. Nothing leaves your machine unless you reconfigure it.
• 🧩 Provider-agnostic — works with OpenAI, Groq, OpenRouter, LM Studio, Together, Mistral, DeepSeek, vLLM, llama.cpp, Jan, or any OpenAI-compatible endpoint.
• 📐 Conventional Commits aware — parses, formats and groups commits by type. Your changelog writes itself.
• 📝 Two commands, that's it — gitquill commit and gitquill release.
• 🪶 Tiny & dependency-light — no heavy TUI, no telemetry, no account.

🚀 Quick start

# 1. Install from npm:
npm install -g gitquill
# 2. (Optional) pull a local model with Ollama
ollama pull qwen2.5-coder:7b
# 3. Make some changes, stage them, and let gitquill write the message
git add .
gitquill commit --yes # or the short alias: gq commit --yes

Prefer a cloud provider?

gitquill config provider openai
gitquill config set provider.apiKey sk-...
gitquill commit

🧰 Commands

gitquill commit

Generate a commit message from staged changes and (optionally) create the commit.

gitquill commit # generate, confirm, commit
gitquill commit --all # stage everything first
gitquill commit -y # commit without prompting
gitquill commit -e # open $EDITOR before committing
gitquill commit --dry-run # just show the message
gitquill commit --language ru # generate in Russian
gitquill commit --no-conventional
gitquill commit --type fix --scope auth # hint type & scope
gitquill commit --max-diff 4000 # cap staged-diff size

gitquill release

Generate Markdown release notes from a commit range.

gitquill release # latest tag → HEAD
gitquill release --from v1.0.0 --to HEAD
gitquill release --tag v1.2.0 --out CHANGELOG.md
gitquill release --flat # no grouping by type
gitquill release --no-header # omit the # project header

gitquill config

Inspect & edit the persistent config at ~/.gitquill/config.json.

gitquill config show
gitquill config path
gitquill config provider ollama # apply a preset
gitquill config set provider.model llama3.1
gitquill config set commit.language es
gitquill config init # write a repo-local .gitquill.json
gitquill config reset

Presets:ollama · openai · groq · openrouter · lmstudio

Repo-local overrides

Run gitquill config init to create a .gitquill.json in your repo. Any field set there wins over your global ~/.gitquill/config.json, so a team can share a preferred model, language, or diff cap without touching anyone's global config. Commit it to share with collaborators.

gitquill doctor

Diagnose your setup — Node version, git binary, repo state, provider connectivity.

gitquill doctor

⚙️ Configuration

Config lives at ~/.gitquill/config.json (override with GITQUILL_CONFIG_DIR).

{
"version": 1,
"provider": {
"name": "ollama",
"baseUrl": "http://localhost:11434/v1",
"apiKey": "ollama",
"model": "qwen2.5-coder:7b",
"temperature": 0.3,
"maxTokens": 512
},
"commit": {
"conventional": true,
"maxLength": 72,
"emitBody": true,
"language": "en",
"maxDiff": 20000
},
"release": {
"groupByType": true,
"includeContributors": true,
"language": "en",
"header": true
}
}

Environment variables

Variable	Purpose
GITQUILL_CONFIG_DIR	Override the config directory.
OPENAI_API_KEY	Used by the openai preset if set.
GROQ_API_KEY	Used by the groq preset if set.
OPENROUTER_API_KEY	Used by the openrouter preset if set.
EDITOR / VISUAL	Editor launched by gitquill commit -e.

🔌 Using a local model (Ollama)

# install: https://ollama.com
ollama serve
ollama pull qwen2.5-coder:7b # or llama3.1, mistral, qwen2.5-coder:14b …
gitquill config provider ollama
gitquill doctor # should report "Provider reachable"
gitquill commit

No API key, no network egress, no per-token cost.

🤝 Contributing

Contributions are welcome and appreciated! See CONTRIBUTING.md for guidelines, the development workflow, and our commit conventions.

Good first issues are labeled good first issue.

🗺️ Roadmap

• Unit tests (vitest) — bun run test
• E2E tests against a mock OpenAI server — bun run test:e2e
• Repo-local .gitquill.json overrides
• --type / --scope commit hints
• npm publish (npm i -g gitquill)
• gitquill pr — draft PR descriptions
• Streaming output for long release notes
• Plug-in prompt templates
• More provider presets (Together, Mistral, DeepSeek, vLLM)

📄 License

MIT © Cryptoteep and contributors. See LICENSE.

💛 Acknowledgements

Inspired by the wonderful work of Conventional Commits, commitlint, Ollama, and every maintainer who has ever dreaded writing release notes on a Friday afternoon.