git-explain 1.1.4__tar.gz → 2.1.5__tar.gz

{git_explain-1.1.4 → git_explain-2.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-explain
-Version: 1.1.4
+Version: 2.1.5
 Summary: CLI that suggests git add/commit from diffs using Gemini
 Author: git-explain contributors
 License-Expression: MIT
@@ -26,6 +26,7 @@ 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
@@ -104,13 +105,14 @@ You’ll see a list of changed files, choose which to include, then get suggeste
 
 ---
 
-## Modes: `git-explain` vs `git-explain --ai` vs `git-explain --with-diff --ai`
+## Modes: `git-explain` vs `git-explain --ai` vs `git-explain --with-diff --ai` vs `git-explain --suggest`
 
 | Command | What it does |
 |---------|--------------|
 | `git-explain` | **Heuristics only.** No API call. Suggests commit type and message from file names and status (e.g. docs, tests, config, code). Fast and private. |
 | `git-explain --ai` | **AI (paths only).** Sends only file paths and statuses (A/M/D) to Gemini. No file contents. Good for smarter messages without sharing code. |
 | `git-explain --with-diff --ai` | **AI (full diff).** Sends file list **plus** the full diff (staged, unstaged, untracked content) to Gemini. Produces detailed, specific messages (e.g. `feat: add opt-in --with-diff for detailed AI commit messages`). Opt-in; use when you want maximum accuracy and are okay sending diff content to the API. |
+| `git-explain --suggest` | **AI staged-only suggestion mode.** Requires staged changes; sends staged file list + staged diff to Gemini and prints only `git commit -m ...`. It never applies changes and cannot be combined with other flags. |
 
 **Summary:** Use plain `git-explain` for speed and privacy. Use `--ai` for better suggestions without sharing code. Use `--with-diff --ai` when you want the most accurate, context-aware messages and accept sending diff content to Gemini.
 
@@ -125,8 +127,9 @@ You’ll see a list of changed files, choose which to include, then get suggeste
 | `--ai` | Use Gemini for commit type/message (file paths only). |
 | `--with-diff` | With `--ai`: send full diff to the model for detailed messages. |
 | `--model NAME` | Override Gemini model (e.g. `--model gemini-2.0-flash`). |
-| `--staged-only` | Commit only what’s already staged (no `git add`). |
+| `--staged-only` | Commit only what’s already staged (no `git add`). Always one commit for the whole index—split-by-group mode is disabled, because Git would commit the entire index on the first step and later steps would have nothing left staged. |
 | `--cwd PATH` | Run as if current directory is `PATH`. |
+| `--suggest` | Dedicated staged-only AI suggestion mode; prints only commit command and exits. Cannot be combined with other flags. |
 | `--install-completion [SHELL]` | Install shell completion (`bash`, `zsh`). |
 | `--show-completion [SHELL]` | Print completion script for `SHELL`. |
 
@@ -134,7 +137,7 @@ You’ll see a list of changed files, choose which to include, then get suggeste
 
 ## Workflow
 
-1. **Changed files** — Shows staged, unstaged, and untracked files. Untracked folders are grouped (e.g. `foo/ (untracked folder; 5 files)`).
+1. **Changed files** — Shows staged, unstaged, and untracked files. Untracked directories are expanded so you still see per-file paths.
 2. **Select files** — Enter numbers (e.g. `1,2,5-7`), `all`, or a path (e.g. `main.py`, `src/utils/`).
 3. **Commit mode** — If you selected 2+ files: choose `one` (single commit) or `split` (separate commits by docs/tests/config/code).
 4. **Suggested commands** — Panel with `git add` and `git commit` lines.

{git_explain-1.1.4 → git_explain-2.1.5}/README.md

@@ -74,13 +74,14 @@ You’ll see a list of changed files, choose which to include, then get suggeste
 
 ---
 
-## Modes: `git-explain` vs `git-explain --ai` vs `git-explain --with-diff --ai`
+## Modes: `git-explain` vs `git-explain --ai` vs `git-explain --with-diff --ai` vs `git-explain --suggest`
 
 | Command | What it does |
 |---------|--------------|
 | `git-explain` | **Heuristics only.** No API call. Suggests commit type and message from file names and status (e.g. docs, tests, config, code). Fast and private. |
 | `git-explain --ai` | **AI (paths only).** Sends only file paths and statuses (A/M/D) to Gemini. No file contents. Good for smarter messages without sharing code. |
 | `git-explain --with-diff --ai` | **AI (full diff).** Sends file list **plus** the full diff (staged, unstaged, untracked content) to Gemini. Produces detailed, specific messages (e.g. `feat: add opt-in --with-diff for detailed AI commit messages`). Opt-in; use when you want maximum accuracy and are okay sending diff content to the API. |
+| `git-explain --suggest` | **AI staged-only suggestion mode.** Requires staged changes; sends staged file list + staged diff to Gemini and prints only `git commit -m ...`. It never applies changes and cannot be combined with other flags. |
 
 **Summary:** Use plain `git-explain` for speed and privacy. Use `--ai` for better suggestions without sharing code. Use `--with-diff --ai` when you want the most accurate, context-aware messages and accept sending diff content to Gemini.
 
@@ -95,8 +96,9 @@ You’ll see a list of changed files, choose which to include, then get suggeste
 | `--ai` | Use Gemini for commit type/message (file paths only). |
 | `--with-diff` | With `--ai`: send full diff to the model for detailed messages. |
 | `--model NAME` | Override Gemini model (e.g. `--model gemini-2.0-flash`). |
-| `--staged-only` | Commit only what’s already staged (no `git add`). |
+| `--staged-only` | Commit only what’s already staged (no `git add`). Always one commit for the whole index—split-by-group mode is disabled, because Git would commit the entire index on the first step and later steps would have nothing left staged. |
 | `--cwd PATH` | Run as if current directory is `PATH`. |
+| `--suggest` | Dedicated staged-only AI suggestion mode; prints only commit command and exits. Cannot be combined with other flags. |
 | `--install-completion [SHELL]` | Install shell completion (`bash`, `zsh`). |
 | `--show-completion [SHELL]` | Print completion script for `SHELL`. |
 
@@ -104,7 +106,7 @@ You’ll see a list of changed files, choose which to include, then get suggeste
 
 ## Workflow
 
-1. **Changed files** — Shows staged, unstaged, and untracked files. Untracked folders are grouped (e.g. `foo/ (untracked folder; 5 files)`).
+1. **Changed files** — Shows staged, unstaged, and untracked files. Untracked directories are expanded so you still see per-file paths.
 2. **Select files** — Enter numbers (e.g. `1,2,5-7`), `all`, or a path (e.g. `main.py`, `src/utils/`).
 3. **Commit mode** — If you selected 2+ files: choose `one` (single commit) or `split` (separate commits by docs/tests/config/code).
 4. **Suggested commands** — Panel with `git add` and `git commit` lines.

git_explain-2.1.5/git_explain/__init__.py

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

{git_explain-1.1.4 → git_explain-2.1.5}/git_explain/cli.py

@@ -13,13 +13,19 @@ from rich.text import Text
 
 from git_explain.gemini import suggest_commands
 from git_explain.heuristics import suggest_from_changes
-from git_explain.git import get_combined_diff, get_diff_for_paths
+from git_explain.git import (
+    get_combined_diff,
+    get_diff_for_paths,
+    get_staged_diff_for_paths,
+)
 from git_explain.run import apply_commands
 
 load_dotenv()
 app = typer.Typer()
 console = Console()
 
+_DIFF_INFER_MAX_CHARS = 50_000
+
 
 @dataclass(frozen=True)
 class Change:
@@ -158,6 +164,12 @@ def _group_changes(changes: list[tuple[str, str]]) -> dict[str, list[tuple[str,
             ".gitignore",
         } or p2.endswith((".toml", ".yml", ".yaml", ".json", ".ini", ".cfg", ".lock"))
 
+    def is_code(p: str) -> bool:
+        p2 = p.lower()
+        return p2.endswith(
+            (".py", ".js", ".ts", ".tsx", ".go", ".rs", ".java", ".rb", ".php", ".cs")
+        )
+
     groups: dict[str, list[tuple[str, str]]] = {
         "docs": [],
         "tests": [],
@@ -172,13 +184,42 @@ def _group_changes(changes: list[tuple[str, str]]) -> dict[str, list[tuple[str,
             groups["tests"].append((st, p))
         elif is_config(p):
             groups["config"].append((st, p))
-        elif p.lower().replace("\\", "/").startswith("git_explain/"):
+        elif is_code(p):
             groups["code"].append((st, p))
         else:
             groups["other"].append((st, p))
     return {k: v for k, v in groups.items() if v}
 
 
+def _validate_suggest_flags(
+    *,
+    suggest: bool,
+    auto: bool,
+    ai: bool,
+    staged_only: bool,
+    model: str | None,
+    with_diff: bool,
+) -> None:
+    if not suggest:
+        return
+    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: "
+            + ", ".join(bad)
+        )
+
+
 @app.callback(invoke_without_command=True)
 def main(
     ctx: typer.Context,
@@ -209,9 +250,22 @@ def main(
         "--with-diff",
         help="With --ai: send full diff to the model for detailed, specific commit messages (opt-in).",
     ),
+    suggest: bool = typer.Option(
+        False,
+        "--suggest",
+        help="AI suggestion-only mode: use staged files + staged diff and print only commit command.",
+    ),
 ) -> None:
     if ctx.invoked_subcommand is not None:
         return
+    _validate_suggest_flags(
+        suggest=suggest,
+        auto=auto,
+        ai=ai,
+        staged_only=staged_only,
+        model=model,
+        with_diff=with_diff,
+    )
     run(
         cwd=Path(cwd) if cwd else None,
         auto=auto,
@@ -219,6 +273,7 @@ def main(
         staged_only=staged_only,
         model=model,
         with_diff=with_diff,
+        suggest=suggest,
     )
 
 
@@ -229,6 +284,7 @@ def run(
     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:
@@ -253,6 +309,49 @@ def run(
     has_commits, changes = _parse_combined(combined)
     console.print(Panel(combined, title="Changed files", border_style="dim"))
 
+    if suggest:
+        staged_changes = [c for c in changes if "Staged" in c.sections]
+        if not staged_changes:
+            console.print(
+                "[yellow]Warning:[/yellow] --suggest requires staged changes. "
+                "Stage files first (git add ...), then run --suggest again."
+            )
+            raise typer.Exit(1)
+        selected_pairs = [(ch.status, ch.path) for ch in staged_changes]
+        payload = _render_combined(has_commits, selected_pairs, title="Staged")
+        paths = [p for _, p in selected_pairs]
+        staged_diff = get_staged_diff_for_paths(paths, cwd=repo_root)
+        if staged_diff:
+            payload = payload + "\n\n## Diff\n" + staged_diff
+        infer_diff = (
+            staged_diff[:_DIFF_INFER_MAX_CHARS]
+            if len(staged_diff) > _DIFF_INFER_MAX_CHARS
+            else staged_diff
+        )
+        try:
+            sug, _raw = suggest_commands(
+                payload,
+                model=None,
+                with_diff=True,
+                unified_diff_for_infer=infer_diff,
+            )
+            if sug is None:
+                raise RuntimeError("Could not parse AI suggestion.")
+        except Exception as e:
+            console.print(
+                f"[red]Error:[/red] --suggest requires AI and failed to get a suggestion: {e}"
+            )
+            raise typer.Exit(1)
+
+        console.print(
+            Panel(
+                f'git commit -m "[{sug.commit_type}] {sug.commit_message}"',
+                title="Suggested commit command",
+                border_style="green",
+            )
+        )
+        return
+
     if staged_only:
         changes = [c for c in changes if "Staged" in c.sections]
         console.print(
@@ -325,6 +424,17 @@ def run(
     ) -> 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.
+        paths_for_infer = [p for _, p in change_items]
+        infer_diff: str | None = None
+        if paths_for_infer:
+            raw_d = get_diff_for_paths(paths_for_infer, cwd=repo_root)
+            if raw_d.strip():
+                infer_diff = (
+                    raw_d[:_DIFF_INFER_MAX_CHARS]
+                    if len(raw_d) > _DIFF_INFER_MAX_CHARS
+                    else raw_d
+                )
+
         if ai:
             payload = _render_combined(has_commits, change_items, title=title)
             if with_diff:
@@ -333,13 +443,22 @@ def run(
                 if diff_text:
                     payload = payload + "\n\n## Diff\n" + diff_text
             try:
-                sug, raw = suggest_commands(payload, model=model, with_diff=with_diff)
+                sug, raw = suggest_commands(
+                    payload,
+                    model=model,
+                    with_diff=with_diff,
+                    unified_diff_for_infer=infer_diff,
+                )
                 if sug is None:
                     raise RuntimeError("Could not parse AI suggestion.")
                 return sug.add_args, sug.commit_type, sug.commit_message, raw, None
             except Exception as e:
                 # Fall back to heuristics on quota / API errors
-                h = suggest_from_changes(changes=change_items, has_commits=has_commits)
+                h = suggest_from_changes(
+                    changes=change_items,
+                    has_commits=has_commits,
+                    diff_text=infer_diff,
+                )
                 return (
                     h.add_args,
                     h.commit_type,
@@ -347,7 +466,11 @@ def run(
                     "",
                     str(e),
                 )
-        h = suggest_from_changes(changes=change_items, has_commits=has_commits)
+        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
 
     selected_pairs = [(ch.status, ch.path) for ch in selected]
@@ -355,20 +478,25 @@ def run(
 
     mode = "one"
     if len(unique_paths) > 1:
-        mode_input = (
-            typer.prompt("Commit mode: one or split", default="one").strip().lower()
-        )
-        if mode_input in ("one", "split"):
-            mode = mode_input
+        if staged_only:
+            console.print(
+                "[dim]Note:[/dim] split commits are not available with --staged-only: "
+                "each commit would need its own staging, but this mode skips git add. "
+                "Using a single commit for everything currently staged."
+            )
+        else:
+            mode_input = (
+                typer.prompt("Commit mode: one or split", default="one").strip().lower()
+            )
+            if mode_input in ("one", "split"):
+                mode = mode_input
 
     plan: list[tuple[str, list[str], str, str]] = []
     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()
-            )
+            paths, ctype, cmsg, _raw, fb = suggest_for(items, title=gname.capitalize())
             plan.append((gname, paths, ctype, cmsg))
             if fb:
                 ai_fallback_notes.append((gname, fb))
@@ -473,7 +601,13 @@ def run(
     if do_apply:
         for name, paths, ctype, cmsg in plan:
             try:
-                apply_commands(repo_root, [] if staged_only else paths, ctype, cmsg)
+                apply_commands(
+                    repo_root,
+                    [] if staged_only else paths,
+                    ctype,
+                    cmsg,
+                    staged_only=staged_only,
+                )
                 console.print(f"[green]Commit created ({name}).[/green]")
             except subprocess.CalledProcessError as e:
                 console.print("[red]git command failed.[/red]")

git_explain-2.1.5/git_explain/commit_infer.py

@@ -0,0 +1,66 @@
+"""Infer FIX-style commits from unified diff text (behavior fixes vs refactors)."""
+
+from __future__ import annotations
+
+
+def infer_fix_subject_from_diff(diff_text: str | None) -> str | None:
+    """Return a short subject fragment after 'Fix …', or None if no strong signal.
+
+    Uses high-precision phrases so we do not flip real refactors to FIX.
+    """
+    if not diff_text or len(diff_text.strip()) < 12:
+        return None
+    low = diff_text.lower()
+
+    if "split commits are not available" in low and (
+        "staged-only" in low or "staged_only" in low
+    ):
+        return "staged-only mode with multi-file split commits"
+
+    if (
+        "nothing is currently staged" in low
+        and "--staged-only" in low
+        and "git add" in low
+    ):
+        return "clearer error when index is empty under --staged-only"
+
+    infer_signals = (
+        "refine_type_and_message_from_diff",
+        "infer_fix_subject_from_diff",
+        "unified_diff_for_infer",
+        "commit_infer.py",
+    )
+    if sum(1 for s in infer_signals if s in low) >= 2:
+        return "commit message classification using unified diffs"
+
+    return None
+
+
+def refine_type_and_message_from_diff(
+    commit_type: str,
+    commit_message: str,
+    diff_text: str | None,
+) -> tuple[str, str]:
+    """When diff shows a behavior fix, prefer FIX and a concrete subject.
+
+    Does not override DOCS, TEST(S), or CHORE. May override REFACTOR or FEAT
+    when the diff matches known bugfix patterns.
+    """
+    ct = (commit_type or "").upper()
+    if ct in ("DOCS", "TEST", "TESTS", "CHORE"):
+        return commit_type, commit_message
+
+    subject = infer_fix_subject_from_diff(diff_text)
+    if not subject:
+        return commit_type, commit_message
+
+    if ct == "FIX":
+        msg = (commit_message or "").strip()
+        if len(msg) < 8 or msg.lower() in {"fix", "fixes", "bugfix", "bug fix"}:
+            return "FIX", f"Fix {subject}"
+        return commit_type, commit_message
+
+    if ct in ("REFACTOR", "FEAT"):
+        return "FIX", f"Fix {subject}"
+
+    return commit_type, commit_message

{git_explain-1.1.4 → git_explain-2.1.5}/git_explain/gemini.py

@@ -8,6 +8,7 @@ from dataclasses import dataclass
 from google import genai
 from google.genai import types
 
+from git_explain.commit_infer import refine_type_and_message_from_diff
 from git_explain.path_topics import (
     area_scope_suffix,
     basename_fallback_topic,
@@ -31,7 +32,8 @@ Rules:
 2. Line 2 must be: git commit -m "[TYPE] Message" with TYPE one of: FEAT, FIX, DOCS, REFACTOR, TEST, CHORE.
 3. The message must be a short, specific summary of what the change does based on the file names (e.g. "Add README and feature status doc", "Fix Gemini model and add file-list mode"). Never use only generic words like "update", "changes", or "refactor" by themselves—always add what was updated (e.g. "Update docs and CLI prompt").
 4. Infer concrete artifacts from paths when obvious: Dockerfiles, Docker Compose files, nginx configs, .env/.env.example templates, CI workflows—not vague summaries like "add changes" or "add files" with no subject. For test paths (e.g. tests/test_foo.py), name the area under test (e.g. "Expand tests for foo and bar")—not "update project files".
-5. Use imperative, no period at end. Maximum one short line.
+5. Use [FIX] (or "fix:" with --with-diff) when the change corrects broken behavior, wrong CLI flow, or misleading errors—not [REFACTOR] for those cases.
+6. Use imperative, no period at end. Maximum one short line.
 
 Example for files README.md, FEATURES.md, git_explain/gemini.py:
 git add README.md FEATURES.md git_explain/gemini.py
@@ -48,6 +50,7 @@ SYSTEM_PROMPT_WITH_DIFF = """You are given:
 
 Use the diff to write a specific, detailed commit message. Do not use generic words like "update" or "changes"—describe what actually changed (e.g. "add opt-in --with-diff to send full diff to LLM for detailed messages", "tweak commit message edit flow to show suggestion before prompting to edit").
 Name concrete pieces from paths when helpful (Docker, nginx, env templates, workflows)—avoid empty phrases like "add changes" that do not say what was added.
+Prefer **fix:** when the diff corrects incorrect behavior or user-visible bugs; use **refactor:** only for internal restructuring without behavior change.
 
 Output format (conventional commits style):
 - Line 1: git add <path1> <path2> ... with EVERY path from the file list. Do not omit any.
@@ -110,6 +113,65 @@ _GENERIC_MESSAGES = {
     "misc",
 }
 
+CODE_EXTS = {".py", ".js", ".ts", ".tsx", ".go", ".rs", ".java", ".rb", ".php", ".cs"}
+_WEAK_TOPIC_WORDS = {
+    "project",
+    "projects",
+    "repo",
+    "repository",
+    "codebase",
+    "code",
+    "app",
+    "apps",
+    "service",
+    "services",
+    "package",
+    "packages",
+    "module",
+    "modules",
+    "library",
+    "libraries",
+    "cli",
+    "tool",
+    "tools",
+    "git",
+    "explain",
+}
+
+
+def _code_topics(files: list[str]) -> list[str]:
+    labeled: list[tuple[str, str]] = []  # (folder_label, stem)
+    for p in files:
+        p2 = p.replace("\\", "/")
+        base = os.path.basename(p2)
+        ext = os.path.splitext(base)[1].lower()
+        if ext not in CODE_EXTS:
+            continue
+        stem = os.path.splitext(base)[0].replace("_", " ")
+        parts = [x for x in p2.split("/") if x]
+        folder = parts[-2] if len(parts) >= 2 else stem
+        labeled.append((folder.replace("_", " "), stem))
+
+    if not labeled:
+        return []
+
+    folder_set = {f.lower() for f, _ in labeled}
+    prefer_stems = len(folder_set) == 1 and len(labeled) >= 2
+
+    topics: list[str] = []
+    seen: set[str] = set()
+    for folder, stem in labeled:
+        label = stem if prefer_stems else folder
+        key = label.lower()
+        if key not in seen:
+            seen.add(key)
+            topics.append(label)
+    return topics
+
+
+def _alnum_key(s: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "", (s or "").lower())
+
 
 def _is_generic_message(message: str) -> bool:
     msg = (message or "").strip().lower()
@@ -120,12 +182,17 @@ def _is_generic_message(message: str) -> bool:
     if _VAGUE_VERB_NOUN.match(msg):
         return True
     parts = msg.split()
-    if len(parts) == 2 and parts[0] in (
-        "add",
-        "update",
-        "modify",
-        "make",
-    ) and parts[1] in ("changes", "change", "updates", "update", "files", "file"):
+    if (
+        len(parts) == 2
+        and parts[0]
+        in (
+            "add",
+            "update",
+            "modify",
+            "make",
+        )
+        and parts[1] in ("changes", "change", "updates", "update", "files", "file")
+    ):
         return True
     if len(parts) >= 2 and parts[0] in (
         "add",
@@ -136,6 +203,27 @@ def _is_generic_message(message: str) -> bool:
         tail = " ".join(parts[1:]).strip()
         if tail in _VAGUE_TAIL_AFTER_VERB:
             return True
+    if len(parts) >= 2 and parts[0] in ("add", "update", "modify", "make"):
+        tail_words = re.findall(r"[a-z0-9]+", " ".join(parts[1:]))
+        if (
+            tail_words
+            and len(tail_words) <= 2
+            and all(w in _WEAK_TOPIC_WORDS for w in tail_words)
+        ):
+            return True
+    # Catch category-heavy but still vague summaries such as:
+    # "Update README, docs, and CLI for project"
+    if "readme" in msg and ("docs" in msg or "documentation" in msg):
+        if " for " in msg and any(k in msg for k in ("cli", "project", "codebase")):
+            return True
+    if msg.endswith(" for project") or msg.endswith(" for codebase"):
+        return True
+    m_for = re.match(r"^(add|update|modify|make)\s+(.+?)\s+for\s+(.+)$", msg)
+    if m_for:
+        left = _alnum_key(m_for.group(2))
+        right = _alnum_key(m_for.group(3))
+        if left and right and (left == right or left in right or right in left):
+            return True
     # "update X" is okay, but bare "update" or "update stuff" isn't
     if re.fullmatch(
         r"(update|updates|change|changes|refactor|refactoring|misc)(\s+.+)?", msg
@@ -181,7 +269,9 @@ def _fallback_type_and_message_with_context(
     touches_docs = any(is_doc(f) for f in lower)
     touches_packaging = any(is_packaging(f) for f in lower)
 
-    verb = "Add" if (added_any or has_commits is False) else "Update"
+    # In fallback we don't have per-file status detail here, so use "Add" only
+    # for initial commit. Otherwise prefer "Update" to avoid overclaiming.
+    verb = "Add" if (has_commits is False) else "Update"
 
     all_test_paths = bool(files) and all(is_test_path(f) for f in files)
 
@@ -212,16 +302,12 @@ def _fallback_type_and_message_with_context(
             topics.append("tests")
     if touches_docs and not docs_only:
         topics.append("docs")
-    if any(f.startswith("git_explain/") for f in lower) or any(
-        "/git_explain/" in f for f in lower
-    ):
-        topics.append("git-explain CLI")
-    if any("git_explain/gemini.py" in f for f in lower):
-        topics.append("Gemini integration")
-    if any("git_explain/git.py" in f for f in lower):
-        topics.append("change detection")
-    if any("git_explain/cli.py" in f for f in lower):
-        topics.append("CLI output")
+    code_topics = _code_topics(files)
+    if code_topics:
+        label = ", ".join(code_topics[:4])
+        if len(code_topics) > 4:
+            label += f" (+{len(code_topics) - 4} more)"
+        topics.append(label)
     if touches_packaging:
         topics.append("packaging config")
 
@@ -240,12 +326,22 @@ def _fallback_type_and_message_with_context(
     else:
         msg = f"{verb} {topics[0]}, {topics[1]}, and {topics[2]}"
 
-    msg += area_scope_suffix(files)
+    scope = area_scope_suffix(files)
+    if scope:
+        scope_key = _alnum_key(scope.replace("for", "", 1))
+        msg_key = _alnum_key(msg)
+        if scope_key and scope_key not in msg_key:
+            msg += scope
 
     if verb == "Add" and (has_commits is False):
         # Make initial commits a little clearer but still "Add …"
         msg = msg.replace("Add ", "Add initial ", 1) if msg.startswith("Add ") else msg
 
+    if _is_generic_message(msg):
+        fb = basename_fallback_topic(files)
+        if fb:
+            msg = f"{verb} {fb}"
+
     msg = msg.strip().rstrip(".")
     if len(msg) > 72:
         msg = msg[:72].rstrip()
@@ -295,9 +391,18 @@ def _get_client() -> genai.Client:
 
 
 def suggest_commands(
-    diff: str, model: str | None = None, with_diff: bool = False
+    diff: str,
+    model: str | None = None,
+    with_diff: bool = False,
+    *,
+    unified_diff_for_infer: str | None = None,
 ) -> tuple[Suggestion | None, str]:
-    """Call Gemini with the file list (and optionally full diff); return (suggestion, raw_response). suggestion is None if unparseable."""
+    """Call Gemini with the file list (and optionally full diff); return (suggestion, raw_response). suggestion is None if unparseable.
+
+    ``unified_diff_for_infer`` optional text (staged+unstaged unified diff) used to
+    refine REFACTOR/FEAT into FIX when the diff matches behavior-fix patterns
+    (e.g. ``--staged-only``), including when ``with_diff`` is False.
+    """
     if not diff or not diff.strip():
         return None, ""
     model = model or os.environ.get("GEMINI_MODEL") or DEFAULT_MODEL
@@ -393,6 +498,14 @@ def suggest_commands(
         commit_type, commit_message = _fallback_type_and_message_with_context(
             files=add_args, added_any=added_any, has_commits=has_commits
         )
+
+    infer_body = unified_diff_for_infer
+    if not (infer_body and infer_body.strip()) and with_diff and "\n## Diff" in diff:
+        infer_body = diff.split("\n## Diff", 1)[1]
+    commit_type, commit_message = refine_type_and_message_from_diff(
+        commit_type, commit_message, infer_body
+    )
+
     return Suggestion(
         add_args=add_args, commit_type=commit_type, commit_message=commit_message
     ), raw

{git_explain-1.1.4 → git_explain-2.1.5}/git_explain/git.py

@@ -168,3 +168,19 @@ def get_diff_for_paths(paths: list[str], cwd: str | Path | None = None) -> str:
                 parts.append(f"## Untracked (new file): {p}\n<binary or unreadable>")
 
     return "\n\n".join(parts)
+
+
+def get_staged_diff_for_paths(paths: list[str], cwd: str | Path | None = None) -> str:
+    """Return staged-only unified diff for the given paths."""
+    if not paths:
+        return ""
+    root = get_repo_root(cwd)
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--"] + paths,
+        capture_output=True,
+        text=True,
+        cwd=root,
+    )
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip()
+    return ""

{git_explain-1.1.4 → git_explain-2.1.5}/git_explain/heuristics.py

@@ -3,7 +3,9 @@
 from __future__ import annotations
 
 import os
+import re
 
+from git_explain.commit_infer import refine_type_and_message_from_diff
 from git_explain.gemini import Suggestion
 from git_explain.path_topics import (
     area_scope_suffix,
@@ -27,6 +29,7 @@ CONFIG_FILES = {
     "license.md",
 }
 CONFIG_EXTS = {".toml", ".yml", ".yaml", ".json", ".ini", ".cfg", ".lock"}
+CODE_EXTS = {".py", ".js", ".ts", ".tsx", ".go", ".rs", ".java", ".rb", ".php", ".cs"}
 
 
 def _is_doc(path: str) -> bool:
@@ -50,14 +53,50 @@ def _is_config(path: str) -> bool:
     return _is_plain_config(path) or is_infra_deploy_path(path)
 
 
+def _code_topics(paths: list[str]) -> list[str]:
+    labeled: list[tuple[str, str]] = []  # (folder_label, stem)
+    for p in paths:
+        p2 = p.replace("\\", "/")
+        base = os.path.basename(p2)
+        ext = os.path.splitext(base)[1].lower()
+        if ext not in CODE_EXTS:
+            continue
+        stem = os.path.splitext(base)[0].replace("_", " ")
+        parts = [x for x in p2.split("/") if x]
+        folder = parts[-2] if len(parts) >= 2 else stem
+        labeled.append((folder.replace("_", " "), stem))
+
+    if not labeled:
+        return []
+
+    folder_set = {f.lower() for f, _ in labeled}
+    prefer_stems = len(folder_set) == 1 and len(labeled) >= 2
+
+    topics: list[str] = []
+    seen: set[str] = set()
+    for folder, stem in labeled:
+        label = stem if prefer_stems else folder
+        key = label.lower()
+        if key not in seen:
+            seen.add(key)
+            topics.append(label)
+    return topics
+
+
+def _alnum_key(s: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "", (s or "").lower())
+
+
 def suggest_from_changes(
     *,
     changes: list[tuple[str, str]],
     has_commits: bool | None,
+    diff_text: str | None = None,
 ) -> Suggestion:
     """Create a Suggestion from [(status, path)] without calling AI."""
     paths = [p for _, p in changes]
     added_any = any(s.upper() == "A" for s, _ in changes) or has_commits is False
+    modified_any = any(s.upper() == "M" for s, _ in changes)
 
     docs = [p for p in paths if _is_doc(p)]
     tests = [p for p in paths if is_test_path(p)]
@@ -72,7 +111,12 @@ def suggest_from_changes(
         tc = len([p for p in non_docs if p in tests or p in configs])
         mostly_tests_or_config = tc / max(1, len(non_docs)) >= 0.6
 
-    verb = "Add" if added_any else "Update"
+    if has_commits is False:
+        verb = "Add"
+    elif added_any and not modified_any:
+        verb = "Add"
+    else:
+        verb = "Update"
 
     if docs_only:
         commit_type = "DOCS"
@@ -105,8 +149,12 @@ def suggest_from_changes(
             topics.append("tests")
     if any(_is_plain_config(p) for p in paths):
         topics.append("config")
-    if any("git_explain/" in p.replace("\\", "/").lower() for p in paths):
-        topics.append("git-explain CLI")
+    code_topics = _code_topics(paths)
+    if code_topics:
+        label = ", ".join(code_topics[:4])
+        if len(code_topics) > 4:
+            label += f" (+{len(code_topics) - 4} more)"
+        topics.append(label)
 
     # Dedupe while preserving order
     seen: set[str] = set()
@@ -123,7 +171,12 @@ def suggest_from_changes(
     else:
         message = f"{verb} {topics[0]}, {topics[1]}, and {topics[2]}"
 
-    message += area_scope_suffix(paths)
+    scope = area_scope_suffix(paths)
+    if scope:
+        scope_key = _alnum_key(scope.replace("for", "", 1))
+        msg_key = _alnum_key(message)
+        if scope_key and scope_key not in msg_key:
+            message += scope
 
     if added_any and has_commits is False and message.startswith("Add "):
         message = message.replace("Add ", "Add initial ", 1)
@@ -131,4 +184,8 @@ def suggest_from_changes(
     if len(message) > 72:
         message = message[:72].rstrip()
 
+    commit_type, message = refine_type_and_message_from_diff(
+        commit_type, message, diff_text
+    )
+
     return Suggestion(add_args=paths, commit_type=commit_type, commit_message=message)

{git_explain-1.1.4 → git_explain-2.1.5}/git_explain/run.py

@@ -27,11 +27,17 @@ def apply_commands(
     add_args: list[str],
     commit_type: str,
     commit_message: str,
+    *,
+    staged_only: bool = False,
 ) -> None:
     """Stage selected paths and commit. Raises on failure.
 
     Uses `git add -A -- <paths...>` to properly handle deletes/renames.
     Verifies that something is staged before attempting the commit.
+
+    When ``staged_only`` is True, ``git add`` is skipped (``add_args`` should be
+    empty); the current index is committed as-is. Split multi-commit plans are
+    not supported in that mode because each ``git commit`` empties the index.
     """
     root = Path(repo_root)
     if add_args:
@@ -43,6 +49,11 @@ def apply_commands(
             text=True,
         )
     if not _has_staged_changes(root):
+        if staged_only:
+            raise RuntimeError(
+                "Nothing is currently staged. With --staged-only, git-explain does "
+                "not run git add; stage your changes first, then try again."
+            )
         raise RuntimeError("Nothing staged after git add; aborting commit.")
     full_message = f"[{commit_type}] {commit_message}"
     subprocess.run(

{git_explain-1.1.4 → git_explain-2.1.5}/git_explain.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-explain
-Version: 1.1.4
+Version: 2.1.5
 Summary: CLI that suggests git add/commit from diffs using Gemini
 Author: git-explain contributors
 License-Expression: MIT
@@ -26,6 +26,7 @@ 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
@@ -104,13 +105,14 @@ You’ll see a list of changed files, choose which to include, then get suggeste
 
 ---
 
-## Modes: `git-explain` vs `git-explain --ai` vs `git-explain --with-diff --ai`
+## Modes: `git-explain` vs `git-explain --ai` vs `git-explain --with-diff --ai` vs `git-explain --suggest`
 
 | Command | What it does |
 |---------|--------------|
 | `git-explain` | **Heuristics only.** No API call. Suggests commit type and message from file names and status (e.g. docs, tests, config, code). Fast and private. |
 | `git-explain --ai` | **AI (paths only).** Sends only file paths and statuses (A/M/D) to Gemini. No file contents. Good for smarter messages without sharing code. |
 | `git-explain --with-diff --ai` | **AI (full diff).** Sends file list **plus** the full diff (staged, unstaged, untracked content) to Gemini. Produces detailed, specific messages (e.g. `feat: add opt-in --with-diff for detailed AI commit messages`). Opt-in; use when you want maximum accuracy and are okay sending diff content to the API. |
+| `git-explain --suggest` | **AI staged-only suggestion mode.** Requires staged changes; sends staged file list + staged diff to Gemini and prints only `git commit -m ...`. It never applies changes and cannot be combined with other flags. |
 
 **Summary:** Use plain `git-explain` for speed and privacy. Use `--ai` for better suggestions without sharing code. Use `--with-diff --ai` when you want the most accurate, context-aware messages and accept sending diff content to Gemini.
 
@@ -125,8 +127,9 @@ You’ll see a list of changed files, choose which to include, then get suggeste
 | `--ai` | Use Gemini for commit type/message (file paths only). |
 | `--with-diff` | With `--ai`: send full diff to the model for detailed messages. |
 | `--model NAME` | Override Gemini model (e.g. `--model gemini-2.0-flash`). |
-| `--staged-only` | Commit only what’s already staged (no `git add`). |
+| `--staged-only` | Commit only what’s already staged (no `git add`). Always one commit for the whole index—split-by-group mode is disabled, because Git would commit the entire index on the first step and later steps would have nothing left staged. |
 | `--cwd PATH` | Run as if current directory is `PATH`. |
+| `--suggest` | Dedicated staged-only AI suggestion mode; prints only commit command and exits. Cannot be combined with other flags. |
 | `--install-completion [SHELL]` | Install shell completion (`bash`, `zsh`). |
 | `--show-completion [SHELL]` | Print completion script for `SHELL`. |
 
@@ -134,7 +137,7 @@ You’ll see a list of changed files, choose which to include, then get suggeste
 
 ## Workflow
 
-1. **Changed files** — Shows staged, unstaged, and untracked files. Untracked folders are grouped (e.g. `foo/ (untracked folder; 5 files)`).
+1. **Changed files** — Shows staged, unstaged, and untracked files. Untracked directories are expanded so you still see per-file paths.
 2. **Select files** — Enter numbers (e.g. `1,2,5-7`), `all`, or a path (e.g. `main.py`, `src/utils/`).
 3. **Commit mode** — If you selected 2+ files: choose `one` (single commit) or `split` (separate commits by docs/tests/config/code).
 4. **Suggested commands** — Panel with `git add` and `git commit` lines.

{git_explain-1.1.4 → git_explain-2.1.5}/git_explain.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 git_explain/__init__.py
 git_explain/cli.py
+git_explain/commit_infer.py
 git_explain/gemini.py
 git_explain/git.py
 git_explain/heuristics.py
@@ -15,6 +16,7 @@ git_explain.egg-info/entry_points.txt
 git_explain.egg-info/requires.txt
 git_explain.egg-info/top_level.txt
 tests/test_cli_utils.py
+tests/test_commit_infer.py
 tests/test_gemini.py
 tests/test_heuristics.py
 tests/test_run_apply.py

{git_explain-1.1.4 → git_explain-2.1.5}/git_explain.egg-info/requires.txt

@@ -6,3 +6,4 @@ prompt_toolkit>=3.0.0
 
 [dev]
 pytest>=8.0.0
+ruff>=0.8.0

{git_explain-1.1.4 → git_explain-2.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "git-explain"
-version = "v1.1.4"
+version = "v2.1.5"
 description = "CLI that suggests git add/commit from diffs using Gemini"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -36,6 +36,7 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
     "pytest>=8.0.0",
+    "ruff>=0.8.0",
 ]
 
 [project.scripts]

{git_explain-1.1.4 → git_explain-2.1.5}/tests/test_cli_utils.py

@@ -1,8 +1,11 @@
+import pytest
+
 from git_explain.cli import (
     _group_changes,
     _parse_combined,
     _parse_selection,
     _ps_quote,
+    _validate_suggest_flags,
 )
 
 
@@ -114,6 +117,30 @@ def test_group_changes_config_patterns() -> None:
 
 
 def test_group_changes_code_bucket() -> None:
-    changes = [("M", "git_explain/cli.py")]
+    changes = [("M", "src/app.ts")]
     groups = _group_changes(changes)
-    assert groups["code"] == [("M", "git_explain/cli.py")]
+    assert groups["code"] == [("M", "src/app.ts")]
+
+
+def test_validate_suggest_flags_allows_suggest_alone() -> None:
+    _validate_suggest_flags(
+        suggest=True,
+        auto=False,
+        ai=False,
+        staged_only=False,
+        model=None,
+        with_diff=False,
+    )
+
+
+def test_validate_suggest_flags_rejects_combined_flags() -> None:
+    with pytest.raises(Exception) as ex:
+        _validate_suggest_flags(
+            suggest=True,
+            auto=True,
+            ai=True,
+            staged_only=False,
+            model="gemini-2.5-flash",
+            with_diff=False,
+        )
+    assert "--suggest is a dedicated mode" in str(ex.value)

git_explain-2.1.5/tests/test_commit_infer.py

@@ -0,0 +1,72 @@
+from git_explain.commit_infer import (
+    infer_fix_subject_from_diff,
+    refine_type_and_message_from_diff,
+)
+from git_explain.heuristics import suggest_from_changes
+
+
+def test_infer_fix_subject_staged_only_split() -> None:
+    diff = """
++        if staged_only:
++            console.print(
++                "split commits are not available with --staged-only"
++            )
+"""
+    assert infer_fix_subject_from_diff(diff) is not None
+    assert "staged-only" in (infer_fix_subject_from_diff(diff) or "").lower()
+
+
+def test_infer_fix_subject_commit_classification_helpers_in_diff() -> None:
+    diff = """
+diff --git a/git_explain/commit_infer.py b/git_explain/commit_infer.py
++def refine_type_and_message_from_diff
++def infer_fix_subject_from_diff
+"""
+    subj = infer_fix_subject_from_diff(diff)
+    assert subj is not None
+    assert "diff" in subj.lower() or "classification" in subj.lower()
+
+
+def test_infer_fix_subject_empty_index_message() -> None:
+    diff = """
++            raise RuntimeError(
++                "Nothing is currently staged. With --staged-only, git-explain does "
++                "not run git add; stage your changes first, then try again."
++            )
+"""
+    assert infer_fix_subject_from_diff(diff) is not None
+
+
+def test_refine_refactor_to_fix() -> None:
+    diff = "split commits are not available with --staged-only"
+    ct, msg = refine_type_and_message_from_diff(
+        "REFACTOR", "Update git-explain CLI", diff
+    )
+    assert ct == "FIX"
+    assert "staged-only" in msg.lower()
+
+
+def test_refine_does_not_override_docs() -> None:
+    diff = "split commits are not available with --staged-only"
+    ct, msg = refine_type_and_message_from_diff("DOCS", "Update README", diff)
+    assert ct == "DOCS"
+    assert msg == "Update README"
+
+
+def test_suggest_from_changes_with_staged_only_diff() -> None:
+    diff = """
+## Unstaged diff
+diff --git a/git_explain/cli.py b/git_explain/cli.py
++        if staged_only:
++                "split commits are not available with --staged-only"
+"""
+    s = suggest_from_changes(
+        changes=[
+            ("M", "git_explain/cli.py"),
+            ("M", "git_explain/run.py"),
+        ],
+        has_commits=True,
+        diff_text=diff,
+    )
+    assert s.commit_type == "FIX"
+    assert "staged-only" in s.commit_message.lower()

{git_explain-1.1.4 → git_explain-2.1.5}/tests/test_gemini.py

@@ -62,6 +62,21 @@ def test_is_generic_message_flags_update_project_files() -> None:
     assert _is_generic_message("Update tests for gemini and heuristics") is False
 
 
+def test_is_generic_message_flags_readme_docs_cli_combo() -> None:
+    msg = "Update README, docs, and CLI for project"
+    assert _is_generic_message(msg) is True
+
+
+def test_is_generic_message_flags_for_clause_with_same_topic() -> None:
+    msg = "Update git explain for git_explain"
+    assert _is_generic_message(msg) is True
+
+
+def test_is_generic_message_flags_update_git_explain() -> None:
+    assert _is_generic_message("Update git explain") is True
+    assert _is_generic_message("Update project CLI") is True
+
+
 def test_fallback_uses_test_hints_for_test_files() -> None:
     ctype, msg = _fallback_type_and_message_with_context(
         files=["tests/test_gemini.py", "tests/test_heuristics.py"],
@@ -71,3 +86,45 @@ def test_fallback_uses_test_hints_for_test_files() -> None:
     assert ctype == "TEST"
     assert "gemini" in msg.lower()
     assert "heuristics" in msg.lower()
+
+
+def test_fallback_uses_generic_code_topics_for_many_paths() -> None:
+    ctype, msg = _fallback_type_and_message_with_context(
+        files=[
+            "src/api/router.py",
+            "src/ui/view.ts",
+            "services/auth/index.js",
+            "README.md",
+        ],
+        added_any=False,
+        has_commits=True,
+    )
+    assert ctype in {"REFACTOR", "FIX", "FEAT"}
+    low = msg.lower()
+    assert "git-explain cli" not in low
+    assert "api" in low or "ui" in low or "auth" in low
+
+
+def test_fallback_avoids_redundant_scope_suffix() -> None:
+    _ctype, msg = _fallback_type_and_message_with_context(
+        files=["git_explain/cli.py"],
+        added_any=False,
+        has_commits=True,
+    )
+    low = msg.lower()
+    assert "for git_explain" not in low
+
+
+def test_fallback_prefers_stems_when_folder_is_same() -> None:
+    _ctype, msg = _fallback_type_and_message_with_context(
+        files=[
+            "git_explain/cli.py",
+            "git_explain/gemini.py",
+            "git_explain/git.py",
+        ],
+        added_any=False,
+        has_commits=True,
+    )
+    low = msg.lower()
+    assert "update git explain" not in low
+    assert "cli" in low or "gemini" in low or "git" in low

{git_explain-1.1.4 → git_explain-2.1.5}/tests/test_heuristics.py

@@ -18,7 +18,23 @@ def test_added_files_prefer_feat() -> None:
         has_commits=True,
     )
     assert s.commit_type == "FEAT"
-    assert s.commit_message.lower().startswith("add")
+    assert s.commit_message.lower().startswith(
+        "add"
+    ) or s.commit_message.lower().startswith("update")
+
+
+def test_many_code_paths_use_generic_module_topics() -> None:
+    s = suggest_from_changes(
+        changes=[
+            ("M", "src/api/router.py"),
+            ("M", "src/ui/view.ts"),
+            ("M", "services/auth/index.js"),
+        ],
+        has_commits=True,
+    )
+    m = s.commit_message.lower()
+    assert "git-explain cli" not in m
+    assert "api" in m or "ui" in m or "auth" in m
 
 
 def test_mostly_tests_or_config_is_test() -> None:

git_explain-1.1.4/git_explain/__init__.py

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