git-explain 2.1.8__tar.gz → 2.2.0__tar.gz

git_explain-2.2.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: git-explain
+Version: 2.2.0
+Summary: CLI that suggests git add/commit from diffs using Gemini
+Author: nazarli-shabnam
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nazarli-shabnam/git-explain
+Project-URL: Source, https://github.com/nazarli-shabnam/git-explain
+Keywords: git,cli,commit,ai,gemini
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-genai>=1.50.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: prompt_toolkit>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Dynamic: license-file
+
+# git-explain
+
+**Commit message block?** Run this in your repo after you change files. It suggests `git add` and `git commit` lines you can copy—or apply in one step if you want. **Nothing leaves your machine** unless you turn on AI.
+
+[![PyPI](https://img.shields.io/pypi/v/git-explain.svg?label=pypi)](https://pypi.org/project/git-explain/)
+[![GitHub tag](https://img.shields.io/github/v/tag/nazarli-shabnam/git-explain?label=repo)](https://github.com/nazarli-shabnam/git-explain/tags)
+
+
+---
+
+## Install (Python 3.10+)
+
+```bash
+pip install git-explain
+```
+
+**From source** (this repo):
+
+```bash
+pip install -e .
+```
+
+**Clone:** install deps (`requirements.txt` is fine), `cd` into the repo, then:
+
+```bash
+python -m git_explain
+```
+
+Run that from the repo root so Python picks up the `git_explain` folder—no `pip install -e .` needed.
+
+Optional: install a specific tag from GitHub instead of PyPI:
+
+```bash
+pip install "git+https://github.com/nazarli-shabnam/git-explain.git@v2.1.8"
+```
+
+---
+
+## Try it
+
+1. In any git repo, change or add a file (not ignored).
+2. Run:
+   ```bash
+   git-explain
+   ```
+3. Choose what to include (`all` is fine), read the suggestion, answer **`n`** if you only want to copy commands yourself—nothing bad happens.
+
+Heuristics guess a sensible type and message from paths and statuses. **No account, no key, no network** for that path.
+
+Suggested commits follow **[Conventional Commits](https://www.conventionalcommits.org/)**—`feat: …`, `fix: …`, optional `(scope)`, and so on—so changelogs and release tools can read them.
+
+---
+
+## Optional: Gemini
+
+If you want sharper messages, set **`GEMINI_API_KEY`** (or `GOOGLE_API_KEY`) in the environment or a **`.env`** file in the folder where you run the tool.
+
+| Command | In plain terms |
+|--------|----------------|
+| `git-explain --ai` | AI sees **paths and change type** only (no file contents). |
+| `git-explain --ai --with-diff` | AI also sees the **diff**—better detail; only use if you’re OK sending that to the API. |
+| `git-explain --suggest` | **Staged only**; prints one plain `git commit -m "…"` line (easy to copy). Needs AI; don’t combine with other flags. |
+
+Everything else (`--auto`, `--staged-only`, `--cwd`, model override, shell completion): **`git-explain --help`**.
+
+---
+
+## If Gemini complains
+
+- **429 / quota** — wait a bit, or try the default model; see Google’s [rate limits](https://ai.google.dev/gemini-api/docs/rate-limits).
+- **404 / model not found** — set something current, e.g. **`GEMINI_MODEL=gemini-2.5-flash`**, and check their [model list](https://ai.google.dev/api/models).
+
+---
+
+## Developers
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```

git_explain-2.2.0/README.md

@@ -0,0 +1,80 @@
+# git-explain
+
+**Commit message block?** Run this in your repo after you change files. It suggests `git add` and `git commit` lines you can copy—or apply in one step if you want. **Nothing leaves your machine** unless you turn on AI.
+
+[![PyPI](https://img.shields.io/pypi/v/git-explain.svg?label=pypi)](https://pypi.org/project/git-explain/)
+[![GitHub tag](https://img.shields.io/github/v/tag/nazarli-shabnam/git-explain?label=repo)](https://github.com/nazarli-shabnam/git-explain/tags)
+
+
+---
+
+## Install (Python 3.10+)
+
+```bash
+pip install git-explain
+```
+
+**From source** (this repo):
+
+```bash
+pip install -e .
+```
+
+**Clone:** install deps (`requirements.txt` is fine), `cd` into the repo, then:
+
+```bash
+python -m git_explain
+```
+
+Run that from the repo root so Python picks up the `git_explain` folder—no `pip install -e .` needed.
+
+Optional: install a specific tag from GitHub instead of PyPI:
+
+```bash
+pip install "git+https://github.com/nazarli-shabnam/git-explain.git@v2.1.8"
+```
+
+---
+
+## Try it
+
+1. In any git repo, change or add a file (not ignored).
+2. Run:
+   ```bash
+   git-explain
+   ```
+3. Choose what to include (`all` is fine), read the suggestion, answer **`n`** if you only want to copy commands yourself—nothing bad happens.
+
+Heuristics guess a sensible type and message from paths and statuses. **No account, no key, no network** for that path.
+
+Suggested commits follow **[Conventional Commits](https://www.conventionalcommits.org/)**—`feat: …`, `fix: …`, optional `(scope)`, and so on—so changelogs and release tools can read them.
+
+---
+
+## Optional: Gemini
+
+If you want sharper messages, set **`GEMINI_API_KEY`** (or `GOOGLE_API_KEY`) in the environment or a **`.env`** file in the folder where you run the tool.
+
+| Command | In plain terms |
+|--------|----------------|
+| `git-explain --ai` | AI sees **paths and change type** only (no file contents). |
+| `git-explain --ai --with-diff` | AI also sees the **diff**—better detail; only use if you’re OK sending that to the API. |
+| `git-explain --suggest` | **Staged only**; prints one plain `git commit -m "…"` line (easy to copy). Needs AI; don’t combine with other flags. |
+
+Everything else (`--auto`, `--staged-only`, `--cwd`, model override, shell completion): **`git-explain --help`**.
+
+---
+
+## If Gemini complains
+
+- **429 / quota** — wait a bit, or try the default model; see Google’s [rate limits](https://ai.google.dev/gemini-api/docs/rate-limits).
+- **404 / model not found** — set something current, e.g. **`GEMINI_MODEL=gemini-2.5-flash`**, and check their [model list](https://ai.google.dev/api/models).
+
+---
+
+## Developers
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```

git_explain-2.2.0/git_explain/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.2.0"

git_explain-2.2.0/git_explain/__main__.py

@@ -0,0 +1,3 @@
+from git_explain.cli import app
+
+app()

{git_explain-2.1.8 → git_explain-2.2.0}/git_explain/cli.py

@@ -1,7 +1,8 @@
 """CLI for git-explain: suggest and optionally apply commit message from diffs."""
 
+import re
 import subprocess
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Iterable
 
@@ -11,14 +12,18 @@ from rich.console import Console
 from rich.panel import Panel
 from rich.text import Text
 
-from git_explain.gemini import suggest_commands
+from git_explain.gemini import Suggestion, suggest_commands
 from git_explain.heuristics import suggest_from_changes
 from git_explain.git import (
     get_combined_diff,
     get_diff_for_paths,
     get_staged_diff_for_paths,
 )
-from git_explain.run import apply_commands
+from git_explain.run import (
+    apply_commands,
+    format_commit_message,
+    normalize_commit_subject_for_dash_m,
+)
 
 load_dotenv()
 app = typer.Typer()
@@ -55,9 +60,8 @@ def _parse_combined(combined: str) -> tuple[bool | None, list[Change]]:
             if v in ("true", "false"):
                 has_commits = v == "true"
             continue
-        m = __import__("re").match(
-            r"^([AMDRC])\s+(.+)$", line, __import__("re").IGNORECASE
-        )
+        # A/M/D/R/C: add/modify/delete/rename/copy; T: type change; U: unmerged (git name-status)
+        m = re.match(r"^([AMDRCUT])\s+(.+)$", line, re.IGNORECASE)
         if not m:
             continue
         status = m.group(1).upper()
@@ -343,13 +347,11 @@ def run(
             )
             raise typer.Exit(1)
 
-        console.print(
-            Panel(
-                f'git commit -m "[{sug.commit_type}] {sug.commit_message}"',
-                title="Suggested commit command",
-                border_style="green",
-            )
+        cmsg = normalize_commit_subject_for_dash_m(sug.commit_message)
+        full = format_commit_message(
+            sug.commit_type, cmsg, scope=sug.scope, breaking=sug.breaking
         )
+        print(f'git commit -m "{full}"')
         return
 
     if staged_only:
@@ -421,9 +423,8 @@ def run(
 
     def suggest_for(
         change_items: list[tuple[str, str]], title: str
-    ) -> tuple[list[str], str, str, str, str | None]:
-        # Returns (paths, type, message, raw_text, ai_fallback_reason).
-        # ai_fallback_reason is set when --ai was used but heuristics were used instead.
+    ) -> tuple[Suggestion, str | None]:
+        """Return (suggestion, ai_fallback_reason)."""
         paths_for_infer = [p for _, p in change_items]
         infer_diff: str | None = None
         if paths_for_infer:
@@ -443,7 +444,7 @@ def run(
                 if diff_text:
                     payload = payload + "\n\n## Diff\n" + diff_text
             try:
-                sug, raw = suggest_commands(
+                sug, _raw = suggest_commands(
                     payload,
                     model=model,
                     with_diff=with_diff,
@@ -451,27 +452,20 @@ def run(
                 )
                 if sug is None:
                     raise RuntimeError("Could not parse AI suggestion.")
-                return sug.add_args, sug.commit_type, sug.commit_message, raw, None
+                return sug, None
             except Exception as e:
-                # Fall back to heuristics on quota / API errors
                 h = suggest_from_changes(
                     changes=change_items,
                     has_commits=has_commits,
                     diff_text=infer_diff,
                 )
-                return (
-                    h.add_args,
-                    h.commit_type,
-                    h.commit_message,
-                    "",
-                    str(e),
-                )
+                return h, str(e)
         h = suggest_from_changes(
             changes=change_items,
             has_commits=has_commits,
             diff_text=infer_diff,
         )
-        return h.add_args, h.commit_type, h.commit_message, "", None
+        return h, None
 
     selected_pairs = [(ch.status, ch.path) for ch in selected]
     unique_paths = {p for _, p in selected_pairs}
@@ -491,18 +485,18 @@ def run(
             if mode_input in ("one", "split"):
                 mode = mode_input
 
-    plan: list[tuple[str, list[str], str, str]] = []
+    plan: list[tuple[str, Suggestion]] = []
     ai_fallback_notes: list[tuple[str, str]] = []
     if mode == "split":
         groups = _group_changes(selected_pairs)
         for gname, items in groups.items():
-            paths, ctype, cmsg, _raw, fb = suggest_for(items, title=gname.capitalize())
-            plan.append((gname, paths, ctype, cmsg))
+            sug, fb = suggest_for(items, title=gname.capitalize())
+            plan.append((gname, sug))
             if fb:
                 ai_fallback_notes.append((gname, fb))
     else:
-        paths, ctype, cmsg, _raw, fb = suggest_for(selected_pairs, title="Selected")
-        plan.append(("one", paths, ctype, cmsg))
+        sug, fb = suggest_for(selected_pairs, title="Selected")
+        plan.append(("one", sug))
         if fb:
             ai_fallback_notes.append(("", fb))
 
@@ -529,11 +523,15 @@ def run(
             )
         )
 
-    def _render_plan(pl: list[tuple[str, list[str], str, str]]) -> str:
+    def _render_plan(pl: list[tuple[str, Suggestion]]) -> str:
         rendered: list[str] = []
-        for name, paths, ctype, cmsg in pl:
-            add_line = "git add -A -- " + " ".join(_ps_quote(p) for p in paths)
-            commit_line = f'git commit -m "[{ctype}] {cmsg}"'
+        for name, sug in pl:
+            add_line = "git add -A -- " + " ".join(_ps_quote(p) for p in sug.add_args)
+            subj = normalize_commit_subject_for_dash_m(sug.commit_message)
+            full = format_commit_message(
+                sug.commit_type, subj, scope=sug.scope, breaking=sug.breaking
+            )
+            commit_line = f'git commit -m "{full}"'
             rendered.append(f"### {name}\n{add_line}\n{commit_line}")
         return "\n\n".join(rendered)
 
@@ -555,29 +553,35 @@ def run(
             .lower()
         )
         if edit_choice in ("y", "yes"):
-            updated: list[tuple[str, list[str], str, str]] = []
-            for name, paths, ctype, cmsg in plan:
+            updated: list[tuple[str, Suggestion]] = []
+            for name, sug in plan:
+                current = format_commit_message(
+                    sug.commit_type,
+                    sug.commit_message,
+                    scope=sug.scope,
+                    breaking=sug.breaking,
+                )
                 console.print(
-                    f"[dim]{name}:[/dim] current message: [bold][{ctype}] {cmsg}[/bold]"
+                    f"[dim]{name}:[/dim] current message: [bold]{current}[/bold]"
                 )
                 try:
                     from prompt_toolkit import prompt as pt_prompt
 
                     new_msg = (
                         pt_prompt(
-                            "New commit message (subject only, no [TYPE] prefix): ",
-                            default=cmsg,
+                            "New commit message (subject only, type/scope added automatically): ",
+                            default=sug.commit_message,
                         ).strip()
-                        or cmsg
+                        or sug.commit_message
                     )
                 except Exception:
                     new_msg = (
                         typer.prompt(
-                            "New commit message (subject only, no [TYPE] prefix)",
-                            default=cmsg,
+                            "New commit message (subject only, type/scope added automatically)",
+                            default=sug.commit_message,
                         ).strip()
-                    ) or cmsg
-                updated.append((name, paths, ctype, new_msg))
+                    ) or sug.commit_message
+                updated.append((name, replace(sug, commit_message=new_msg)))
             plan = updated
             console.print(
                 Panel(
@@ -599,13 +603,16 @@ def run(
         do_apply = choice == "auto" or choice in ("y", "yes")
 
     if do_apply:
-        for name, paths, ctype, cmsg in plan:
+        for name, sug in plan:
             try:
                 apply_commands(
                     repo_root,
-                    [] if staged_only else paths,
-                    ctype,
-                    cmsg,
+                    [] if staged_only else sug.add_args,
+                    sug.commit_type,
+                    sug.commit_message,
+                    scope=sug.scope,
+                    body=sug.body,
+                    breaking=sug.breaking,
                     staged_only=staged_only,
                 )
                 console.print(f"[green]Commit created ({name}).[/green]")

{git_explain-2.1.8 → git_explain-2.2.0}/git_explain/commit_infer.py

@@ -47,7 +47,7 @@ def refine_type_and_message_from_diff(
     when the diff matches known bugfix patterns.
     """
     ct = (commit_type or "").upper()
-    if ct in ("DOCS", "TEST", "TESTS", "CHORE"):
+    if ct in ("DOCS", "TEST", "TESTS", "CHORE", "BUILD", "CI", "STYLE", "PERF"):
         return commit_type, commit_message
 
     subject = infer_fix_subject_from_diff(diff_text)