git-to-doc 0.2.0__tar.gz → 0.2.2__tar.gz

{git_to_doc-0.2.0 → git_to_doc-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-to-doc
-Version: 0.2.0
+Version: 0.2.2
 Summary: Conventional Commit messages, changelogs & PRs from git diffs using Gemma (local or cloud)
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -9,9 +9,11 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: requests>=2.31
 Requires-Dist: python-dotenv>=1.0
 
-# git-to-doc
+# 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.
+> 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
@@ -33,12 +35,11 @@ Developers write terrible commit messages and skip doc updates. `git-to-doc` is
 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
-cat x.diff | git-to-doc --commit-msg -    # print ONLY the commit message
 
 # generate (and open) a pull request from the current branch
-git-to-doc pr                              # preview
-git-to-doc pr --create                     # push + open via gh
-git-to-doc pr --draft --base develop
+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
@@ -47,6 +48,12 @@ git-to-doc install-hook
 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.

{git_to_doc-0.2.0 → git_to_doc-0.2.2}/README.md

@@ -1,6 +1,8 @@
-# git-to-doc
+# 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.
+> 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
@@ -22,12 +24,11 @@ Developers write terrible commit messages and skip doc updates. `git-to-doc` is
 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
-cat x.diff | git-to-doc --commit-msg -    # print ONLY the commit message
 
 # generate (and open) a pull request from the current branch
-git-to-doc pr                              # preview
-git-to-doc pr --create                     # push + open via gh
-git-to-doc pr --draft --base develop
+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
@@ -36,6 +37,12 @@ git-to-doc install-hook
 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.

{git_to_doc-0.2.0 → git_to_doc-0.2.2}/git_to_doc/cli.py

@@ -1,24 +1,4 @@
-#!/usr/bin/env python3
-"""
-git-to-doc — Conventional Commit messages, changelogs & PRs from git diffs.
-
-Commands:
-  git-to-doc <input> [--output md|json|both] [--model M]   generate commit + changelog
-  git-to-doc <input> --commit-msg                          print ONLY the commit message
-  git-to-doc pr [--base B] [--create] [--draft] [--model M]  generate / open a pull request
-  git-to-doc install-hook                                   auto-fill commit messages via git hook
-
-<input> is a GitHub PR URL, '-' for stdin, a local .diff/.txt file, or a folder of .diff files.
-
-Examples:
-  git-to-doc https://github.com/pallets/flask/pull/5000 --output both
-  git-to-doc sample.diff
-  git diff --cached | git-to-doc --commit-msg -
-  git-to-doc pr --create
-  git-to-doc install-hook
-"""
-
-import sys, re, argparse, time, os, subprocess, tempfile, shutil
+import sys, re, json, argparse, time, os, subprocess, tempfile, shutil, threading, itertools
 from pathlib import Path
 from datetime import date
 from typing import Optional
@@ -78,13 +58,14 @@ def diff_stats(text: str) -> dict:
     return {"files": files, "additions": adds, "deletions": dels}
 
 
-def auto_stem(input_str: str) -> str:
+def auto_stem(input_str: str, model: str) -> str:
     today = date.today().isoformat()
+    clean_model = model.replace(":", "-")
     if is_url(input_str):
         _, slug = normalise_url(input_str)
-        return f"{slug}-changelog-{today}"
+        return f"{slug}-changelog-{clean_model}-{today}"
     p = Path(input_str)
-    return f"{(p.name if p.is_dir() else p.stem)}-changelog-{today}"
+    return f"{(p.name if p.is_dir() else p.stem)}-changelog-{clean_model}-{today}"
 
 
 def _read_source(input_str: str) -> str:
@@ -127,13 +108,30 @@ def process_diff(diff_text: str, stem: str, model: str,
     for f in stats["files"]:
         print(_c(f"    • {f}", DIM))
     print(_c(f"  +{stats['additions']} additions  -{stats['deletions']} deletions", DIM))
-    print()
-    print(_c(f"  ⏳ Sending to {model}…", DIM))
+    done = False
+    def spinner():
+        for char in itertools.cycle(['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']):
+            if done:
+                break
+            sys.stdout.write(f"\r{_c('  ' + char + f' Sending to {model}…', DIM)}")
+            sys.stdout.flush()
+            time.sleep(0.1)
 
     t0 = time.time()
+    t = threading.Thread(target=spinner)
+    t.start()
+    
     result = analyze_diff(diff_text, model=model)
-    print(_c(f"  ⚡ Inference done in {time.time() - t0:.1f}s", DIM))
-    print(render_full_output(result))
+    
+    done = True
+    t.join()
+    sys.stdout.write("\r" + " " * 50 + "\r")  # clear spinner line
+    
+    elapsed = time.time() - t0
+    print(_c(f"  ⚡ Inference done in {elapsed:.1f}s", DIM))
+    
+    if fmt is None:
+        print(render_full_output(result))
 
     if fmt in ("md", "both"):
         md_path = Path(f"{stem}.md")
@@ -159,8 +157,7 @@ def cmd_doc(argv):
         metavar="{md,json,both}",
         help="Save output: 'md' (default when flag used), 'json', or 'both'.")
     parser.add_argument("--model", default="gemma4", help="Ollama model name (default: gemma4)")
-    parser.add_argument("--commit-msg", action="store_true",
-        help="Print ONLY the Conventional Commit message (for git hooks / piping)")
+    parser.add_argument("--commit-msg", action="store_true", help=argparse.SUPPRESS)
     args = parser.parse_args(argv)
 
     if args.commit_msg:
@@ -184,12 +181,13 @@ def cmd_doc(argv):
             print(_c(f"  ⚡ Source: folder ({len(diffs)} diff files)", BOLD))
             for diff_file in diffs:
                 print(_c(f"\n  ── {diff_file.name} ──", BOLD, CYAN))
-                stem = f"{diff_file.stem}-changelog-{date.today().isoformat()}"
+                clean_model = args.model.replace(":", "-")
+                stem = f"{diff_file.stem}-changelog-{clean_model}-{date.today().isoformat()}"
                 process_diff(diff_file.read_text(encoding="utf-8"), stem, args.model, fmt, source=str(diff_file))
         else:
             label = "URL" if is_url(args.input) else ("stdin" if args.input == "-" else Path(args.input).name)
             print(_c(f"  ⚡ Source: {label}", BOLD))
-            process_diff(_read_source(args.input), auto_stem(args.input), args.model, fmt, source=args.input)
+            process_diff(_read_source(args.input), auto_stem(args.input, args.model), args.model, fmt, source=args.input)
     except requests.HTTPError as e:
         code = getattr(e.response, "status_code", "?")
         print(_c(f"\n  ✗ Could not fetch diff (HTTP {code}). Check the PR URL is public.", RED)); sys.exit(1)
@@ -198,10 +196,10 @@ def cmd_doc(argv):
     print()
 
 
-# ── pr: branch diff → PR title + body, optionally opened via gh ────────────────
+# ── pull-request: branch diff → PR title + body, optionally opened via gh ──────
 def cmd_pr(argv):
     parser = argparse.ArgumentParser(
-        prog="git-to-doc pr",
+        prog="git-to-doc pull-request",
         description="Generate (and optionally open) a pull request from the current branch.")
     parser.add_argument("--base", help="base branch (default: auto-detect main/master)")
     parser.add_argument("--model", default="gemma4", help="Ollama model name (default: gemma4)")
@@ -226,10 +224,24 @@ def cmd_pr(argv):
     if not diff_text.strip():
         print(_c(f"  ✗ No changes between {base} and {head}.", RED)); sys.exit(1)
 
-    print(_c("\n  🔀  git-to-doc pr", BOLD, CYAN) + _c(f"  {head} → {base}  ·  {args.model}", DIM))
+    print(_c("\n  🔀  git-to-doc pull-request", BOLD, CYAN) + _c(f"  {head} → {base}  ·  {args.model}", DIM))
     print(_c("  " + "─" * 52, DIM))
-    print(_c("  ⏳ Generating pull request…", DIM))
+    done = False
+    def spinner():
+        for char in itertools.cycle(['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']):
+            if done:
+                break
+            sys.stdout.write(f"\r{_c('  ' + char + f' Generating pull request…', DIM)}")
+            sys.stdout.flush()
+            time.sleep(0.1)
+
+    t = threading.Thread(target=spinner)
+    t.start()
     pr = analyze_pr(diff_text, model=args.model, verbose=True)
+    done = True
+    t.join()
+    sys.stdout.write("\r" + " " * 50 + "\r")
+    
     print(render_pr_full_output(pr))
 
     if not (args.create or args.draft):
@@ -301,10 +313,7 @@ def _top_help():
         Generate a Conventional Commit message + changelog + plain-English summary.
         <input> = a GitHub PR URL, '-' for stdin, a .diff/.txt file, or a folder of .diff files.
 
-    {_c("git-to-doc <input> --commit-msg", BOLD)}
-        Print ONLY the commit message (for piping / git hooks).
-
-    {_c("git-to-doc pr", BOLD)} [--base B] [--create] [--draft] [--model M]
+    {_c("git-to-doc pull-request", BOLD)} [--base B] [--create] [--draft] [--model M]
         Generate a pull request from the current branch. Preview by default;
         --create pushes the branch and opens the PR via gh.
 
@@ -317,8 +326,7 @@ def _top_help():
 {_c("  EXAMPLES", BOLD)}
     git-to-doc sample.diff
     git-to-doc https://github.com/pallets/flask/pull/5000 --output both
-    git diff --cached | git-to-doc --commit-msg -
-    git-to-doc pr --create
+    git-to-doc pull-request --create
 
 {_c("  Run", DIM)} {_c("git-to-doc <command> --help", BOLD)} {_c("for command-specific options.", DIM)}
 """)
@@ -330,7 +338,7 @@ def main():
     if not argv or argv[0] in ("-h", "--help", "help"):
         _top_help()
         return
-    if argv[0] == "pr":
+    if argv[0] in ("pull-request", "pr"):
         return cmd_pr(argv[1:])
     if argv[0] == "install-hook":
         return cmd_install_hook(argv[1:])

{git_to_doc-0.2.0 → git_to_doc-0.2.2}/git_to_doc/evaluate.py

@@ -14,17 +14,16 @@ from git_to_doc.model import _client, _resolve_model
 DEFAULT_JUDGE = "gpt-oss:120b"
 
 RUBRIC = [
-    ("format_compliance", 0.20,
-     "Commit header matches Conventional Commits, valid type, imperative, "
-     "no trailing period, <= 72 chars. 5 = perfect, 1 = not conventional."),
-    ("type_accuracy", 0.15,
-     "type/scope correctly reflect the change. 5 = right, 1 = wrong."),
-    ("semantic_accuracy", 0.30,
+    ("conventional_commit", 0.15,
+     "Commit header matches Conventional Commits, valid type/scope, imperative mood. 5 = perfect, 1 = invalid."),
+    ("semantic_accuracy", 0.25,
      "Truthfully describes the diff, no hallucination/omission. 5 = faithful, 1 = fabricated."),
-    ("conciseness", 0.15,
-     "Terse, free of filler/preamble. 5 = clean, 1 = bloated."),
-    ("changelog_quality", 0.20,
-     "Valid markdown, user-facing, accurate. 5 = useful, 1 = missing/wrong."),
+    ("changelog_quality", 0.15,
+     "Valid markdown, user-facing, accurate changelog entry. 5 = useful, 1 = missing/wrong."),
+    ("plain_english_quality", 0.25,
+     "The 'What changed' section explains the change clearly to a human reader, and file notes accurately summarize file changes. 5 = excellent, 1 = confusing/absent."),
+    ("reviewer_utility", 0.20,
+     "The review notes highlight tricky parts, design decisions, and are highly actionable for reviewers. 5 = highly useful, 1 = generic/empty."),
 ]
 
 

{git_to_doc-0.2.0 → git_to_doc-0.2.2}/git_to_doc/model.py

@@ -63,7 +63,10 @@ def _parse(raw: str, Model):
             return Model.model_validate_json(c)
         except ValidationError as e:
             last_err = e
-    raise last_err
+    
+    if last_err is not None:
+        raise last_err
+    raise ValueError("No valid candidates found for parsing.")
 
 
 # ── Commit document ───────────────────────────────────────────────────────────
@@ -75,24 +78,28 @@ class CommitDoc(BaseModel):
     breaking: bool
     changelog_entry: str
     plain_english: str
+    human_title: str
+    review_notes: str
+    file_notes: dict[str, str]
 
 
 SYSTEM_PROMPT = """
-
-You are an expert Git commit message generator and technical writer.
+You are a senior developer and expert technical writer.
 Given a raw git diff, output ONLY a valid JSON object with no explanation, no markdown fences, no preamble.
 
 Rules for each field:
 - type: one of feat|fix|docs|refactor|perf|test|chore|ci|build|revert
 - scope: lowercase name of the module or folder most affected (null if unclear)
-- subject: imperative mood, lowercase, no trailing period, max 72 chars — be specific
-- body: 1-3 sentences of technical detail for non-trivial changes (null if simple)
+- subject: imperative mood, lowercase, no trailing period, max 72 chars. Write it like a human developer would — natural and specific, not robotic.
+- body: 2-4 sentences of precise technical detail explaining WHAT was changed and WHY. Reference specific function names, file paths, or patterns you see in the diff. Never be vague. null if truly trivial.
 - breaking: true ONLY if existing public API contracts are removed or changed incompatibly
-- changelog_entry: a single markdown bullet like "- feat(scope): description" ready to paste into CHANGELOG.md
-- plain_english: 1-2 sentences a non-technical person could understand explaining WHAT changed and WHY
+- changelog_entry: a user-facing markdown bullet starting with "- " that summarizes the change for a CHANGELOG.md. Be specific and helpful — mention the feature, fix, or improvement by name. For large changes, use multiple sub-bullets with "  - " to break down the key items.
+- plain_english: 3-5 sentences explaining this change to a developer who hasn't seen the code. Cover: (1) what the code did before, (2) what it does now, and (3) why this matters. Use concrete language, not vague summaries. Reference module names and behaviors.
+- human_title: A clear, specific title for the document. Bad: "Code Update". Good: "Refactor: Simplified checkpoint loading to return checkpointer objects directly". The title should tell someone exactly what happened without opening the doc.
+- review_notes: 2-3 paragraphs for code reviewers. Paragraph 1: the overall approach and key design decisions. Paragraph 2: specific areas that need careful review (e.g., edge cases, error handling, concurrency). Paragraph 3 (optional): suggestions for follow-up work or things that were intentionally left out.
+- file_notes: A dictionary mapping up to 10 of the MOST IMPORTANT changed file paths to a 1-sentence summary of what changed in each. Focus on files where the logic actually changed, not config or boilerplate. If the diff has more than 10 files, pick the ones with the most substantive changes.
 
 Output format: raw JSON only. No ```json fences. No commentary.
-
 """
 
 
@@ -138,8 +145,11 @@ def analyze_diff(diff_text: str, model: str = "gemma4", max_retries: int = 3,
     # Fallback — never crash during a demo.
     return CommitDoc(
         type="chore", scope=None, subject="update codebase", body=None,
-        breaking=False, changelog_entry="- chore: miscellaneous updates",
+        breaking=False, changelog_entry="- chore: miscellaneous codebase updates",
         plain_english="General codebase updates were made.",
+        human_title="Maintenance: Codebase Update",
+        review_notes="This is a general maintenance update. No specific review areas identified.",
+        file_notes={}
     )
 
 

{git_to_doc-0.2.0 → git_to_doc-0.2.2}/git_to_doc/renderer.py

@@ -138,67 +138,107 @@ def render_pr_full_output(doc: PRDoc) -> str:
 
 def render_markdown_file(doc: CommitDoc, model: str = "gemma4",
                           source: str = "", stats: dict = None) -> str:
-    """Returns a rich markdown file with metadata, no heading collision."""
-    emoji      = _TYPE_EMOJI.get(doc.type, "📌")
-    commit_msg = render_commit_message(doc)
-    today      = date.today().isoformat()
-    section    = "⚠️ Breaking Changes" if doc.breaking else _SECTION.get(doc.type, "Changed")
-    scope_str  = f"({doc.scope})" if doc.scope else ""
-
-    # Files changed block
-    files_block = ""
-    if stats and stats.get("files"):
-        files_list = "\n".join(f"- `{f}`" for f in stats["files"])
-        files_block = f"""## 📂 Files Changed
-
-{files_list}
-
-**+{stats.get('additions', 0)} additions / -{stats.get('deletions', 0)} deletions**
-
----
+    """Returns a reviewer-first markdown doc: merge-safety callout, clean
+    copy-paste blocks, and collapsible files/metadata sections."""
+    emoji  = _TYPE_EMOJI.get(doc.type, "📌")
+    today  = date.today().isoformat()
+    header = doc.human_title
 
-"""
-
-    source_block = f"> **Source:** {source}\n\n" if source else ""
+    # 1. Merge-safety callout — the first thing a reviewer needs
+    if doc.breaking:
+        callout = ("> [!WARNING]\n"
+                   "> **Breaking change** — review before merging. "
+                   "Existing API behavior changes.")
+    else:
+        callout = "> [!NOTE]\n> **Non-breaking change** — safe to merge."
+
+    # 2. One-line at-a-glance strip
+    n_files  = len(stats["files"]) if stats and stats.get("files") else 0
+    diffstat = f" · +{stats.get('additions', 0)} / -{stats.get('deletions', 0)}" if stats else ""
+    stat_line = (f"`{doc.type}` · scope `{doc.scope or '—'}` · "
+                 f"{n_files} file(s) changed{diffstat} · via git-to-doc + `{model}`")
+
+    # 3. CLEAN copy-paste commit block (nothing decorative inside)
+    scope  = f"({doc.scope})" if doc.scope else ""
+    commit_block = f"{doc.type}{scope}{'!' if doc.breaking else ''}: {doc.subject}"
+    if doc.body:
+        commit_block += f"\n\n{doc.body}"
+    if doc.breaking:
+        commit_block += f"\n\nBREAKING CHANGE: {doc.body or doc.subject}"
 
-    body_block = f"\n> {doc.body}\n" if doc.body else ""
+    # 4. Changelog snippet = section bucket + bullet (paste under Unreleased)
+    section = _SECTION.get(doc.type, "Changed")
+    changelog_block = f"### {section}\n{doc.changelog_entry}"
 
-    return f"""# {emoji} `{doc.type}{scope_str}`: {doc.subject}
+    # 5. Files section — key files with notes shown prominently, rest collapsed
+    files_section = ""
+    if stats and stats.get("files"):
+        noted_lines = []
+        other_lines = []
+        for f in stats["files"]:
+            note = doc.file_notes.get(f)
+            if note:
+                noted_lines.append(f"| `{f}` | {note} |")
+            else:
+                other_lines.append(f"- `{f}`")
+
+        parts = []
+        if noted_lines:
+            parts.append("### Key files\n")
+            parts.append("| File | Change |")
+            parts.append("|------|--------|")
+            parts.extend(noted_lines)
+            parts.append("")
+
+        if other_lines:
+            other_text = "\n".join(other_lines)
+            parts.append(f"<details>\n<summary>Other files changed ({len(other_lines)})</summary>\n")
+            parts.append(other_text)
+            parts.append("\n</details>\n")
+
+        if parts:
+            files_section = "\n".join(parts) + "\n"
+
+    # 6. Review notes
+    review_section = ""
+    if doc.review_notes:
+        review_section = f"## Review notes\n\n{doc.review_notes}\n\n"
+
+    # 7. Metadata (always collapsed)
+    src_row = f"| Source | {source} |\n" if source else ""
+    meta_section = (f"<details>\n<summary>Metadata</summary>\n\n"
+                    f"| Field | Value |\n|-------|-------|\n"
+                    f"| Type | `{doc.type}` |\n"
+                    f"| Scope | `{doc.scope or '—'}` |\n"
+                    f"| Breaking | {'⚠️ Yes' if doc.breaking else 'No'} |\n"
+                    f"| Model | `{model}` |\n{src_row}"
+                    f"| Generated | {today} |\n\n</details>\n")
+
+    return f"""# {emoji} {header}
+
+{callout}
+
+{stat_line}
 
-> Generated by **git-to-doc** using `{model}` on {today}
-{source_block}
 ---
 
-## 🗣️ Plain English Summary
+## What changed
 
 {doc.plain_english}
 
----
-
-## ✅ Conventional Commit Message
+{review_section}## Commit message
 
 ```
-{commit_msg}
+{commit_block}
 ```
 
----
-
-## 📋 Changelog Entry
+## Changelog entry — paste into `CHANGELOG.md`
 
-### {section}
-
-{doc.changelog_entry}
-{body_block}
----
+```markdown
+{changelog_block}
+```
 
-{files_block}## ℹ️ Metadata
+## Files
 
-| Field | Value |
-|-------|-------|
-| Type | `{doc.type}` |
-| Scope | `{doc.scope or "—"}` |
-| Breaking Change | {"⚠️ Yes" if doc.breaking else "No"} |
-| Model | `{model}` |
-| Generated | {today} |
-"""
+{files_section}{meta_section}"""
 

{git_to_doc-0.2.0 → git_to_doc-0.2.2}/git_to_doc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-to-doc
-Version: 0.2.0
+Version: 0.2.2
 Summary: Conventional Commit messages, changelogs & PRs from git diffs using Gemma (local or cloud)
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -9,9 +9,11 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: requests>=2.31
 Requires-Dist: python-dotenv>=1.0
 
-# git-to-doc
+# 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.
+> 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
@@ -33,12 +35,11 @@ Developers write terrible commit messages and skip doc updates. `git-to-doc` is
 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
-cat x.diff | git-to-doc --commit-msg -    # print ONLY the commit message
 
 # generate (and open) a pull request from the current branch
-git-to-doc pr                              # preview
-git-to-doc pr --create                     # push + open via gh
-git-to-doc pr --draft --base develop
+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
@@ -47,6 +48,12 @@ git-to-doc install-hook
 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.

{git_to_doc-0.2.0 → git_to_doc-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "git-to-doc"
-version = "0.2.0"
+version = "0.2.2"
 description = "Conventional Commit messages, changelogs & PRs from git diffs using Gemma (local or cloud)"
 readme = "README.md"
 requires-python = ">=3.9"