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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-explain
-Version: 1.1.2
+Version: 1.1.4
 Summary: CLI that suggests git add/commit from diffs using Gemini
 Author: git-explain contributors
 License-Expression: MIT
@@ -68,13 +68,27 @@ pip install -e .
 
 ## API key (for `--ai` only)
 
-Put your Gemini API key in a `.env` file where you run the CLI, or set it in your environment:
+**Option 1 — Environment variable** (recommended for production, CI, scripts):
+
+```powershell
+# PowerShell
+$env:GEMINI_API_KEY = "your_key_here"
+```
+
+```bash
+# Bash / Zsh
+export GEMINI_API_KEY=your_key_here
+```
+
+**Option 2 — `.env` file** (convenient for local development):
+
+Create a `.env` file where you run the CLI:
 
 ```
 GEMINI_API_KEY=your_key_here
 ```
 
-Or use `GOOGLE_API_KEY`. Optional: set `GEMINI_MODEL` to override the default (e.g. `GEMINI_MODEL=gemini-2.5-flash`). See [Troubleshooting](#troubleshooting) for 404/429.
+You can also use `GOOGLE_API_KEY`. Optional: set `GEMINI_MODEL` to override the default (e.g. `GEMINI_MODEL=gemini-2.5-flash`). See [Troubleshooting](#troubleshooting) for 404/429.
 
 ---
 

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

@@ -38,13 +38,27 @@ pip install -e .
 
 ## API key (for `--ai` only)
 
-Put your Gemini API key in a `.env` file where you run the CLI, or set it in your environment:
+**Option 1 — Environment variable** (recommended for production, CI, scripts):
+
+```powershell
+# PowerShell
+$env:GEMINI_API_KEY = "your_key_here"
+```
+
+```bash
+# Bash / Zsh
+export GEMINI_API_KEY=your_key_here
+```
+
+**Option 2 — `.env` file** (convenient for local development):
+
+Create a `.env` file where you run the CLI:
 
 ```
 GEMINI_API_KEY=your_key_here
 ```
 
-Or use `GOOGLE_API_KEY`. Optional: set `GEMINI_MODEL` to override the default (e.g. `GEMINI_MODEL=gemini-2.5-flash`). See [Troubleshooting](#troubleshooting) for 404/429.
+You can also use `GOOGLE_API_KEY`. Optional: set `GEMINI_MODEL` to override the default (e.g. `GEMINI_MODEL=gemini-2.5-flash`). See [Troubleshooting](#troubleshooting) for 404/429.
 
 ---
 

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

@@ -264,36 +264,11 @@ def run(
         return
 
     norm_paths = [c.path.replace("\\", "/") for c in changes]
-    untracked_indices_by_root: dict[str, list[int]] = {}
-    for idx, (ch, np) in enumerate(zip(changes, norm_paths)):
-        if (
-            "Untracked" in ch.sections
-            and "Staged" not in ch.sections
-            and "Unstaged" not in ch.sections
-            and "/" in np
-        ):
-            root = np.split("/", 1)[0]
-            untracked_indices_by_root.setdefault(root, []).append(idx)
-    folder_groups = {
-        root: idxs for root, idxs in untracked_indices_by_root.items() if len(idxs) > 1
-    }
-
     display_items: list[tuple[str, list[int]]] = []
-    seen_untracked_roots: set[str] = set()
     for idx, ch in enumerate(changes):
-        np = norm_paths[idx]
-        root = np.split("/", 1)[0] if "/" in np else None
-        if root and root in folder_groups:
-            if root in seen_untracked_roots:
-                continue
-            seen_untracked_roots.add(root)
-            count = len(folder_groups[root])
-            label = f"{root}/ (untracked folder; {count} files)"
-            display_items.append((label, folder_groups[root]))
-        else:
-            sec = ",".join([s.lower() for s in ch.sections if s and s != "Meta"])
-            label = f"[{ch.status}] ({sec}) {ch.path}"
-            display_items.append((label, [idx]))
+        sec = ",".join([s.lower() for s in ch.sections if s and s != "Meta"])
+        label = f"[{ch.status}] ({sec}) {ch.path}"
+        display_items.append((label, [idx]))
 
     lines = []
     for idx, (label, _idxs) in enumerate(display_items, start=1):
@@ -347,8 +322,9 @@ def run(
 
     def suggest_for(
         change_items: list[tuple[str, str]], title: str
-    ) -> tuple[list[str], str, str, str]:
-        # Returns (paths, type, message, raw_text)
+    ) -> 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.
         if ai:
             payload = _render_combined(has_commits, change_items, title=title)
             if with_diff:
@@ -360,7 +336,7 @@ def run(
                 sug, raw = suggest_commands(payload, model=model, with_diff=with_diff)
                 if sug is None:
                     raise RuntimeError("Could not parse AI suggestion.")
-                return sug.add_args, sug.commit_type, sug.commit_message, raw
+                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)
@@ -368,10 +344,11 @@ def run(
                     h.add_args,
                     h.commit_type,
                     h.commit_message,
-                    f"AI unavailable: {e}",
+                    "",
+                    str(e),
                 )
         h = suggest_from_changes(changes=change_items, has_commits=has_commits)
-        return h.add_args, h.commit_type, h.commit_message, ""
+        return h.add_args, h.commit_type, h.commit_message, "", None
 
     selected_pairs = [(ch.status, ch.path) for ch in selected]
     unique_paths = {p for _, p in selected_pairs}
@@ -385,14 +362,44 @@ def run(
             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 = 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))
     else:
-        paths, ctype, cmsg, _raw = suggest_for(selected_pairs, title="Selected")
+        paths, ctype, cmsg, _raw, fb = suggest_for(selected_pairs, title="Selected")
         plan.append(("one", paths, ctype, cmsg))
+        if fb:
+            ai_fallback_notes.append(("", fb))
+
+    if ai and ai_fallback_notes:
+        lines = [
+            "[bold]You used --ai, but Gemini was not used for the suggestion below.[/bold]",
+            "Commit message(s) come from [bold]local heuristics[/bold] instead.",
+            "",
+        ]
+        if mode == "split":
+            for gname, reason in ai_fallback_notes:
+                lines.append(f"[dim]{gname}:[/dim] {reason}")
+        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]"
+        )
+        console.print(
+            Panel(
+                "\n".join(lines),
+                title="[yellow]Warning: AI unavailable[/yellow]",
+                border_style="yellow",
+            )
+        )
 
     def _render_plan(pl: list[tuple[str, list[str], str, str]]) -> str:
         rendered: list[str] = []

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

@@ -8,6 +8,14 @@ from dataclasses import dataclass
 from google import genai
 from google.genai import types
 
+from git_explain.path_topics import (
+    area_scope_suffix,
+    basename_fallback_topic,
+    infra_deploy_topics,
+    is_test_path,
+    test_subject_hints,
+)
+
 SYSTEM_PROMPT = """You are given a list of changed/added files under ## Staged, ## Unstaged, ## Untracked.
 Each file line is: <STATUS> <PATH> where STATUS is one of:
 - A = added/new file
@@ -20,13 +28,18 @@ Suggest one commit that includes ALL of these files.
 
 Rules:
 1. Line 1 must be: git add <path1> <path2> ... with EVERY PATH from the list (all sections). Do not omit any file. Do not truncate. Do not include status letters.
-2. Line 2 must be: git commit -m "[TYPE] Message" with TYPE one of: FEAT, FIX, DOCS, REFACTOR, TEST.
+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. Use imperative, no period at end. Maximum one short line.
+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.
 
 Example for files README.md, FEATURES.md, git_explain/gemini.py:
 git add README.md FEATURES.md git_explain/gemini.py
 git commit -m "[DOCS] Add README and FEATURES doc, tune Gemini prompt"
+
+Example for Docker + nginx + env templates under api/ and apps/frontend/:
+git add api/app/Dockerfile apps/frontend/nginx.conf
+git commit -m "[CHORE] Add Docker and nginx config with env examples for api and frontend"
 """
 
 SYSTEM_PROMPT_WITH_DIFF = """You are given:
@@ -34,10 +47,11 @@ SYSTEM_PROMPT_WITH_DIFF = """You are given:
 2. The full diff (## Staged diff, ## Unstaged diff, ## Untracked) showing exact code changes.
 
 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.
 
 Output format (conventional commits style):
 - Line 1: git add <path1> <path2> ... with EVERY path from the file list. Do not omit any.
-- Line 2: git commit -m "type: subject" where type is exactly one of: feat, fix, docs, refactor, test.
+- Line 2: git commit -m "type: subject" where type is exactly one of: feat, fix, docs, refactor, test, chore.
   The subject must be a short, specific summary in imperative mood, no period at end (e.g. "feat: allow editing commit message before apply", "fix: parse conventional commit line from AI").
 
 Example:
@@ -47,16 +61,39 @@ git commit -m "feat: add opt-in --with-diff for detailed AI commit messages"
 
 ADD_LINE_RE = re.compile(r"git\s+add\s+(.+)", re.IGNORECASE)
 COMMIT_LINE_RE = re.compile(
-    r'git\s+commit\s+-m\s+["\']\[(FEAT|FIX|DOCS|REFACTOR|TESTS)\]\s*(.+?)["\']',
+    r'git\s+commit\s+-m\s+["\']\[(FEAT|FIX|DOCS|REFACTOR|TESTS|CHORE)\]\s*(.+?)["\']',
     re.IGNORECASE,
 )
 # Conventional: "feat: subject" or "fix: subject" (use "tests" not "test")
 COMMIT_LINE_CONVENTIONAL_RE = re.compile(
-    r'git\s+commit\s+-m\s+["\'](feat|fix|docs|refactor|tests)\s*:\s*(.+?)["\']',
+    r'git\s+commit\s+-m\s+["\'](feat|fix|docs|refactor|tests|chore)\s*:\s*(.+?)["\']',
     re.IGNORECASE,
 )
 DEFAULT_MODEL = "gemini-2.5-flash"
 
+_VAGUE_VERB_NOUN = re.compile(
+    r"^(add|update|modify|make)\s+(changes?|updates?|stuff|things)\s*$",
+    re.IGNORECASE,
+)
+
+# After add/update/modify/make, these tails are too vague to keep as the final message.
+_VAGUE_TAIL_AFTER_VERB = frozenset(
+    {
+        "project files",
+        "the project",
+        "the codebase",
+        "codebase",
+        "code",
+        "files",
+        "file",
+        "some files",
+        "various files",
+        "multiple files",
+        "dependencies",
+        "deps",
+    }
+)
+
 _GENERIC_MESSAGES = {
     "update",
     "updates",
@@ -80,6 +117,25 @@ def _is_generic_message(message: str) -> bool:
         return True
     if msg in _GENERIC_MESSAGES:
         return True
+    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"):
+        return True
+    if len(parts) >= 2 and parts[0] in (
+        "add",
+        "update",
+        "modify",
+        "make",
+    ):
+        tail = " ".join(parts[1:]).strip()
+        if tail in _VAGUE_TAIL_AFTER_VERB:
+            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
@@ -127,8 +183,12 @@ def _fallback_type_and_message_with_context(
 
     verb = "Add" if (added_any or has_commits is False) else "Update"
 
+    all_test_paths = bool(files) and all(is_test_path(f) for f in files)
+
     if docs_only:
         commit_type = "DOCS"
+    elif all_test_paths:
+        commit_type = "TEST"
     elif verb == "Add":
         commit_type = "FEAT"
     else:
@@ -139,6 +199,17 @@ def _fallback_type_and_message_with_context(
         topics.append("README")
     if any(f.endswith("features.md") for f in lower):
         topics.append("FEATURES doc")
+    topics.extend(infra_deploy_topics(files))
+    test_files = [f for f in files if is_test_path(f)]
+    if test_files:
+        all_tests_only = len(test_files) == len(files)
+        hints = test_subject_hints(files)
+        if all_tests_only and hints:
+            head = " and ".join(hints[:3])
+            tail = f" (+{len(hints) - 3} more)" if len(hints) > 3 else ""
+            topics.append(f"tests for {head}{tail}")
+        else:
+            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(
@@ -154,13 +225,14 @@ def _fallback_type_and_message_with_context(
     if touches_packaging:
         topics.append("packaging config")
 
-    if not topics:
-        topics = ["project files"]
-
     # Dedupe while keeping order
     seen: set[str] = set()
     topics = [t for t in topics if not (t in seen or seen.add(t))]
 
+    if not topics:
+        fb = basename_fallback_topic(files)
+        topics = [fb] if fb else ["project files"]
+
     if len(topics) == 1:
         msg = f"{verb} {topics[0]}"
     elif len(topics) == 2:
@@ -168,6 +240,8 @@ def _fallback_type_and_message_with_context(
     else:
         msg = f"{verb} {topics[0]}, {topics[1]}, and {topics[2]}"
 
+    msg += area_scope_suffix(files)
+
     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

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

@@ -5,10 +5,17 @@ from __future__ import annotations
 import os
 
 from git_explain.gemini import Suggestion
+from git_explain.path_topics import (
+    area_scope_suffix,
+    basename_fallback_topic,
+    infra_deploy_topics,
+    is_infra_deploy_path,
+    is_test_path,
+    test_subject_hints,
+)
 
 
 DOC_EXTS = {".md", ".rst", ".txt"}
-TEST_HINTS = ("test", "tests", "pytest", "unittest")
 CONFIG_FILES = {
     "pyproject.toml",
     "requirements.txt",
@@ -32,25 +39,15 @@ def _is_doc(path: str) -> bool:
     }
 
 
-def _is_test(path: str) -> bool:
+def _is_plain_config(path: str) -> bool:
     p = path.lower()
     base = os.path.basename(p)
-    if p.startswith("tests/") or "/tests/" in p:
-        return True
-    if (
-        base.startswith("test_")
-        or base.endswith("_test.py")
-        or base.endswith(".spec.ts")
-        or base.endswith(".spec.tsx")
-    ):
-        return True
-    return any(h in p for h in TEST_HINTS)
+    return base in CONFIG_FILES or os.path.splitext(p)[1] in CONFIG_EXTS
 
 
 def _is_config(path: str) -> bool:
-    p = path.lower()
-    base = os.path.basename(p)
-    return base in CONFIG_FILES or os.path.splitext(p)[1] in CONFIG_EXTS
+    """Packaging/config files plus Docker, Compose, nginx, env templates."""
+    return _is_plain_config(path) or is_infra_deploy_path(path)
 
 
 def suggest_from_changes(
@@ -63,7 +60,7 @@ def suggest_from_changes(
     added_any = any(s.upper() == "A" for s, _ in changes) or has_commits is False
 
     docs = [p for p in paths if _is_doc(p)]
-    tests = [p for p in paths if _is_test(p)]
+    tests = [p for p in paths if is_test_path(p)]
     configs = [p for p in paths if _is_config(p)]
     has_tests = bool(tests)
     has_configs = bool(configs)
@@ -96,20 +93,29 @@ def suggest_from_changes(
         topics.append("README")
     if any(os.path.basename(p).lower() == "features.md" for p in paths):
         topics.append("FEATURES doc")
+    topics.extend(infra_deploy_topics(paths))
     if tests:
-        topics.append("tests")
-    if configs:
+        all_tests_only = bool(paths) and len(tests) == len(paths)
+        hints = test_subject_hints(paths)
+        if all_tests_only and hints:
+            head = " and ".join(hints[:3])
+            tail = f" (+{len(hints) - 3} more)" if len(hints) > 3 else ""
+            topics.append(f"tests for {head}{tail}")
+        else:
+            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")
 
-    if not topics:
-        topics = ["changes"]
-
     # Dedupe while preserving order
     seen: set[str] = set()
     topics = [t for t in topics if not (t in seen or seen.add(t))]
 
+    if not topics:
+        fb = basename_fallback_topic(paths)
+        topics = [fb] if fb else ["project files"]
+
     if len(topics) == 1:
         message = f"{verb} {topics[0]}"
     elif len(topics) == 2:
@@ -117,7 +123,12 @@ def suggest_from_changes(
     else:
         message = f"{verb} {topics[0]}, {topics[1]}, and {topics[2]}"
 
+    message += area_scope_suffix(paths)
+
     if added_any and has_commits is False and message.startswith("Add "):
         message = message.replace("Add ", "Add initial ", 1)
 
+    if len(message) > 72:
+        message = message[:72].rstrip()
+
     return Suggestion(add_args=paths, commit_type=commit_type, commit_message=message)

git_explain-1.1.4/git_explain/path_topics.py

@@ -0,0 +1,178 @@
+"""Derive concrete commit-message topics from paths (Docker, nginx, env templates, areas)."""
+
+from __future__ import annotations
+
+import os
+
+
+def _norm(p: str) -> str:
+    return p.replace("\\", "/").strip()
+
+
+_TEST_HINTS = ("pytest", "unittest", "tests/", "/tests/")
+
+
+def is_test_path(path: str) -> bool:
+    """True if path looks like a test file (mirrors heuristics rules; paths normalized)."""
+    p = _norm(path).lower()
+    base = os.path.basename(p)
+    if p.startswith("tests/") or "/tests/" in p:
+        return True
+    if (
+        base.startswith("test_")
+        or base.endswith("_test.py")
+        or base.endswith(".spec.ts")
+        or base.endswith(".spec.tsx")
+    ):
+        return True
+    return any(h in p for h in _TEST_HINTS)
+
+
+def test_subject_hints(paths: list[str]) -> list[str]:
+    """Short labels from test filenames, e.g. test_gemini.py -> gemini (deduped, stable order)."""
+    hints: list[str] = []
+    seen: set[str] = set()
+    for raw in paths:
+        if not is_test_path(raw):
+            continue
+        base = os.path.basename(_norm(raw))
+        stem, _ext = os.path.splitext(base)
+        s = stem
+        low = s.lower()
+        if low.startswith("test_"):
+            core = s[5:]
+        elif low.endswith("_test"):
+            core = s[: -len("_test")]
+        else:
+            core = s
+        core = core.strip().replace("_", " ").strip()
+        if not core:
+            continue
+        key = core.lower()
+        if key not in seen:
+            seen.add(key)
+            hints.append(core)
+    return hints
+
+
+def is_infra_deploy_path(path: str) -> bool:
+    """True if path looks like Docker, Compose, nginx, or env-template deploy config."""
+    p = _norm(path).lower()
+    base = os.path.basename(p)
+    if base == "dockerfile" or base.endswith(".dockerfile"):
+        return True
+    if base == ".dockerignore":
+        return True
+    if base.startswith("docker-compose") and base.endswith((".yml", ".yaml")):
+        return True
+    if base in ("compose.yaml", "compose.yml"):
+        return True
+    if "nginx" in base and base.endswith(".conf"):
+        return True
+    if base.endswith((".env.example", ".env.sample")):
+        return True
+    if base in ("compose.env.example", ".env.example"):
+        return True
+    return False
+
+
+def infra_deploy_topics(paths: list[str]) -> list[str]:
+    """Ordered, deduplicated topic phrases (no leading verb)."""
+    has_dockerfile = False
+    has_dockerignore = False
+    has_compose = False
+    has_nginx = False
+    has_env_example = False
+
+    for raw in paths:
+        p = _norm(raw).lower()
+        base = os.path.basename(p)
+        if base == "dockerfile" or base.endswith(".dockerfile"):
+            has_dockerfile = True
+        if base == ".dockerignore":
+            has_dockerignore = True
+        if base.startswith("docker-compose") and base.endswith((".yml", ".yaml")):
+            has_compose = True
+        if base in ("compose.yaml", "compose.yml"):
+            has_compose = True
+        if "nginx" in base and base.endswith(".conf"):
+            has_nginx = True
+        if base.endswith((".env.example", ".env.sample")):
+            has_env_example = True
+        if base in ("compose.env.example", ".env.example"):
+            has_env_example = True
+
+    topics: list[str] = []
+    seen: set[str] = set()
+
+    def add(s: str) -> None:
+        if s not in seen:
+            seen.add(s)
+            topics.append(s)
+
+    if has_dockerfile or has_dockerignore:
+        add("Docker")
+    if has_compose:
+        add("Docker Compose")
+    if has_nginx:
+        add("nginx")
+    if has_env_example:
+        add("env examples")
+
+    return topics
+
+
+def area_scope_suffix(paths: list[str]) -> str:
+    """Return ' for api and frontend' style suffix, or ''."""
+    labels: list[str] = []
+    seen: set[str] = set()
+
+    for raw in paths:
+        p = _norm(raw)
+        if not p or p == ".":
+            continue
+        parts = [x for x in p.split("/") if x]
+        if len(parts) < 2:
+            continue
+        first, second = parts[0], parts[1]
+        if first.lower() in {"apps", "packages", "services"}:
+            label = second
+        else:
+            label = first
+        low = label.lower()
+        if low not in seen:
+            seen.add(low)
+            labels.append(label)
+
+    if not labels:
+        return ""
+
+    def fmt(lbl: str) -> str:
+        return "API" if lbl.lower() == "api" else lbl
+
+    labels = [fmt(x) for x in labels]
+    if len(labels) == 1:
+        return f" for {labels[0]}"
+    if len(labels) == 2:
+        return f" for {labels[0]} and {labels[1]}"
+    return f" for {labels[0]}, {labels[1]}, and {labels[2]}"
+
+
+def basename_fallback_topic(paths: list[str], max_names: int = 4) -> str | None:
+    """Short description from basenames when no other topic matched."""
+    bases: list[str] = []
+    seen: set[str] = set()
+    for raw in paths:
+        b = os.path.basename(_norm(raw))
+        if not b:
+            continue
+        key = b.lower()
+        if key not in seen:
+            seen.add(key)
+            bases.append(b)
+    if not bases:
+        return None
+    if len(bases) <= max_names:
+        return ", ".join(bases)
+    head = ", ".join(bases[:max_names])
+    return f"{head} (+{len(bases) - max_names} more)"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-explain
-Version: 1.1.2
+Version: 1.1.4
 Summary: CLI that suggests git add/commit from diffs using Gemini
 Author: git-explain contributors
 License-Expression: MIT
@@ -68,13 +68,27 @@ pip install -e .
 
 ## API key (for `--ai` only)
 
-Put your Gemini API key in a `.env` file where you run the CLI, or set it in your environment:
+**Option 1 — Environment variable** (recommended for production, CI, scripts):
+
+```powershell
+# PowerShell
+$env:GEMINI_API_KEY = "your_key_here"
+```
+
+```bash
+# Bash / Zsh
+export GEMINI_API_KEY=your_key_here
+```
+
+**Option 2 — `.env` file** (convenient for local development):
+
+Create a `.env` file where you run the CLI:
 
 ```
 GEMINI_API_KEY=your_key_here
 ```
 
-Or use `GOOGLE_API_KEY`. Optional: set `GEMINI_MODEL` to override the default (e.g. `GEMINI_MODEL=gemini-2.5-flash`). See [Troubleshooting](#troubleshooting) for 404/429.
+You can also use `GOOGLE_API_KEY`. Optional: set `GEMINI_MODEL` to override the default (e.g. `GEMINI_MODEL=gemini-2.5-flash`). See [Troubleshooting](#troubleshooting) for 404/429.
 
 ---
 

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

@@ -6,6 +6,7 @@ git_explain/cli.py
 git_explain/gemini.py
 git_explain/git.py
 git_explain/heuristics.py
+git_explain/path_topics.py
 git_explain/run.py
 git_explain.egg-info/PKG-INFO
 git_explain.egg-info/SOURCES.txt

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "git-explain"
-version = "v1.1.2"
+version = "v1.1.4"
 description = "CLI that suggests git add/commit from diffs using Gemini"
 readme = "README.md"
 requires-python = ">=3.10"

git_explain-1.1.4/tests/test_gemini.py

@@ -0,0 +1,73 @@
+from git_explain.gemini import (
+    COMMIT_LINE_CONVENTIONAL_RE,
+    COMMIT_LINE_RE,
+    _fallback_type_and_message_with_context,
+    _is_generic_message,
+)
+
+
+def test_commit_line_re_matches_tests_not_test() -> None:
+    """COMMIT_LINE_RE should match [TESTS] but not [TEST]."""
+    line_tests = 'git commit -m "[TESTS] Add unit tests"'
+    m = COMMIT_LINE_RE.match(line_tests)
+    assert m is not None
+    assert m.group(1).upper() == "TESTS"
+    assert "Add unit tests" in m.group(2)
+
+    line_test = 'git commit -m "[TEST] Add unit test"'
+    m = COMMIT_LINE_RE.match(line_test)
+    assert m is None
+
+
+def test_commit_line_conventional_re_matches_tests() -> None:
+    """COMMIT_LINE_CONVENTIONAL_RE should match 'tests:' not 'test:'."""
+    line = 'git commit -m "tests: add unit tests"'
+    m = COMMIT_LINE_CONVENTIONAL_RE.match(line)
+    assert m is not None
+    assert m.group(1).lower() == "tests"
+
+    line_test = 'git commit -m "test: add unit test"'
+    m = COMMIT_LINE_CONVENTIONAL_RE.match(line_test)
+    assert m is None
+
+
+def test_commit_line_re_matches_other_types() -> None:
+    for line in [
+        'git commit -m "[FEAT] Add feature"',
+        'git commit -m "[FIX] Fix bug"',
+        'git commit -m "[DOCS] Update readme"',
+        'git commit -m "[REFACTOR] Simplify logic"',
+        'git commit -m "[CHORE] Add Docker and nginx config"',
+    ]:
+        m = COMMIT_LINE_RE.match(line)
+        assert m is not None, f"Expected match for {line}"
+
+
+def test_commit_line_conventional_matches_chore() -> None:
+    line = 'git commit -m "chore: add docker compose"'
+    m = COMMIT_LINE_CONVENTIONAL_RE.match(line)
+    assert m is not None
+    assert m.group(1).lower() == "chore"
+
+
+def test_is_generic_message_flags_vague_add_changes() -> None:
+    assert _is_generic_message("Add changes") is True
+    assert _is_generic_message("Update changes") is True
+    assert _is_generic_message("Add Docker and nginx for api") is False
+
+
+def test_is_generic_message_flags_update_project_files() -> None:
+    assert _is_generic_message("Update project files") is True
+    assert _is_generic_message("Add project files") is True
+    assert _is_generic_message("Update tests for gemini and heuristics") is False
+
+
+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"],
+        added_any=False,
+        has_commits=True,
+    )
+    assert ctype == "TEST"
+    assert "gemini" in msg.lower()
+    assert "heuristics" in msg.lower()

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

@@ -39,3 +39,40 @@ def test_config_only_is_chore_not_test() -> None:
         has_commits=True,
     )
     assert s.commit_type == "CHORE"
+
+
+def test_test_only_paths_get_specific_test_message() -> None:
+    s = suggest_from_changes(
+        changes=[
+            ("M", "tests/test_gemini.py"),
+            ("M", "tests/test_heuristics.py"),
+        ],
+        has_commits=True,
+    )
+    assert s.commit_type == "TEST"
+    m = s.commit_message.lower()
+    assert "gemini" in m
+    assert "heuristics" in m
+    assert "project files" not in m
+
+
+def test_docker_nginx_env_paths_get_specific_chore_message() -> None:
+    """Infra paths should not collapse to 'Add changes'."""
+    s = suggest_from_changes(
+        changes=[
+            ("A", "api/app/.env.example"),
+            ("A", "api/app/Dockerfile"),
+            ("A", "apps/frontend/.dockerignore"),
+            ("A", "apps/frontend/Dockerfile"),
+            ("A", "apps/frontend/nginx.conf"),
+            ("A", "compose.env.example"),
+        ],
+        has_commits=True,
+    )
+    assert s.commit_type == "CHORE"
+    m = s.commit_message.lower()
+    assert "docker" in m
+    assert "nginx" in m
+    assert "env" in m
+    assert "changes" not in m
+    assert "api" in m and "frontend" in m

git_explain-1.1.2/tests/test_gemini.py

@@ -1,37 +0,0 @@
-from git_explain.gemini import COMMIT_LINE_CONVENTIONAL_RE, COMMIT_LINE_RE
-
-
-def test_commit_line_re_matches_tests_not_test() -> None:
-    """COMMIT_LINE_RE should match [TESTS] but not [TEST]."""
-    line_tests = 'git commit -m "[TESTS] Add unit tests"'
-    m = COMMIT_LINE_RE.match(line_tests)
-    assert m is not None
-    assert m.group(1).upper() == "TESTS"
-    assert "Add unit tests" in m.group(2)
-
-    line_test = 'git commit -m "[TEST] Add unit test"'
-    m = COMMIT_LINE_RE.match(line_test)
-    assert m is None
-
-
-def test_commit_line_conventional_re_matches_tests() -> None:
-    """COMMIT_LINE_CONVENTIONAL_RE should match 'tests:' not 'test:'."""
-    line = 'git commit -m "tests: add unit tests"'
-    m = COMMIT_LINE_CONVENTIONAL_RE.match(line)
-    assert m is not None
-    assert m.group(1).lower() == "tests"
-
-    line_test = 'git commit -m "test: add unit test"'
-    m = COMMIT_LINE_CONVENTIONAL_RE.match(line_test)
-    assert m is None
-
-
-def test_commit_line_re_matches_other_types() -> None:
-    for line in [
-        'git commit -m "[FEAT] Add feature"',
-        'git commit -m "[FIX] Fix bug"',
-        'git commit -m "[DOCS] Update readme"',
-        'git commit -m "[REFACTOR] Simplify logic"',
-    ]:
-        m = COMMIT_LINE_RE.match(line)
-        assert m is not None, f"Expected match for {line}"