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

{git_explain-2.1.9 → git_explain-2.2.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: git-explain
-Version: 2.1.9
+Version: 2.2.0
 Summary: CLI that suggests git add/commit from diffs using Gemini
-Author: git-explain contributors
+Author: nazarli-shabnam
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/nazarli-shabnam/git-explain
 Project-URL: Source, https://github.com/nazarli-shabnam/git-explain
@@ -51,6 +51,14 @@ pip install git-explain
 pip install -e .
 ```
 
+**Clone:** install deps (`requirements.txt` is fine), `cd` into the repo, then:
+
+```bash
+python -m git_explain
+```
+
+Run that from the repo root so Python picks up the `git_explain` folder—no `pip install -e .` needed.
+
 Optional: install a specific tag from GitHub instead of PyPI:
 
 ```bash
@@ -70,6 +78,8 @@ pip install "git+https://github.com/nazarli-shabnam/git-explain.git@v2.1.8"
 
 Heuristics guess a sensible type and message from paths and statuses. **No account, no key, no network** for that path.
 
+Suggested commits follow **[Conventional Commits](https://www.conventionalcommits.org/)**—`feat: …`, `fix: …`, optional `(scope)`, and so on—so changelogs and release tools can read them.
+
 ---
 
 ## Optional: Gemini
@@ -80,7 +90,7 @@ If you want sharper messages, set **`GEMINI_API_KEY`** (or `GOOGLE_API_KEY`) in
 |--------|----------------|
 | `git-explain --ai` | AI sees **paths and change type** only (no file contents). |
 | `git-explain --ai --with-diff` | AI also sees the **diff**—better detail; only use if you’re OK sending that to the API. |
-| `git-explain --suggest` | **Staged files only**; prints one **`git commit -m "..."`** line for scripting. Needs AI; don’t combine with other flags. |
+| `git-explain --suggest` | **Staged only**; prints one plain `git commit -m "…"` line (easy to copy). Needs AI; don’t combine with other flags. |
 
 Everything else (`--auto`, `--staged-only`, `--cwd`, model override, shell completion): **`git-explain --help`**.
 

{git_explain-2.1.9 → git_explain-2.2.0}/README.md

@@ -20,6 +20,14 @@ pip install git-explain
 pip install -e .
 ```
 
+**Clone:** install deps (`requirements.txt` is fine), `cd` into the repo, then:
+
+```bash
+python -m git_explain
+```
+
+Run that from the repo root so Python picks up the `git_explain` folder—no `pip install -e .` needed.
+
 Optional: install a specific tag from GitHub instead of PyPI:
 
 ```bash
@@ -39,6 +47,8 @@ pip install "git+https://github.com/nazarli-shabnam/git-explain.git@v2.1.8"
 
 Heuristics guess a sensible type and message from paths and statuses. **No account, no key, no network** for that path.
 
+Suggested commits follow **[Conventional Commits](https://www.conventionalcommits.org/)**—`feat: …`, `fix: …`, optional `(scope)`, and so on—so changelogs and release tools can read them.
+
 ---
 
 ## Optional: Gemini
@@ -49,7 +59,7 @@ If you want sharper messages, set **`GEMINI_API_KEY`** (or `GOOGLE_API_KEY`) in
 |--------|----------------|
 | `git-explain --ai` | AI sees **paths and change type** only (no file contents). |
 | `git-explain --ai --with-diff` | AI also sees the **diff**—better detail; only use if you’re OK sending that to the API. |
-| `git-explain --suggest` | **Staged files only**; prints one **`git commit -m "..."`** line for scripting. Needs AI; don’t combine with other flags. |
+| `git-explain --suggest` | **Staged only**; prints one plain `git commit -m "…"` line (easy to copy). Needs AI; don’t combine with other flags. |
 
 Everything else (`--auto`, `--staged-only`, `--cwd`, model override, shell completion): **`git-explain --help`**.
 

git_explain-2.2.0/git_explain/__init__.py

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

git_explain-2.2.0/git_explain/__main__.py

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

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

@@ -2,7 +2,7 @@
 
 import re
 import subprocess
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Iterable
 
@@ -12,14 +12,18 @@ from rich.console import Console
 from rich.panel import Panel
 from rich.text import Text
 
-from git_explain.gemini import suggest_commands
+from git_explain.gemini import Suggestion, suggest_commands
 from git_explain.heuristics import suggest_from_changes
 from git_explain.git import (
     get_combined_diff,
     get_diff_for_paths,
     get_staged_diff_for_paths,
 )
-from git_explain.run import apply_commands, normalize_commit_subject_for_dash_m
+from git_explain.run import (
+    apply_commands,
+    format_commit_message,
+    normalize_commit_subject_for_dash_m,
+)
 
 load_dotenv()
 app = typer.Typer()
@@ -344,13 +348,10 @@ def run(
             raise typer.Exit(1)
 
         cmsg = normalize_commit_subject_for_dash_m(sug.commit_message)
-        console.print(
-            Panel(
-                f'git commit -m "[{sug.commit_type}] {cmsg}"',
-                title="Suggested commit command",
-                border_style="green",
-            )
+        full = format_commit_message(
+            sug.commit_type, cmsg, scope=sug.scope, breaking=sug.breaking
         )
+        print(f'git commit -m "{full}"')
         return
 
     if staged_only:
@@ -422,9 +423,8 @@ def run(
 
     def suggest_for(
         change_items: list[tuple[str, str]], title: str
-    ) -> tuple[list[str], str, str, str, str | None]:
-        # Returns (paths, type, message, raw_text, ai_fallback_reason).
-        # ai_fallback_reason is set when --ai was used but heuristics were used instead.
+    ) -> tuple[Suggestion, str | None]:
+        """Return (suggestion, ai_fallback_reason)."""
         paths_for_infer = [p for _, p in change_items]
         infer_diff: str | None = None
         if paths_for_infer:
@@ -444,7 +444,7 @@ def run(
                 if diff_text:
                     payload = payload + "\n\n## Diff\n" + diff_text
             try:
-                sug, raw = suggest_commands(
+                sug, _raw = suggest_commands(
                     payload,
                     model=model,
                     with_diff=with_diff,
@@ -452,27 +452,20 @@ def run(
                 )
                 if sug is None:
                     raise RuntimeError("Could not parse AI suggestion.")
-                return sug.add_args, sug.commit_type, sug.commit_message, raw, None
+                return sug, None
             except Exception as e:
-                # Fall back to heuristics on quota / API errors
                 h = suggest_from_changes(
                     changes=change_items,
                     has_commits=has_commits,
                     diff_text=infer_diff,
                 )
-                return (
-                    h.add_args,
-                    h.commit_type,
-                    h.commit_message,
-                    "",
-                    str(e),
-                )
+                return h, str(e)
         h = suggest_from_changes(
             changes=change_items,
             has_commits=has_commits,
             diff_text=infer_diff,
         )
-        return h.add_args, h.commit_type, h.commit_message, "", None
+        return h, None
 
     selected_pairs = [(ch.status, ch.path) for ch in selected]
     unique_paths = {p for _, p in selected_pairs}
@@ -492,18 +485,18 @@ def run(
             if mode_input in ("one", "split"):
                 mode = mode_input
 
-    plan: list[tuple[str, list[str], str, str]] = []
+    plan: list[tuple[str, Suggestion]] = []
     ai_fallback_notes: list[tuple[str, str]] = []
     if mode == "split":
         groups = _group_changes(selected_pairs)
         for gname, items in groups.items():
-            paths, ctype, cmsg, _raw, fb = suggest_for(items, title=gname.capitalize())
-            plan.append((gname, paths, ctype, cmsg))
+            sug, fb = suggest_for(items, title=gname.capitalize())
+            plan.append((gname, sug))
             if fb:
                 ai_fallback_notes.append((gname, fb))
     else:
-        paths, ctype, cmsg, _raw, fb = suggest_for(selected_pairs, title="Selected")
-        plan.append(("one", paths, ctype, cmsg))
+        sug, fb = suggest_for(selected_pairs, title="Selected")
+        plan.append(("one", sug))
         if fb:
             ai_fallback_notes.append(("", fb))
 
@@ -530,12 +523,15 @@ def run(
             )
         )
 
-    def _render_plan(pl: list[tuple[str, list[str], str, str]]) -> str:
+    def _render_plan(pl: list[tuple[str, Suggestion]]) -> str:
         rendered: list[str] = []
-        for name, paths, ctype, cmsg in pl:
-            add_line = "git add -A -- " + " ".join(_ps_quote(p) for p in paths)
-            subj = normalize_commit_subject_for_dash_m(cmsg)
-            commit_line = f'git commit -m "[{ctype}] {subj}"'
+        for name, sug in pl:
+            add_line = "git add -A -- " + " ".join(_ps_quote(p) for p in sug.add_args)
+            subj = normalize_commit_subject_for_dash_m(sug.commit_message)
+            full = format_commit_message(
+                sug.commit_type, subj, scope=sug.scope, breaking=sug.breaking
+            )
+            commit_line = f'git commit -m "{full}"'
             rendered.append(f"### {name}\n{add_line}\n{commit_line}")
         return "\n\n".join(rendered)
 
@@ -557,29 +553,35 @@ def run(
             .lower()
         )
         if edit_choice in ("y", "yes"):
-            updated: list[tuple[str, list[str], str, str]] = []
-            for name, paths, ctype, cmsg in plan:
+            updated: list[tuple[str, Suggestion]] = []
+            for name, sug in plan:
+                current = format_commit_message(
+                    sug.commit_type,
+                    sug.commit_message,
+                    scope=sug.scope,
+                    breaking=sug.breaking,
+                )
                 console.print(
-                    f"[dim]{name}:[/dim] current message: [bold][{ctype}] {cmsg}[/bold]"
+                    f"[dim]{name}:[/dim] current message: [bold]{current}[/bold]"
                 )
                 try:
                     from prompt_toolkit import prompt as pt_prompt
 
                     new_msg = (
                         pt_prompt(
-                            "New commit message (subject only, no [TYPE] prefix): ",
-                            default=cmsg,
+                            "New commit message (subject only, type/scope added automatically): ",
+                            default=sug.commit_message,
                         ).strip()
-                        or cmsg
+                        or sug.commit_message
                     )
                 except Exception:
                     new_msg = (
                         typer.prompt(
-                            "New commit message (subject only, no [TYPE] prefix)",
-                            default=cmsg,
+                            "New commit message (subject only, type/scope added automatically)",
+                            default=sug.commit_message,
                         ).strip()
-                    ) or cmsg
-                updated.append((name, paths, ctype, new_msg))
+                    ) or sug.commit_message
+                updated.append((name, replace(sug, commit_message=new_msg)))
             plan = updated
             console.print(
                 Panel(
@@ -601,13 +603,16 @@ def run(
         do_apply = choice == "auto" or choice in ("y", "yes")
 
     if do_apply:
-        for name, paths, ctype, cmsg in plan:
+        for name, sug in plan:
             try:
                 apply_commands(
                     repo_root,
-                    [] if staged_only else paths,
-                    ctype,
-                    cmsg,
+                    [] if staged_only else sug.add_args,
+                    sug.commit_type,
+                    sug.commit_message,
+                    scope=sug.scope,
+                    body=sug.body,
+                    breaking=sug.breaking,
                     staged_only=staged_only,
                 )
                 console.print(f"[green]Commit created ({name}).[/green]")

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

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

{git_explain-2.1.9 → git_explain-2.2.0}/git_explain/gemini.py

@@ -12,12 +12,31 @@ from git_explain.commit_infer import refine_type_and_message_from_diff
 from git_explain.path_topics import (
     area_scope_suffix,
     basename_fallback_topic,
+    infer_scope,
     infra_deploy_topics,
     is_test_path,
     test_subject_hints,
 )
 
-SYSTEM_PROMPT = """You are given a list of changed/added files under ## Staged, ## Unstaged, ## Untracked.
+VALID_TYPES = frozenset(
+    {
+        "FEAT",
+        "FIX",
+        "DOCS",
+        "REFACTOR",
+        "TEST",
+        "CHORE",
+        "BUILD",
+        "CI",
+        "STYLE",
+        "PERF",
+        "REVERT",
+    }
+)
+
+_TYPE_RE_ALT = "|".join(sorted(VALID_TYPES | {"TESTS"}, key=len, reverse=True))
+
+SYSTEM_PROMPT = f"""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
 - M = modified
@@ -25,56 +44,81 @@ Each file line is: <STATUS> <PATH> where STATUS is one of:
 - R = renamed
 - C = copied
 
-Suggest one commit that includes ALL of these files.
+Suggest one commit that includes ALL of these files using Conventional Commits format.
 
 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, CHORE.
-3. The message must describe **what the change does** (behavior, feature, fix)—not a comma-separated list of folders or path segments. You may mention one path if it disambiguates, but the subject must state substance (e.g. "Document FEATURES and tighten Gemini prompt for commit suggestions" not "update gemini, readme, features"). Never use only generic words like "update", "changes", or "refactor" by themselves.
-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 [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 mood, no period at end. The subject may be up to about 200 characters when needed—finish the thought completely (no cut-off mid-phrase).
+2. Line 2 must be: git commit -m "type(scope): description"
+   - type: exactly one of: feat, fix, docs, refactor, test, chore, build, ci, style, perf
+   - scope (optional): a noun in parentheses describing the area of the codebase (e.g., cli, api, parser). Omit if the change spans many unrelated areas.
+   - If the change introduces a breaking API change, add ! after the type/scope: feat!: or feat(api)!:
+   - description: imperative mood, lowercase first letter, no period at end. Up to about 200 characters—finish the thought completely.
+3. The description must state **what the change does** (behavior, feature, fix)—not a comma-separated list of folders or path segments. You may mention one path if it disambiguates. Never use only generic words like "update", "changes", or "refactor" by themselves.
+4. Infer concrete artifacts from paths when obvious: Dockerfiles, Docker Compose files, nginx configs, .env/.env.example templates, CI workflows—not vague summaries. For test paths (e.g. tests/test_foo.py), name the area under test (e.g. "expand tests for foo and bar").
+5. Use fix when the change corrects broken behavior, wrong CLI flow, or misleading errors—not refactor for those cases.
+6. Use build for build system / dependency changes (Dockerfile, pyproject.toml, requirements.txt, Makefile). Use ci for CI/CD config (.github/workflows, .gitlab-ci.yml, etc.).
 
 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"
+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"
+Example for Docker + nginx under api/:
+git add api/Dockerfile api/nginx.conf
+git commit -m "build(api): add Docker and nginx configuration"
 """
 
-SYSTEM_PROMPT_WITH_DIFF = """You are given:
+SYSTEM_PROMPT_WITH_DIFF = f"""You are given:
 1. A list of changed/added files (## Staged, ## Unstaged, ## Untracked) with <STATUS> <PATH>.
-2. The full diff (## Staged diff, ## Unstaged diff, ## Untracked) showing exact code changes.
+2. The full diff (## Diff) showing exact code changes.
 
-Use the diff to write a **specific, detailed** commit message about **what changed in behavior, UI, data flow, or APIs**. Quote or paraphrase the actual diff: new props, renamed state, conditional logic, extracted components, bug fixes, etc.
-**Do not** summarize by only listing directories, modules, or file names (e.g. forbidden: "update layout, issues, workspace-views"). If many files move together, state the **theme** of the change in plain language (e.g. "align filter panels and toolbar actions across issue list and workspace views").
-Avoid hollow words like "update" or "changes" without saying what moved or why. Naming Docker, nginx, env templates, or workflows is fine when the diff is about those.
-Prefer **fix:** when the diff corrects incorrect behavior or user-visible bugs; use **refactor:** only for internal restructuring without behavior change.
+Use the diff to write a **specific, detailed** commit message in Conventional Commits format about **what changed in behavior, UI, data flow, or APIs**. Quote or paraphrase the actual diff: new props, renamed state, conditional logic, extracted components, bug fixes, etc.
+**Do not** summarize by only listing directories, modules, or file names. If many files move together, state the **theme** of the change in plain language.
+Avoid hollow words like "update" or "changes" without saying what moved or why.
+Prefer fix when the diff corrects incorrect behavior or user-visible bugs; use refactor only for internal restructuring without behavior change.
+Use build for build/dependency changes, ci for CI/CD config changes.
 
-Output format (conventional commits style):
+Output format:
 - 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, chore.
-  Subject: imperative mood, no period at end. Use **up to about 200 characters** when the diff needs it—**complete the sentence**; never stop mid-word or mid-parenthetical.
+- Line 2: git commit -m "type(scope): description"
+  - type: exactly one of: feat, fix, docs, refactor, test, chore, build, ci, style, perf
+  - scope (optional): noun in parentheses describing the area. Omit if change spans many areas.
+  - If breaking change, add ! after type/scope: feat!: or feat(api)!:
+  - description: imperative mood, lowercase first letter, no period at end. Up to 200 characters—complete the sentence, never cut mid-word.
 
 Example:
 git add git_explain/cli.py git_explain/gemini.py
-git commit -m "feat: add opt-in --with-diff for detailed AI commit messages"
+git commit -m "feat(cli): 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|CHORE)\]\s*(.+?)["\']',
+    r"git\s+commit\s+-m\s+[\"']"
+    rf"({_TYPE_RE_ALT})"
+    r"(?:\(([^)]*)\))?"
+    r"(!?)"
+    r"\s*:\s*(.+?)"
+    r"[\"']",
     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|chore)\s*:\s*(.+?)["\']',
+
+_COMMIT_LINE_BRACKET_RE = re.compile(
+    r"git\s+commit\s+-m\s+[\"']"
+    rf"\[({_TYPE_RE_ALT})\]"
+    r"\s*(.+?)"
+    r"[\"']",
     re.IGNORECASE,
 )
+
 DEFAULT_MODEL = "gemini-2.5-flash"
 
+
+def _normalize_type(t: str) -> str:
+    upper = (t or "").upper()
+    if upper == "TESTS":
+        return "TEST"
+    return upper if upper in VALID_TYPES else "CHORE"
+
 # Single-line subject for `git commit -m` (no body); allow longer than classic 72 when users want detail.
 MAX_COMMIT_SUBJECT_CHARS = 200
 
@@ -318,22 +362,18 @@ def _fallback_type_and_message_with_context(
         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}")
+            if len(hints) <= 4:
+                head = ", ".join(hints[:-1]) + " and " + hints[-1] if len(hints) > 1 else hints[0]
+            else:
+                head = ", ".join(hints[:4])
+            topics.append(f"tests for {head}")
         else:
             topics.append("tests")
     if touches_docs and not docs_only:
         topics.append("docs")
     code_topics = _code_topics(files)
     if code_topics:
-        if len(code_topics) <= 3:
-            label = ", ".join(code_topics)
-        else:
-            head = ", ".join(code_topics[:3])
-            rest = len(code_topics) - 3
-            label = f"{head} and {rest} related areas"
-        topics.append(label)
+        topics.append(", ".join(code_topics[:5]))
     if touches_packaging:
         topics.append("packaging config")
 
@@ -405,6 +445,9 @@ class Suggestion:
     add_args: list[str]
     commit_type: str
     commit_message: str
+    scope: str | None = None
+    body: str | None = None
+    breaking: bool = False
 
 
 def _get_client() -> genai.Client:
@@ -481,20 +524,24 @@ def suggest_commands(
     add_args: list[str] = []
     commit_type = "REFACTOR"
     commit_message = "update"
+    scope: str | None = None
+    breaking = False
     for line in lines:
         add_m = ADD_LINE_RE.match(line)
         if add_m:
             add_args = [f.strip() for f in add_m.group(1).split() if f.strip()]
             continue
-        commit_m = COMMIT_LINE_CONVENTIONAL_RE.match(line) if with_diff else None
-        if commit_m:
-            commit_type = commit_m.group(1).upper()
-            commit_message = commit_m.group(2).strip().rstrip(".")
-            break
         commit_m = COMMIT_LINE_RE.match(line)
         if commit_m:
-            commit_type = commit_m.group(1).upper()
-            commit_message = commit_m.group(2).strip().rstrip(".")
+            commit_type = _normalize_type(commit_m.group(1))
+            scope = commit_m.group(2) or None
+            breaking = commit_m.group(3) == "!"
+            commit_message = commit_m.group(4).strip().rstrip(".")
+            break
+        bracket_m = _COMMIT_LINE_BRACKET_RE.match(line)
+        if bracket_m:
+            commit_type = _normalize_type(bracket_m.group(1))
+            commit_message = bracket_m.group(2).strip().rstrip(".")
             break
     if not add_args or not commit_message:
         return None, raw
@@ -507,11 +554,9 @@ def suggest_commands(
     all_paths = [p for _, p in entries]
     added_any = any(s == "A" for s, _ in entries)
 
-    # Always use the full path list we sent (model may truncate or omit)
     if all_paths:
         add_args = all_paths
 
-    # If we're adding new files (or this is an initial commit), don't label it REFACTOR
     docs_only = all_paths and all(
         os.path.splitext(p)[1].lower() in {".md", ".rst", ".txt"} for p in all_paths
     )
@@ -523,6 +568,9 @@ def suggest_commands(
             files=add_args, added_any=added_any, has_commits=has_commits
         )
 
+    if scope is None:
+        scope = infer_scope(add_args)
+
     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]
@@ -531,5 +579,9 @@ def suggest_commands(
     )
 
     return Suggestion(
-        add_args=add_args, commit_type=commit_type, commit_message=commit_message
+        add_args=add_args,
+        commit_type=commit_type,
+        commit_message=commit_message,
+        scope=scope,
+        breaking=breaking,
     ), raw

{git_explain-2.1.9 → git_explain-2.2.0}/git_explain/heuristics.py

@@ -14,7 +14,10 @@ from git_explain.gemini import (
 from git_explain.path_topics import (
     area_scope_suffix,
     basename_fallback_topic,
+    infer_scope,
     infra_deploy_topics,
+    is_build_path,
+    is_ci_path,
     is_infra_deploy_path,
     is_test_path,
     test_subject_hints,
@@ -105,25 +108,33 @@ def suggest_from_changes(
     docs = [p for p in paths if _is_doc(p)]
     tests = [p for p in paths if is_test_path(p)]
     configs = [p for p in paths if _is_config(p)]
+    ci_files = [p for p in paths if is_ci_path(p)]
+    build_files = [p for p in paths if is_build_path(p)]
     has_tests = bool(tests)
     has_configs = bool(configs)
     non_docs = [p for p in paths if p not in docs]
 
     docs_only = bool(paths) and len(docs) == len(paths)
+    ci_only = bool(paths) and len(ci_files) == len(paths)
+    build_only = bool(paths) and len(build_files) == len(paths)
     mostly_tests_or_config = False
     if non_docs:
         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
 
     if has_commits is False:
-        verb = "Add"
+        verb = "add"
     elif added_any and not modified_any:
-        verb = "Add"
+        verb = "add"
     else:
-        verb = "Update"
+        verb = "update"
 
     if docs_only:
         commit_type = "DOCS"
+    elif ci_only:
+        commit_type = "CI"
+    elif build_only:
+        commit_type = "BUILD"
     elif mostly_tests_or_config:
         if has_tests and not has_configs:
             commit_type = "TEST"
@@ -146,22 +157,18 @@ def suggest_from_changes(
         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}")
+            if len(hints) <= 4:
+                head = ", ".join(hints[:-1]) + " and " + hints[-1] if len(hints) > 1 else hints[0]
+            else:
+                head = ", ".join(hints[:4])
+            topics.append(f"tests for {head}")
         else:
             topics.append("tests")
     if any(_is_plain_config(p) for p in paths):
         topics.append("config")
     code_topics = _code_topics(paths)
     if code_topics:
-        if len(code_topics) <= 3:
-            label = ", ".join(code_topics)
-        else:
-            head = ", ".join(code_topics[:3])
-            rest = len(code_topics) - 3
-            label = f"{head} and {rest} related areas"
-        topics.append(label)
+        topics.append(", ".join(code_topics[:5]))
 
     # Dedupe while preserving order
     seen: set[str] = set()
@@ -178,15 +185,15 @@ def suggest_from_changes(
     else:
         message = f"{verb} {topics[0]}, {topics[1]}, and {topics[2]}"
 
-    scope = area_scope_suffix(paths)
-    if scope:
-        scope_key = _alnum_key(scope.replace("for", "", 1))
+    scope_suffix = area_scope_suffix(paths)
+    if scope_suffix:
+        scope_key = _alnum_key(scope_suffix.replace("for", "", 1))
         msg_key = _alnum_key(message)
         if scope_key and scope_key not in msg_key:
-            message += scope
+            message += scope_suffix
 
-    if added_any and has_commits is False and message.startswith("Add "):
-        message = message.replace("Add ", "Add initial ", 1)
+    if added_any and has_commits is False and message.startswith("add "):
+        message = message.replace("add ", "add initial ", 1)
 
     message = truncate_commit_subject(message, MAX_COMMIT_SUBJECT_CHARS)
 
@@ -194,4 +201,11 @@ def suggest_from_changes(
         commit_type, message, diff_text
     )
 
-    return Suggestion(add_args=paths, commit_type=commit_type, commit_message=message)
+    cc_scope = infer_scope(paths)
+
+    return Suggestion(
+        add_args=paths,
+        commit_type=commit_type,
+        commit_message=message,
+        scope=cc_scope,
+    )

{git_explain-2.1.9 → git_explain-2.2.0}/git_explain/path_topics.py

@@ -158,6 +158,86 @@ def area_scope_suffix(paths: list[str]) -> str:
     return f" for {labels[0]}, {labels[1]}, and {labels[2]}"
 
 
+_CI_FILES = {
+    ".gitlab-ci.yml",
+    ".travis.yml",
+    "azure-pipelines.yml",
+    "jenkinsfile",
+    "bitbucket-pipelines.yml",
+}
+
+
+def is_ci_path(path: str) -> bool:
+    """True if path looks like a CI/CD configuration file."""
+    p = _norm(path).lower()
+    base = os.path.basename(p)
+    if ".github/workflows/" in p or ".github/actions/" in p:
+        return True
+    if base in _CI_FILES:
+        return True
+    if ".circleci/" in p:
+        return True
+    return False
+
+
+_BUILD_FILES = {
+    "pyproject.toml",
+    "setup.py",
+    "setup.cfg",
+    "requirements.txt",
+    "requirements-dev.txt",
+    "makefile",
+    "gnumakefile",
+    "package.json",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "cargo.toml",
+    "cargo.lock",
+    "go.mod",
+    "go.sum",
+    "gemfile",
+    "gemfile.lock",
+    "build.gradle",
+    "pom.xml",
+}
+
+
+def is_build_path(path: str) -> bool:
+    """True if path is a build system, packaging, or containerization file."""
+    p = _norm(path).lower()
+    base = os.path.basename(p)
+    if base in _BUILD_FILES:
+        return True
+    return is_infra_deploy_path(path)
+
+
+def infer_scope(paths: list[str]) -> str | None:
+    """Infer a conventional commits scope from file paths.
+
+    Returns a single scope when all non-root files share one top-level
+    directory, otherwise None.
+    """
+    if not paths:
+        return None
+
+    candidates: set[str] = set()
+    for raw in paths:
+        p = _norm(raw).lower()
+        parts = [x for x in p.split("/") if x]
+        if len(parts) < 2:
+            continue
+        first = parts[0]
+        if first in ("apps", "packages", "services") and len(parts) >= 3:
+            candidates.add(parts[1])
+        else:
+            candidates.add(first)
+
+    if len(candidates) == 1:
+        return candidates.pop().replace("_", "-")
+    return None
+
+
 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] = []

{git_explain-2.1.9 → git_explain-2.2.0}/git_explain/run.py

@@ -7,6 +7,32 @@ from pathlib import Path
 _GIT_TEXT = {"encoding": "utf-8", "errors": "replace"}
 
 
+def _lowercase_first(s: str) -> str:
+    """Lowercase the first character unless the first word is an acronym."""
+    if not s:
+        return s
+    first_space = s.find(" ")
+    first_word = s[:first_space] if first_space > 0 else s
+    if first_word == first_word.upper() and len(first_word) > 1:
+        return s
+    return s[0].lower() + s[1:]
+
+
+def format_commit_message(
+    commit_type: str,
+    commit_message: str,
+    *,
+    scope: str | None = None,
+    breaking: bool = False,
+) -> str:
+    """Format a conventional commit subject: type(scope)!: description."""
+    type_str = commit_type.lower()
+    scope_str = f"({scope})" if scope else ""
+    bang = "!" if breaking else ""
+    msg = _lowercase_first(commit_message)
+    return f"{type_str}{scope_str}{bang}: {msg}"
+
+
 def normalize_commit_subject_for_dash_m(message: str | None) -> str:
     """Single line for ``git commit -m``: newlines/tabs become spaces, strip ends.
 
@@ -39,6 +65,9 @@ def apply_commands(
     commit_type: str,
     commit_message: str,
     *,
+    scope: str | None = None,
+    body: str | None = None,
+    breaking: bool = False,
     staged_only: bool = False,
 ) -> None:
     """Stage selected paths and commit. Raises on failure.
@@ -67,9 +96,15 @@ def apply_commands(
             )
         raise RuntimeError("Nothing staged after git add; aborting commit.")
     safe_msg = normalize_commit_subject_for_dash_m(commit_message)
-    full_message = f"[{commit_type}] {safe_msg}"
+    full_message = format_commit_message(
+        commit_type, safe_msg, scope=scope, breaking=breaking
+    )
+    cmd = ["git", "commit", "-m", full_message]
+    if body:
+        safe_body = normalize_commit_subject_for_dash_m(body)
+        cmd.extend(["-m", safe_body])
     subprocess.run(
-        ["git", "commit", "-m", full_message],
+        cmd,
         check=True,
         cwd=root,
         capture_output=True,

{git_explain-2.1.9 → git_explain-2.2.0}/git_explain.egg-info/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: git-explain
-Version: 2.1.9
+Version: 2.2.0
 Summary: CLI that suggests git add/commit from diffs using Gemini
-Author: git-explain contributors
+Author: nazarli-shabnam
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/nazarli-shabnam/git-explain
 Project-URL: Source, https://github.com/nazarli-shabnam/git-explain
@@ -51,6 +51,14 @@ pip install git-explain
 pip install -e .
 ```
 
+**Clone:** install deps (`requirements.txt` is fine), `cd` into the repo, then:
+
+```bash
+python -m git_explain
+```
+
+Run that from the repo root so Python picks up the `git_explain` folder—no `pip install -e .` needed.
+
 Optional: install a specific tag from GitHub instead of PyPI:
 
 ```bash
@@ -70,6 +78,8 @@ pip install "git+https://github.com/nazarli-shabnam/git-explain.git@v2.1.8"
 
 Heuristics guess a sensible type and message from paths and statuses. **No account, no key, no network** for that path.
 
+Suggested commits follow **[Conventional Commits](https://www.conventionalcommits.org/)**—`feat: …`, `fix: …`, optional `(scope)`, and so on—so changelogs and release tools can read them.
+
 ---
 
 ## Optional: Gemini
@@ -80,7 +90,7 @@ If you want sharper messages, set **`GEMINI_API_KEY`** (or `GOOGLE_API_KEY`) in
 |--------|----------------|
 | `git-explain --ai` | AI sees **paths and change type** only (no file contents). |
 | `git-explain --ai --with-diff` | AI also sees the **diff**—better detail; only use if you’re OK sending that to the API. |
-| `git-explain --suggest` | **Staged files only**; prints one **`git commit -m "..."`** line for scripting. Needs AI; don’t combine with other flags. |
+| `git-explain --suggest` | **Staged only**; prints one plain `git commit -m "…"` line (easy to copy). Needs AI; don’t combine with other flags. |
 
 Everything else (`--auto`, `--staged-only`, `--cwd`, model override, shell completion): **`git-explain --help`**.
 

{git_explain-2.1.9 → git_explain-2.2.0}/git_explain.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 git_explain/__init__.py
+git_explain/__main__.py
 git_explain/cli.py
 git_explain/commit_infer.py
 git_explain/gemini.py

{git_explain-2.1.9 → git_explain-2.2.0}/pyproject.toml

@@ -10,7 +10,7 @@ requires-python = ">=3.10"
 dynamic = ["version"]
 license = "MIT"
 authors = [
-  { name = "git-explain contributors" },
+  { name = "nazarli-shabnam" },
 ]
 keywords = ["git", "cli", "commit", "ai", "gemini"]
 classifiers = [

{git_explain-2.1.9 → git_explain-2.2.0}/tests/test_gemini.py

@@ -1,54 +1,76 @@
 from git_explain.gemini import (
-    COMMIT_LINE_CONVENTIONAL_RE,
     COMMIT_LINE_RE,
+    _COMMIT_LINE_BRACKET_RE,
     _fallback_type_and_message_with_context,
     _is_generic_message,
+    _normalize_type,
     truncate_commit_subject,
 )
 
 
-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)
+def test_commit_line_re_matches_conventional_types() -> None:
+    """COMMIT_LINE_RE should match conventional commits: type: subject."""
+    for line, expected_type in [
+        ('git commit -m "feat: add new feature"', "FEAT"),
+        ('git commit -m "fix: correct the bug"', "FIX"),
+        ('git commit -m "docs: update readme"', "DOCS"),
+        ('git commit -m "refactor: simplify logic"', "REFACTOR"),
+        ('git commit -m "test: add unit tests"', "TEST"),
+        ('git commit -m "chore: update deps"', "CHORE"),
+        ('git commit -m "build: update dockerfile"', "BUILD"),
+        ('git commit -m "ci: add github workflow"', "CI"),
+        ('git commit -m "style: fix formatting"', "STYLE"),
+        ('git commit -m "perf: optimize query"', "PERF"),
+    ]:
+        m = COMMIT_LINE_RE.match(line)
+        assert m is not None, f"Expected match for {line}"
+        assert _normalize_type(m.group(1)) == expected_type
 
-    line_test = 'git commit -m "[TEST] Add unit test"'
-    m = COMMIT_LINE_RE.match(line_test)
-    assert m is None
 
+def test_commit_line_re_matches_scope_and_breaking() -> None:
+    """COMMIT_LINE_RE should parse scope and breaking change indicator."""
+    line = 'git commit -m "feat(cli): add new flag"'
+    m = COMMIT_LINE_RE.match(line)
+    assert m is not None
+    assert m.group(1).upper() == "FEAT"
+    assert m.group(2) == "cli"
+    assert m.group(3) == ""
+    assert "add new flag" in m.group(4)
 
-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)
+    line = 'git commit -m "feat(api)!: drop legacy endpoint"'
+    m = COMMIT_LINE_RE.match(line)
     assert m is not None
-    assert m.group(1).lower() == "tests"
+    assert m.group(2) == "api"
+    assert m.group(3) == "!"
 
-    line_test = 'git commit -m "test: add unit test"'
-    m = COMMIT_LINE_CONVENTIONAL_RE.match(line_test)
-    assert m is None
+    line = 'git commit -m "fix!: breaking bugfix"'
+    m = COMMIT_LINE_RE.match(line)
+    assert m is not None
+    assert m.group(2) is None
+    assert m.group(3) == "!"
 
 
-def test_commit_line_re_matches_other_types() -> None:
+def test_bracket_re_matches_legacy_format() -> None:
+    """_COMMIT_LINE_BRACKET_RE should match [TYPE] format as fallback."""
     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"',
+        'git commit -m "[TESTS] Add tests"',
+        'git commit -m "[CHORE] Add Docker config"',
+        'git commit -m "[BUILD] Update dockerfile"',
+        'git commit -m "[CI] Add workflow"',
     ]:
-        m = COMMIT_LINE_RE.match(line)
-        assert m is not None, f"Expected match for {line}"
+        m = _COMMIT_LINE_BRACKET_RE.match(line)
+        assert m is not None, f"Expected bracket 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_normalize_type_converts_tests_to_test() -> None:
+    assert _normalize_type("TESTS") == "TEST"
+    assert _normalize_type("tests") == "TEST"
+    assert _normalize_type("TEST") == "TEST"
+    assert _normalize_type("feat") == "FEAT"
+    assert _normalize_type("unknown") == "CHORE"
 
 
 def test_is_generic_message_flags_vague_add_changes() -> None:
@@ -143,7 +165,7 @@ def test_fallback_prefers_stems_when_folder_is_same() -> None:
     assert "cli" in low or "gemini" in low or "git" in low
 
 
-def test_fallback_many_folders_uses_related_areas_not_plus_more() -> None:
+def test_fallback_many_folders_lists_topics_without_overflow() -> None:
     folders = [f"ui/src/area{i}/File.tsx" for i in range(8)]
     _ctype, msg = _fallback_type_and_message_with_context(
         files=folders,
@@ -151,4 +173,5 @@ def test_fallback_many_folders_uses_related_areas_not_plus_more() -> None:
         has_commits=True,
     )
     assert "(+" not in msg
-    assert "related areas" in msg.lower()
+    assert "related areas" not in msg.lower()
+    assert "area0" in msg.lower() or "area1" in msg.lower()

{git_explain-2.1.9 → git_explain-2.2.0}/tests/test_heuristics.py

@@ -72,8 +72,8 @@ def test_test_only_paths_get_specific_test_message() -> None:
     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'."""
+def test_docker_nginx_env_paths_get_specific_build_message() -> None:
+    """Infra paths should not collapse to 'add changes'."""
     s = suggest_from_changes(
         changes=[
             ("A", "api/app/.env.example"),
@@ -85,7 +85,7 @@ def test_docker_nginx_env_paths_get_specific_chore_message() -> None:
         ],
         has_commits=True,
     )
-    assert s.commit_type == "CHORE"
+    assert s.commit_type == "BUILD"
     m = s.commit_message.lower()
     assert "docker" in m
     assert "nginx" in m

{git_explain-2.1.9 → git_explain-2.2.0}/tests/test_run_apply.py

@@ -44,7 +44,7 @@ def test_apply_commands_newlines_in_message_become_single_subject_line(
     (repo / "a.txt").write_text("x\n", encoding="utf-8")
     apply_commands(repo, ["a.txt"], "FIX", "first line\nsecond line")
     subj = _git(repo, "log", "-1", "--format=%s").stdout.strip()
-    assert subj == "[FIX] first line second line"
+    assert subj == "fix: first line second line"
 
 
 def test_apply_commands_deleted_file(tmp_path) -> None:

git_explain-2.1.9/git_explain/__init__.py

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