🪶 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.