git-explain 2.2.1__tar.gz → 2.5.0__tar.gz

git_explain-2.5.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: git-explain
+Version: 2.5.0
+Summary: CLI that suggests git add/commit from diffs using Gemini
+Author: nazarli-shabnam
+Author-email: shabnamnezerli@gmail.com
+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: Programming Language :: Python :: 3.13
+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.12.3; extra == "dev"
+Dynamic: license-file
+
+# git-explain
+
+Suggests **conventional** `git add` / `git commit` messages from your changes. Uses AI when you configure a key; otherwise uses simple local rules.
+
+[![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 and upgrade
+
+```bash
+pip install git-explain
+pip install --upgrade git-explain
+```
+
+Use the second command anytime you want the latest release from PyPI.
+
+In a terminal, go to your project folder (the one that contains `.git`) and run:
+
+```bash
+git-explain
+```
+
+The first time you run it without `AI_MODEL` in `.env`, the tool can create `.env` with a default Gemini model and a link to create an API key.
+
+---
+
+## Configure (`.env`)
+
+Put a file named **`.env` in the repo root** (next to `.git`). Typical variables:
+
+| Variable | Role |
+|----------|------|
+| `AI_MODEL` | Gemini model id, e.g. `gemini-2.5-flash`. Set on first run if missing. |
+| `AI_API_KEY` | From [Google AI Studio](https://aistudio.google.com/apikey). |
+| `AI_MODEL_FALLBACKS` | Optional: comma-separated backup models, tried **in order** after `AI_MODEL` on retryable busy/rate-limit errors. If you omit this variable, the tool uses the **default fallbacks** below. |
+
+**Default `AI_MODEL_FALLBACKS` (when the variable is unset):** `gemini-2.5-flash-lite`, then `gemini-3-flash-preview` — each is tried in sequence after a failed attempt on the previous model in the chain (starting from `AI_MODEL`).
+
+If `AI_API_KEY` is empty, **`GEMINI_API_KEY`** is still read (same key, older name).
+
+---
+
+## Flags
+
+| | |
+|--|--|
+| `--auto` | Apply suggested commands without a confirmation prompt. |
+| `--staged-only` | Work with staged changes only (no `git add` from the tool). |
+| `--cwd` | Use another directory as the git repo root. |
+| `--model` | Override the AI model for this run (defaults to `AI_MODEL` from the repo `.env`). |
+| `--with-diff` | Send the full diff to the AI (more context). |
+| `--suggest` | Print one suggested `git commit -m "…"` line (staged, AI only). |
+
+If you pick **more than one changed file**, you can choose **one** commit or **split** into several (split is not available with `--staged-only`). **Enter** applies the suggestion; **n** skips so you can copy instead.
+
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, optional scope, etc.).
+
+---
+
+## When AI fails
+
+Wrong key, bad model name, network issues, or quota errors → the tool falls back to local heuristics and shows a warning. On retryable busy/rate-limit errors it steps through the fallback chain: your `AI_MODEL` first, then the models in `AI_MODEL_FALLBACKS` (or the **default** `gemini-2.5-flash-lite` → `gemini-3-flash-preview` list if that variable is unset).
+
+---
+
+## Install a specific version from GitHub
+
+```bash
+pip install "git+https://github.com/nazarli-shabnam/git-explain.git@v2.3.0"
+pip install "git+https://github.com/nazarli-shabnam/git-explain.git@v2.4.0"
+```
+
+Replace `v2.3.0` with the [tag](https://github.com/nazarli-shabnam/git-explain/tags) you want.
+
+---
+
+## Develop
+
+From a clone of this repo:
+
+```bash
+pip install -r requirements.txt
+python -m git_explain
+```
+
+Contributors: `pip install -e ".[dev]"` then `pytest -q`, `ruff check .`, `ruff format --check .`.
+

git_explain-2.5.0/README.md

@@ -0,0 +1,89 @@
+# git-explain
+
+Suggests **conventional** `git add` / `git commit` messages from your changes. Uses AI when you configure a key; otherwise uses simple local rules.
+
+[![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 and upgrade
+
+```bash
+pip install git-explain
+pip install --upgrade git-explain
+```
+
+Use the second command anytime you want the latest release from PyPI.
+
+In a terminal, go to your project folder (the one that contains `.git`) and run:
+
+```bash
+git-explain
+```
+
+The first time you run it without `AI_MODEL` in `.env`, the tool can create `.env` with a default Gemini model and a link to create an API key.
+
+---
+
+## Configure (`.env`)
+
+Put a file named **`.env` in the repo root** (next to `.git`). Typical variables:
+
+| Variable | Role |
+|----------|------|
+| `AI_MODEL` | Gemini model id, e.g. `gemini-2.5-flash`. Set on first run if missing. |
+| `AI_API_KEY` | From [Google AI Studio](https://aistudio.google.com/apikey). |
+| `AI_MODEL_FALLBACKS` | Optional: comma-separated backup models, tried **in order** after `AI_MODEL` on retryable busy/rate-limit errors. If you omit this variable, the tool uses the **default fallbacks** below. |
+
+**Default `AI_MODEL_FALLBACKS` (when the variable is unset):** `gemini-2.5-flash-lite`, then `gemini-3-flash-preview` — each is tried in sequence after a failed attempt on the previous model in the chain (starting from `AI_MODEL`).
+
+If `AI_API_KEY` is empty, **`GEMINI_API_KEY`** is still read (same key, older name).
+
+---
+
+## Flags
+
+| | |
+|--|--|
+| `--auto` | Apply suggested commands without a confirmation prompt. |
+| `--staged-only` | Work with staged changes only (no `git add` from the tool). |
+| `--cwd` | Use another directory as the git repo root. |
+| `--model` | Override the AI model for this run (defaults to `AI_MODEL` from the repo `.env`). |
+| `--with-diff` | Send the full diff to the AI (more context). |
+| `--suggest` | Print one suggested `git commit -m "…"` line (staged, AI only). |
+
+If you pick **more than one changed file**, you can choose **one** commit or **split** into several (split is not available with `--staged-only`). **Enter** applies the suggestion; **n** skips so you can copy instead.
+
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, optional scope, etc.).
+
+---
+
+## When AI fails
+
+Wrong key, bad model name, network issues, or quota errors → the tool falls back to local heuristics and shows a warning. On retryable busy/rate-limit errors it steps through the fallback chain: your `AI_MODEL` first, then the models in `AI_MODEL_FALLBACKS` (or the **default** `gemini-2.5-flash-lite` → `gemini-3-flash-preview` list if that variable is unset).
+
+---
+
+## Install a specific version from GitHub
+
+```bash
+pip install "git+https://github.com/nazarli-shabnam/git-explain.git@v2.3.0"
+pip install "git+https://github.com/nazarli-shabnam/git-explain.git@v2.4.0"
+```
+
+Replace `v2.3.0` with the [tag](https://github.com/nazarli-shabnam/git-explain/tags) you want.
+
+---
+
+## Develop
+
+From a clone of this repo:
+
+```bash
+pip install -r requirements.txt
+python -m git_explain
+```
+
+Contributors: `pip install -e ".[dev]"` then `pytest -q`, `ruff check .`, `ruff format --check .`.
+

git_explain-2.5.0/git_explain/__init__.py

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

{git_explain-2.2.1 → git_explain-2.5.0}/git_explain/cli.py

@@ -1,18 +1,23 @@
 """CLI for git-explain: suggest and optionally apply commit message from diffs."""
 
+import os
 import re
 import subprocess
 from dataclasses import dataclass, replace
 from pathlib import Path
+from collections.abc import Callable
 from typing import Iterable
 
+import httpx
+import requests
 import typer
-from dotenv import load_dotenv
+from dotenv import dotenv_values
+from google.genai import errors as genai_errors
 from rich.console import Console
 from rich.panel import Panel
 from rich.text import Text
 
-from git_explain.gemini import Suggestion, suggest_commands
+from git_explain.gemini import DEFAULT_MODEL, Suggestion, suggest_commands
 from git_explain.heuristics import suggest_from_changes
 from git_explain.git import (
     get_combined_diff,
@@ -25,11 +30,70 @@ from git_explain.run import (
     normalize_commit_subject_for_dash_m,
 )
 
-load_dotenv()
 app = typer.Typer()
 console = Console()
 
 _DIFF_INFER_MAX_CHARS = 50_000
+_AI_ENV_KEYS = (
+    "AI_MODEL",
+    "AI_API_KEY",
+    "GEMINI_API_KEY",
+    "AI_MODEL_FALLBACKS",
+)
+# Terminal hyperlinks (OSC 8) for first-run setup — Ctrl+click in supported terminals.
+_GOOGLE_AI_API_KEY_URL = "https://aistudio.google.com/apikey"
+
+# Expected failure modes from an AI call: missing key / unparseable response
+# (RuntimeError), Gemini API errors, and network-level failures. Anything else
+# is a real bug and should not be silently treated as "AI unavailable".
+_AI_CALL_ERRORS = (
+    RuntimeError,
+    genai_errors.APIError,
+    httpx.HTTPError,
+    requests.exceptions.RequestException,
+)
+
+
+def _gemini_fallback_notifier(
+    group_label: str | None = None,
+) -> Callable[[str], None]:
+    """Dim one-line notices when switching models after rate limits / overload.
+
+    ``group_label`` prefixes the line in split-commit mode (one AI call per group),
+    so repeated "primary busy" messages are distinguishable.
+    """
+    first: list[bool] = [True]
+    prefix = f"{group_label}: " if group_label else ""
+
+    def _notify(next_model: str) -> None:
+        if first[0]:
+            console.print(
+                Text(
+                    f"{prefix}Primary model busy; trying fallback: {next_model}",
+                    style="dim",
+                )
+            )
+            first[0] = False
+        else:
+            console.print(
+                Text(f"{prefix}Model busy; trying fallback: {next_model}", style="dim")
+            )
+
+    return _notify
+
+
+def _model_picker_line(
+    num: int, label: str, link_url: str, model_id: str | None = None
+) -> Text:
+    """OSC 8 link on `label`; optional cyan tail in parentheses (e.g. model id)."""
+    line = Text()
+    line.append(f"  {num}. ")
+    line.append(label, style=f"link {link_url}")
+    if model_id:
+        line.append(" (")
+        line.append(model_id, style="cyan")
+        line.append(")")
+    return line
 
 
 @dataclass(frozen=True)
@@ -89,6 +153,87 @@ def _parse_combined(combined: str) -> tuple[bool | None, list[Change]]:
     return has_commits, changes
 
 
+def _load_ai_env_from_dotenv(dotenv_path: Path) -> None:
+    """Load only AI-related vars from .env, overriding existing process values."""
+    values = dotenv_values(dotenv_path)
+    for key in _AI_ENV_KEYS:
+        raw = values.get(key)
+        if raw is None:
+            continue
+        val = str(raw).strip()
+        if val:
+            os.environ[key] = val
+
+
+def _upsert_env_var(dotenv_path: Path, key: str, value: str) -> None:
+    lines: list[str] = []
+    if dotenv_path.exists():
+        lines = dotenv_path.read_text(encoding="utf-8").splitlines()
+    replaced = False
+    out: list[str] = []
+    prefix = key + "="
+    for ln in lines:
+        if ln.startswith(prefix):
+            out.append(f"{key}={value}")
+            replaced = True
+        else:
+            out.append(ln)
+    if not replaced:
+        if out and out[-1].strip():
+            out.append("")
+        out.append(f"{key}={value}")
+    dotenv_path.write_text("\n".join(out) + "\n", encoding="utf-8")
+
+
+def _ensure_repo_env_file(repo_env: Path) -> bool:
+    if repo_env.is_file():
+        return True
+    create = (
+        typer.prompt("No .env found. Create one now? (y/n)", default="y")
+        .strip()
+        .lower()
+    )
+    if create not in ("y", "yes"):
+        return False
+    repo_env.write_text("", encoding="utf-8")
+    return True
+
+
+def _choose_and_persist_ai_model(repo_env: Path) -> str:
+    """First run: set default Gemini model and reload .env for API keys."""
+    console.print(
+        Text(
+            "Add your API key to .env (create one in Google AI Studio if needed):",
+            style="dim",
+        )
+    )
+    console.print(
+        _model_picker_line(
+            1,
+            "Google AI Studio",
+            _GOOGLE_AI_API_KEY_URL,
+            model_id=DEFAULT_MODEL,
+        )
+    )
+    model = DEFAULT_MODEL
+    _upsert_env_var(repo_env, "AI_MODEL", model)
+    os.environ["AI_MODEL"] = model
+    if repo_env.is_file():
+        _load_ai_env_from_dotenv(repo_env)
+    return model
+
+
+def _resolve_project_ai_model(repo_env: Path, model_override: str | None) -> str | None:
+    if model_override:
+        return model_override
+    model = (os.environ.get("AI_MODEL") or "").strip()
+    if model:
+        return model
+    if not _ensure_repo_env_file(repo_env):
+        return None
+    return _choose_and_persist_ai_model(repo_env)
+
+
 def _render_combined(
     has_commits: bool | None, items: Iterable[tuple[str, str]], title: str
 ) -> str:
@@ -199,7 +344,6 @@ def _validate_suggest_flags(
     *,
     suggest: bool,
     auto: bool,
-    ai: bool,
     staged_only: bool,
     model: str | None,
     with_diff: bool,
@@ -209,14 +353,10 @@ def _validate_suggest_flags(
     bad: list[str] = []
     if auto:
         bad.append("--auto")
-    if ai:
-        bad.append("--ai")
     if staged_only:
         bad.append("--staged-only")
     if with_diff:
         bad.append("--with-diff")
-    if model is not None:
-        bad.append("--model")
     if bad:
         raise typer.BadParameter(
             "--suggest is a dedicated mode and cannot be combined with: "
@@ -230,9 +370,6 @@ def main(
     auto: bool = typer.Option(
         False, "--auto", help="Apply suggestion without prompting"
     ),
-    ai: bool = typer.Option(
-        False, "--ai", help="Use Gemini to suggest commit message (default: off)"
-    ),
     staged_only: bool = typer.Option(
         False,
         "--staged-only",
@@ -244,15 +381,12 @@ def main(
     model: str | None = typer.Option(
         None,
         "--model",
-        help=(
-            "Override Gemini model name for --ai "
-            "(defaults to GEMINI_MODEL env var or internal default)."
-        ),
+        help="Override AI model for this run (defaults to AI_MODEL from repo .env).",
     ),
     with_diff: bool = typer.Option(
         False,
         "--with-diff",
-        help="With --ai: send full diff to the model for detailed, specific commit messages (opt-in).",
+        help="Send full diff to the configured AI model for more specific messages (opt-in).",
     ),
     suggest: bool = typer.Option(
         False,
@@ -265,7 +399,6 @@ def main(
     _validate_suggest_flags(
         suggest=suggest,
         auto=auto,
-        ai=ai,
         staged_only=staged_only,
         model=model,
         with_diff=with_diff,
@@ -273,7 +406,6 @@ def main(
     run(
         cwd=Path(cwd) if cwd else None,
         auto=auto,
-        ai=ai,
         staged_only=staged_only,
         model=model,
         with_diff=with_diff,
@@ -284,32 +416,29 @@ def main(
 def run(
     cwd: Path | None = None,
     auto: bool = False,
-    ai: bool = False,
     staged_only: bool = False,
     model: str | None = None,
     with_diff: bool = False,
     suggest: bool = False,
 ) -> None:
     console.print(Text("git-explain", style="bold"))
-    if with_diff and not ai:
-        console.print(
-            "[yellow]Warning:[/yellow] --with-diff has no effect without --ai. "
-            "It only affects AI-generated commit messages."
-        )
-        enable = typer.prompt("Enable AI? (y/n)", default="n").strip().lower()
-        if enable in ("y", "yes"):
-            ai = True
-        else:
-            with_diff = False
 
     try:
         combined, repo_root = get_combined_diff(cwd=cwd)
     except RuntimeError as e:
         console.print(f"[red]Error:[/red] {e}")
         raise typer.Exit(1)
+
+    repo_env = repo_root / ".env"
+    if repo_env.is_file():
+        _load_ai_env_from_dotenv(repo_env)
+
     if not combined.strip():
         console.print("[yellow]No staged, unstaged, or untracked changes.[/yellow]")
         return
+    ai_model = _resolve_project_ai_model(repo_env, model)
+    if repo_env.is_file():
+        _load_ai_env_from_dotenv(repo_env)
     has_commits, changes = _parse_combined(combined)
     console.print(Panel(combined, title="Changed files", border_style="dim"))
 
@@ -332,12 +461,19 @@ def run(
             if len(staged_diff) > _DIFF_INFER_MAX_CHARS
             else staged_diff
         )
+        if not ai_model:
+            console.print(
+                "[red]Error:[/red] --suggest requires an AI model. "
+                "Set AI_MODEL in repo .env or pass --model."
+            )
+            raise typer.Exit(1)
         try:
             sug, _raw = suggest_commands(
                 payload,
-                model=None,
+                model=ai_model,
                 with_diff=bool(staged_diff),
                 unified_diff_for_infer=infer_diff,
+                fallback_notifier=_gemini_fallback_notifier(),
             )
             if sug is None:
                 raise RuntimeError("Could not parse AI suggestion.")
@@ -436,7 +572,7 @@ def run(
                     else raw_d
                 )
 
-        if ai:
+        if ai_model:
             payload = _render_combined(has_commits, change_items, title=title)
             if with_diff:
                 paths_for_diff = [p for _, p in change_items]
@@ -444,16 +580,18 @@ def run(
                 if diff_text:
                     payload = payload + "\n\n## Diff\n" + diff_text
             try:
+                fb_label = title if mode == "split" else None
                 sug, _raw = suggest_commands(
                     payload,
-                    model=model,
+                    model=ai_model,
                     with_diff=with_diff,
                     unified_diff_for_infer=infer_diff,
+                    fallback_notifier=_gemini_fallback_notifier(fb_label),
                 )
                 if sug is None:
                     raise RuntimeError("Could not parse AI suggestion.")
                 return sug, None
-            except Exception as e:
+            except _AI_CALL_ERRORS as e:
                 h = suggest_from_changes(
                     changes=change_items,
                     has_commits=has_commits,
@@ -500,9 +638,10 @@ def run(
         if fb:
             ai_fallback_notes.append(("", fb))
 
-    if ai and ai_fallback_notes:
+    if ai_model and ai_fallback_notes:
+        key_help = "Check AI_API_KEY, AI_MODEL, AI_MODEL_FALLBACKS, quota/model availability, and network."
         lines = [
-            "[bold]You used --ai, but Gemini was not used for the suggestion below.[/bold]",
+            "[bold]Configured AI was not used for the suggestion below.[/bold]",
             "Commit message(s) come from [bold]local heuristics[/bold] instead.",
             "",
         ]
@@ -512,9 +651,7 @@ def run(
         else:
             lines.append(ai_fallback_notes[0][1])
         lines.append("")
-        lines.append(
-            "[dim]Check API key (GEMINI_API_KEY / GOOGLE_API_KEY), quota, model name, and network.[/dim]"
-        )
+        lines.append(f"[dim]{key_help}[/dim]")
         console.print(
             Panel(
                 "\n".join(lines),
@@ -595,12 +732,12 @@ def run(
         do_apply = True
     else:
         prompt = (
-            "Apply these commit(s)? (y/n/auto)"
+            "Apply these commit(s)? (y/n)"
             if len(plan) > 1
-            else "Apply these commands? (y/n/auto)"
+            else "Apply these commands? (y/n)"
         )
-        choice = typer.prompt(prompt, default="n").strip().lower()
-        do_apply = choice == "auto" or choice in ("y", "yes")
+        choice = typer.prompt(prompt, default="y").strip().lower()
+        do_apply = choice in ("y", "yes")
 
     if do_apply:
         for name, sug in plan: