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

{git_explain-2.4.0 → git_explain-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-explain
-Version: 2.4.0
+Version: 2.5.0
 Summary: CLI that suggests git add/commit from diffs using Gemini
 Author: nazarli-shabnam
 Author-email: shabnamnezerli@gmail.com
@@ -28,7 +28,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"
+Requires-Dist: ruff==0.12.3; extra == "dev"
 Dynamic: license-file
 
 # git-explain
@@ -37,7 +37,6 @@ Suggests **conventional** `git add` / `git commit` messages from your changes. U
 
 [![PyPI](https://img.shields.io/pypi/v/git-explain.svg?label=pypi)](https://pypi.org/project/git-explain/)
 [![GitHub tag](https://img.shields.io/github/v/tag/nazarli-shabnam/git-explain?label=repo)](https://github.com/nazarli-shabnam/git-explain/tags)
-<!-- GitAds-Verify: 29ITVVWNRUVU524NJ5ZRR6DSZKIHP3EX -->
 
 ---
 
@@ -83,6 +82,7 @@ If `AI_API_KEY` is empty, **`GEMINI_API_KEY`** is still read (same key, older na
 | `--auto` | Apply suggested commands without a confirmation prompt. |
 | `--staged-only` | Work with staged changes only (no `git add` from the tool). |
 | `--cwd` | Use another directory as the git repo root. |
+| `--model` | Override the AI model for this run (defaults to `AI_MODEL` from the repo `.env`). |
 | `--with-diff` | Send the full diff to the AI (more context). |
 | `--suggest` | Print one suggested `git commit -m "…"` line (staged, AI only). |
 
@@ -120,6 +120,3 @@ python -m git_explain
 
 Contributors: `pip install -e ".[dev]"` then `pytest -q`, `ruff check .`, `ruff format --check .`.
 
-## GitAds Sponsored
-[![Sponsored by GitAds](https://gitads.dev/v1/ad-serve?source=nazarli-shabnam/git-explain@github)](https://gitads.dev/v1/ad-track?source=nazarli-shabnam/git-explain@github)
-

{git_explain-2.4.0 → git_explain-2.5.0}/README.md

@@ -4,7 +4,6 @@ Suggests **conventional** `git add` / `git commit` messages from your changes. U
 
 [![PyPI](https://img.shields.io/pypi/v/git-explain.svg?label=pypi)](https://pypi.org/project/git-explain/)
 [![GitHub tag](https://img.shields.io/github/v/tag/nazarli-shabnam/git-explain?label=repo)](https://github.com/nazarli-shabnam/git-explain/tags)
-<!-- GitAds-Verify: 29ITVVWNRUVU524NJ5ZRR6DSZKIHP3EX -->
 
 ---
 
@@ -50,6 +49,7 @@ If `AI_API_KEY` is empty, **`GEMINI_API_KEY`** is still read (same key, older na
 | `--auto` | Apply suggested commands without a confirmation prompt. |
 | `--staged-only` | Work with staged changes only (no `git add` from the tool). |
 | `--cwd` | Use another directory as the git repo root. |
+| `--model` | Override the AI model for this run (defaults to `AI_MODEL` from the repo `.env`). |
 | `--with-diff` | Send the full diff to the AI (more context). |
 | `--suggest` | Print one suggested `git commit -m "…"` line (staged, AI only). |
 
@@ -87,6 +87,3 @@ python -m git_explain
 
 Contributors: `pip install -e ".[dev]"` then `pytest -q`, `ruff check .`, `ruff format --check .`.
 
-## GitAds Sponsored
-[![Sponsored by GitAds](https://gitads.dev/v1/ad-serve?source=nazarli-shabnam/git-explain@github)](https://gitads.dev/v1/ad-track?source=nazarli-shabnam/git-explain@github)
-

git_explain-2.5.0/git_explain/__init__.py

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

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

@@ -8,8 +8,11 @@ from pathlib import Path
 from collections.abc import Callable
 from typing import Iterable
 
+import httpx
+import requests
 import typer
 from dotenv import dotenv_values
+from google.genai import errors as genai_errors
 from rich.console import Console
 from rich.panel import Panel
 from rich.text import Text
@@ -40,6 +43,16 @@ _AI_ENV_KEYS = (
 # Terminal hyperlinks (OSC 8) for first-run setup — Ctrl+click in supported terminals.
 _GOOGLE_AI_API_KEY_URL = "https://aistudio.google.com/apikey"
 
+# Expected failure modes from an AI call: missing key / unparseable response
+# (RuntimeError), Gemini API errors, and network-level failures. Anything else
+# is a real bug and should not be silently treated as "AI unavailable".
+_AI_CALL_ERRORS = (
+    RuntimeError,
+    genai_errors.APIError,
+    httpx.HTTPError,
+    requests.exceptions.RequestException,
+)
+
 
 def _gemini_fallback_notifier(
     group_label: str | None = None,
@@ -578,7 +591,7 @@ def run(
                 if sug is None:
                     raise RuntimeError("Could not parse AI suggestion.")
                 return sug, None
-            except Exception as e:
+            except _AI_CALL_ERRORS as e:
                 h = suggest_from_changes(
                     changes=change_items,
                     has_commits=has_commits,

{git_explain-2.4.0 → git_explain-2.5.0}/git_explain/gemini.py

@@ -11,8 +11,10 @@ from google.genai import types
 
 from git_explain.commit_infer import refine_type_and_message_from_diff
 from git_explain.path_topics import (
+    alnum_key,
     area_scope_suffix,
     basename_fallback_topic,
+    code_topics,
     infer_scope,
     infra_deploy_topics,
     is_test_path,
@@ -184,7 +186,6 @@ _GENERIC_MESSAGES = {
     "misc",
 }
 
-CODE_EXTS = {".py", ".js", ".ts", ".tsx", ".go", ".rs", ".java", ".rb", ".php", ".cs"}
 _WEAK_TOPIC_WORDS = {
     "project",
     "projects",
@@ -210,40 +211,6 @@ _WEAK_TOPIC_WORDS = {
 }
 
 
-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()
     if not msg:
@@ -291,8 +258,8 @@ def _is_generic_message(message: str) -> bool:
         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))
+        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
@@ -379,9 +346,9 @@ def _fallback_type_and_message_with_context(
             topics.append("tests")
     if touches_docs and not docs_only:
         topics.append("docs")
-    code_topics = _code_topics(files)
-    if code_topics:
-        topics.append(", ".join(code_topics[:5]))
+    file_code_topics = code_topics(files)
+    if file_code_topics:
+        topics.append(", ".join(file_code_topics[:5]))
     if touches_packaging:
         topics.append("packaging config")
 
@@ -402,8 +369,8 @@ def _fallback_type_and_message_with_context(
 
     scope = area_scope_suffix(files)
     if scope:
-        scope_key = _alnum_key(scope.replace("for", "", 1))
-        msg_key = _alnum_key(msg)
+        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
 

{git_explain-2.4.0 → git_explain-2.5.0}/git_explain/heuristics.py

@@ -3,7 +3,6 @@
 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 (
@@ -12,8 +11,11 @@ from git_explain.gemini import (
     truncate_commit_subject,
 )
 from git_explain.path_topics import (
+    CODE_EXTS,
+    alnum_key,
     area_scope_suffix,
     basename_fallback_topic,
+    code_topics,
     infer_scope,
     infra_deploy_topics,
     is_build_path,
@@ -36,7 +38,6 @@ 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:
@@ -60,40 +61,6 @@ 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 _path_first_segment(path: str) -> str:
     parts = [x for x in path.replace("\\", "/").strip("/").split("/") if x]
     return parts[0].lower() if parts else "root"
@@ -175,9 +142,9 @@ def suggest_from_changes(
             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) > 4:
+    file_code_topics = code_topics(paths)
+    if file_code_topics:
+        if len(file_code_topics) > 4:
             roots = {_path_first_segment(p) for p in paths}
             if len(roots) == 1:
                 root = next(iter(roots))
@@ -189,9 +156,9 @@ def suggest_from_changes(
                 a, b = sorted(roots)
                 topics.append(f"{len(paths)} files across {a} and {b}")
             else:
-                topics.append(", ".join(code_topics[:4]))
+                topics.append(", ".join(file_code_topics[:4]))
         else:
-            topics.append(", ".join(code_topics[:5]))
+            topics.append(", ".join(file_code_topics[:5]))
 
     # Dedupe while preserving order
     seen: set[str] = set()
@@ -210,8 +177,8 @@ def suggest_from_changes(
 
     scope_suffix = area_scope_suffix(paths)
     if scope_suffix:
-        scope_key = _alnum_key(scope_suffix.replace("for", "", 1))
-        msg_key = _alnum_key(message)
+        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_suffix
 

{git_explain-2.4.0 → git_explain-2.5.0}/git_explain/path_topics.py

@@ -3,12 +3,52 @@
 from __future__ import annotations
 
 import os
+import re
 
 
 def _norm(p: str) -> str:
     return p.replace("\\", "/").strip()
 
 
+CODE_EXTS = {".py", ".js", ".ts", ".tsx", ".go", ".rs", ".java", ".rb", ".php", ".cs"}
+
+
+def alnum_key(s: str) -> str:
+    """Lowercase alnum-only key, for loose substring comparisons of free text."""
+    return re.sub(r"[^a-z0-9]+", "", (s or "").lower())
+
+
+def code_topics(paths: list[str]) -> list[str]:
+    """Ordered, deduplicated topic labels for code files: filename stems or parent folders."""
+    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
+
+
 _TEST_HINTS = ("pytest", "unittest", "tests/", "/tests/")
 
 

{git_explain-2.4.0 → git_explain-2.5.0}/git_explain.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-explain
-Version: 2.4.0
+Version: 2.5.0
 Summary: CLI that suggests git add/commit from diffs using Gemini
 Author: nazarli-shabnam
 Author-email: shabnamnezerli@gmail.com
@@ -28,7 +28,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"
+Requires-Dist: ruff==0.12.3; extra == "dev"
 Dynamic: license-file
 
 # git-explain
@@ -37,7 +37,6 @@ Suggests **conventional** `git add` / `git commit` messages from your changes. U
 
 [![PyPI](https://img.shields.io/pypi/v/git-explain.svg?label=pypi)](https://pypi.org/project/git-explain/)
 [![GitHub tag](https://img.shields.io/github/v/tag/nazarli-shabnam/git-explain?label=repo)](https://github.com/nazarli-shabnam/git-explain/tags)
-<!-- GitAds-Verify: 29ITVVWNRUVU524NJ5ZRR6DSZKIHP3EX -->
 
 ---
 
@@ -83,6 +82,7 @@ If `AI_API_KEY` is empty, **`GEMINI_API_KEY`** is still read (same key, older na
 | `--auto` | Apply suggested commands without a confirmation prompt. |
 | `--staged-only` | Work with staged changes only (no `git add` from the tool). |
 | `--cwd` | Use another directory as the git repo root. |
+| `--model` | Override the AI model for this run (defaults to `AI_MODEL` from the repo `.env`). |
 | `--with-diff` | Send the full diff to the AI (more context). |
 | `--suggest` | Print one suggested `git commit -m "…"` line (staged, AI only). |
 
@@ -120,6 +120,3 @@ python -m git_explain
 
 Contributors: `pip install -e ".[dev]"` then `pytest -q`, `ruff check .`, `ruff format --check .`.
 
-## GitAds Sponsored
-[![Sponsored by GitAds](https://gitads.dev/v1/ad-serve?source=nazarli-shabnam/git-explain@github)](https://gitads.dev/v1/ad-track?source=nazarli-shabnam/git-explain@github)
-

{git_explain-2.4.0 → git_explain-2.5.0}/git_explain.egg-info/SOURCES.txt

@@ -19,5 +19,7 @@ git_explain.egg-info/top_level.txt
 tests/test_cli_utils.py
 tests/test_commit_infer.py
 tests/test_gemini.py
+tests/test_gemini_suggest_commands.py
+tests/test_git.py
 tests/test_heuristics.py
 tests/test_run_apply.py

{git_explain-2.4.0 → git_explain-2.5.0}/git_explain.egg-info/requires.txt

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

{git_explain-2.4.0 → git_explain-2.5.0}/pyproject.toml

@@ -38,7 +38,7 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
     "pytest>=8.0.0",
-    "ruff>=0.8.0",
+    "ruff==0.12.3",
 ]
 
 [project.scripts]

git_explain-2.5.0/tests/test_gemini_suggest_commands.py

@@ -0,0 +1,127 @@
+import pytest
+from google.genai import errors as genai_errors
+
+from git_explain import gemini as gemini_module
+from git_explain.gemini import suggest_commands
+
+
+class _FakeModels:
+    def __init__(self, fn):
+        self._fn = fn
+
+    def generate_content(self, *, model, contents, config):
+        return self._fn(model=model, contents=contents, config=config)
+
+
+class _FakeClient:
+    def __init__(self, fn):
+        self.models = _FakeModels(fn)
+
+
+class _FakeResponse:
+    def __init__(self, text: str) -> None:
+        self.text = text
+
+
+def _patch_client(monkeypatch, fn) -> None:
+    monkeypatch.setattr(gemini_module.genai, "Client", lambda api_key: _FakeClient(fn))
+
+
+_DIFF = "## Meta\nhas_commits: true\n\n## Staged\nM a.txt"
+
+
+def test_suggest_commands_successful_parse(monkeypatch) -> None:
+    monkeypatch.setenv("AI_API_KEY", "test-key")
+    monkeypatch.delenv("AI_MODEL_FALLBACKS", raising=False)
+
+    def fake(*, model, contents, config):
+        return _FakeResponse('git add a.txt\ngit commit -m "fix: correct the bug"')
+
+    _patch_client(monkeypatch, fake)
+
+    sug, raw = suggest_commands(_DIFF, model="gemini-2.5-flash")
+
+    assert sug is not None
+    assert sug.commit_type == "FIX"
+    assert sug.commit_message == "correct the bug"
+    assert sug.add_args == ["a.txt"]
+    assert "correct the bug" in raw
+
+
+def test_suggest_commands_retries_fallback_on_rate_limit(monkeypatch) -> None:
+    monkeypatch.setenv("AI_API_KEY", "test-key")
+    monkeypatch.setenv("AI_MODEL_FALLBACKS", "gemini-2.5-flash-lite")
+
+    calls: list[str] = []
+
+    def fake(*, model, contents, config):
+        calls.append(model)
+        if model == "gemini-2.5-flash":
+            raise genai_errors.ClientError(429, {"error": {"message": "rate"}}, None)
+        return _FakeResponse('git add a.txt\ngit commit -m "fix: correct the bug"')
+
+    _patch_client(monkeypatch, fake)
+
+    notified: list[str] = []
+    sug, _raw = suggest_commands(
+        _DIFF,
+        model="gemini-2.5-flash",
+        fallback_notifier=notified.append,
+    )
+
+    assert calls == ["gemini-2.5-flash", "gemini-2.5-flash-lite"]
+    assert notified == ["gemini-2.5-flash-lite"]
+    assert sug is not None
+    assert sug.commit_type == "FIX"
+
+
+def test_suggest_commands_non_retryable_error_propagates_without_fallback(
+    monkeypatch,
+) -> None:
+    monkeypatch.setenv("AI_API_KEY", "test-key")
+    monkeypatch.setenv("AI_MODEL_FALLBACKS", "gemini-2.5-flash-lite")
+
+    calls: list[str] = []
+
+    def fake(*, model, contents, config):
+        calls.append(model)
+        raise genai_errors.ClientError(400, {"error": {"message": "bad request"}}, None)
+
+    _patch_client(monkeypatch, fake)
+
+    with pytest.raises(genai_errors.ClientError):
+        suggest_commands(_DIFF, model="gemini-2.5-flash")
+
+    assert calls == ["gemini-2.5-flash"]
+
+
+def test_suggest_commands_generic_ai_message_falls_back_to_heuristic_message(
+    monkeypatch,
+) -> None:
+    monkeypatch.setenv("AI_API_KEY", "test-key")
+    monkeypatch.delenv("AI_MODEL_FALLBACKS", raising=False)
+
+    def fake(*, model, contents, config):
+        return _FakeResponse('git add a.txt\ngit commit -m "chore: update"')
+
+    _patch_client(monkeypatch, fake)
+
+    sug, _raw = suggest_commands(_DIFF, model="gemini-2.5-flash")
+
+    assert sug is not None
+    assert sug.commit_message != "update"
+
+
+def test_suggest_commands_missing_api_key_raises(monkeypatch) -> None:
+    monkeypatch.delenv("AI_API_KEY", raising=False)
+    monkeypatch.delenv("GEMINI_API_KEY", raising=False)
+
+    with pytest.raises(RuntimeError):
+        suggest_commands(_DIFF, model="gemini-2.5-flash")
+
+
+def test_suggest_commands_empty_diff_returns_none(monkeypatch) -> None:
+    monkeypatch.setenv("AI_API_KEY", "test-key")
+    sug, raw = suggest_commands("   ", model="gemini-2.5-flash")
+    assert sug is None
+    assert raw == ""

git_explain-2.5.0/tests/test_git.py

@@ -0,0 +1,209 @@
+import subprocess
+
+import pytest
+
+from git_explain.git import (
+    ensure_git_repo,
+    get_combined_diff,
+    get_diff_for_paths,
+    get_repo_root,
+    get_staged_changes,
+    get_staged_diff_for_paths,
+    get_untracked_changes,
+    get_unstaged_changes,
+    repo_has_commits,
+)
+
+
+def _git(cwd, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _init_repo(repo) -> None:
+    repo.mkdir()
+    _git(repo, "init")
+    _git(repo, "config", "user.email", "test@example.com")
+    _git(repo, "config", "user.name", "Test User")
+    # Emit UTF-8 paths as-is instead of octal-escaped/quoted (git's default
+    # for non-ASCII paths), matching the UTF-8 assumption in git_explain.git.
+    _git(repo, "config", "core.quotepath", "false")
+
+
+def test_get_repo_root_raises_outside_a_repo(tmp_path) -> None:
+    outside = tmp_path / "not_a_repo"
+    outside.mkdir()
+    with pytest.raises(RuntimeError):
+        get_repo_root(outside)
+
+
+def test_ensure_git_repo_raises_outside_a_repo(tmp_path) -> None:
+    outside = tmp_path / "not_a_repo"
+    outside.mkdir()
+    with pytest.raises(RuntimeError):
+        ensure_git_repo(outside)
+
+
+def test_get_repo_root_and_ensure_git_repo_return_root(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    assert get_repo_root(repo).resolve() == repo.resolve()
+    assert ensure_git_repo(repo).resolve() == repo.resolve()
+
+
+def test_repo_has_commits_before_and_after_first_commit(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    assert repo_has_commits(repo) is False
+
+    (repo / "a.txt").write_text("hello\n", encoding="utf-8")
+    _git(repo, "add", "a.txt")
+    _git(repo, "commit", "-m", "init")
+    assert repo_has_commits(repo) is True
+
+
+def test_get_staged_changes(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    (repo / "a.txt").write_text("hello\n", encoding="utf-8")
+    _git(repo, "add", "a.txt")
+    assert get_staged_changes(repo) == [("A", "a.txt")]
+
+
+def test_get_unstaged_changes(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    (repo / "a.txt").write_text("hello\n", encoding="utf-8")
+    _git(repo, "add", "a.txt")
+    _git(repo, "commit", "-m", "init")
+
+    (repo / "a.txt").write_text("hello world\n", encoding="utf-8")
+    assert get_unstaged_changes(repo) == [("M", "a.txt")]
+
+
+def test_get_untracked_changes(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    (repo / "new.txt").write_text("new\n", encoding="utf-8")
+    assert get_untracked_changes(repo) == [("A", "new.txt")]
+
+
+def test_rename_is_normalized_to_single_r_status(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    (repo / "old.txt").write_text("same content\n", encoding="utf-8")
+    _git(repo, "add", "old.txt")
+    _git(repo, "commit", "-m", "init")
+
+    _git(repo, "mv", "old.txt", "new.txt")
+    staged = get_staged_changes(repo)
+    assert staged == [("R", "new.txt")]
+
+
+def test_copy_without_detection_flags_shows_as_two_adds(tmp_path) -> None:
+    # get_staged_changes() calls `git diff --name-status` without -C, so git
+    # never detects copies (unlike renames, copy detection needs an explicit
+    # flag) — both the original and the copy show up as separate adds.
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    (repo / "old.txt").write_text("x\n" * 20, encoding="utf-8")
+    _git(repo, "add", "old.txt")
+    _git(repo, "commit", "-m", "init")
+
+    (repo / "copy.txt").write_text((repo / "old.txt").read_text(encoding="utf-8"))
+    _git(repo, "add", "copy.txt")
+    assert get_staged_changes(repo) == [("A", "copy.txt")]
+
+
+def test_non_ascii_path_round_trips(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    fname = "café.txt"
+    (repo / fname).write_text("hello\n", encoding="utf-8")
+    assert get_untracked_changes(repo) == [("A", fname)]
+
+
+def test_get_combined_diff_sections(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    (repo / "tracked.txt").write_text("hello\n", encoding="utf-8")
+    _git(repo, "add", "tracked.txt")
+    _git(repo, "commit", "-m", "init")
+
+    (repo / "tracked.txt").write_text("hello world\n", encoding="utf-8")
+    (repo / "staged.txt").write_text("staged\n", encoding="utf-8")
+    _git(repo, "add", "staged.txt")
+    (repo / "untracked.txt").write_text("new\n", encoding="utf-8")
+
+    combined, root = get_combined_diff(repo)
+    assert root.resolve() == repo.resolve()
+    assert "## Meta\nhas_commits: true" in combined
+    assert "## Staged\nA staged.txt" in combined
+    assert "## Unstaged\nM tracked.txt" in combined
+    assert "## Untracked\nA untracked.txt" in combined
+
+
+def test_get_combined_diff_empty_repo_has_no_commits(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    combined, _root = get_combined_diff(repo)
+    assert "has_commits: false" in combined
+
+
+def test_get_diff_for_paths_includes_untracked_file_content(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    (repo / "new.txt").write_text("brand new content\n", encoding="utf-8")
+
+    diff = get_diff_for_paths(["new.txt"], repo)
+    assert "Untracked (new file): new.txt" in diff
+    assert "brand new content" in diff
+
+
+def test_get_diff_for_paths_includes_staged_and_unstaged_sections(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    (repo / "a.txt").write_text("line1\n", encoding="utf-8")
+    _git(repo, "add", "a.txt")
+    _git(repo, "commit", "-m", "init")
+
+    (repo / "a.txt").write_text("line1\nline2\n", encoding="utf-8")
+    _git(repo, "add", "a.txt")
+    (repo / "a.txt").write_text("line1\nline2\nline3\n", encoding="utf-8")
+
+    diff = get_diff_for_paths(["a.txt"], repo)
+    assert "## Staged diff" in diff
+    assert "## Unstaged diff" in diff
+
+
+def test_get_diff_for_paths_empty_paths_returns_empty_string(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    assert get_diff_for_paths([], repo) == ""
+
+
+def test_get_staged_diff_for_paths(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    (repo / "a.txt").write_text("line1\n", encoding="utf-8")
+    _git(repo, "add", "a.txt")
+    _git(repo, "commit", "-m", "init")
+
+    (repo / "a.txt").write_text("line1\nline2\n", encoding="utf-8")
+    _git(repo, "add", "a.txt")
+    (repo / "a.txt").write_text("line1\nline2\nline3\n", encoding="utf-8")
+
+    staged_diff = get_staged_diff_for_paths(["a.txt"], repo)
+    assert "+line2" in staged_diff
+    assert "line3" not in staged_diff
+
+
+def test_get_staged_diff_for_paths_empty_paths_returns_empty_string(tmp_path) -> None:
+    repo = tmp_path / "repo"
+    _init_repo(repo)
+    assert get_staged_diff_for_paths([], repo) == ""

git_explain-2.4.0/git_explain/__init__.py

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