Metadata-Version: 2.4
Name: git-to-doc
Version: 0.2.3
Summary: Conventional Commit messages, changelogs & PRs from git diffs using Gemma (local or cloud)
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: ollama>=0.4
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.31
Requires-Dist: python-dotenv>=1.0

# 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

```bash
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

```bash
# 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](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

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