git-to-doc 0.2.3

Conventional Commit messages, changelogs & PRs from git diffs using Gemma (local or cloud)

git-to-doc ⚡

Turn a git diff into developer documentation with a local or cloud Gemma model — Conventional Commit messages, markdown changelogs, and pull requests — straight from the terminal.

Install

pip install git-to-doc

Why

Developers write terrible commit messages and skip doc updates. git-to-doc is the plumbing that fixes that: feed it a diff, get back a spec-valid commit, a changelog snippet, and a plain-English summary. It can also write your PRs and auto-fill commit messages via a git hook.

Backend (auto-detected)

• Cloud: set OLLAMA_API_KEY (in a .env or your environment) → uses ollama.com.
• Local: no key → uses a local ollama daemon (localhost:11434).

Commands

# diff → commit message + changelog + plain-English summary (saves to markdown by default)
git-to-doc sample.diff
git-to-doc https://github.com/pallets/flask/pull/5000 --output both
git-to-doc ./diffs/ --output md           # batch a folder
git-to-doc https://github.com/google/jax/pull/123 --output stdout # print to terminal

# generate (and open) a pull request from the current branch
git-to-doc pull-request                              # preview
git-to-doc pull-request --create                     # push + open via gh
git-to-doc pull-request --draft --base develop

# install a git hook so `git commit` (no -m) auto-fills the message
git-to-doc install-hook

# benchmark models (timing; add --judge for rubric quality + CC pass-rate)
git-to-doc-compare sample.diff --models gemma3:4b gemma3:12b --judge gpt-oss:120b

Output Example

For each diff, git-to-doc produces a reviewer-first document:

📄 See a real rendered example → examples/PR-474.md (GitHub renders the callouts, collapsible sections, and code blocks natively)

How it's built for trust

• Self-repair loop — every generated commit is checked against the Conventional Commits spec (validate.py); on failure the exact violations are fed back and the model regenerates. Output is guaranteed spec-valid, not hopeful.
• Structured output — Pydantic schemas force valid JSON from the model.
• Measured, not guessed — git-to-doc-compare --judge scores models with an LLM-as-judge rubric and a deterministic Conventional Commit pass-rate.

Library use

from git_to_doc import analyze_diff, render_full_output
doc = analyze_diff(open("sample.diff").read(), model="gemma4")
print(render_full_output(doc))