git-commit-message 0.4.0__py3-none-any.whl

git_commit_message/__init__.py

@@ -0,0 +1,10 @@
+"""Public package exporting the CLI and internal utilities.
+
+This module exposes only public symbols in accordance with the codestyle guide.
+"""
+
+from ._cli import main
+
+__all__ = (
+    "main",
+)

git_commit_message/__main__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from ._cli import main
+
+
+if __name__ == "__main__":
+    main()

git_commit_message/_cli.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+"""Command-line interface entry point.
+
+Collect staged changes from the repository and call an OpenAI GPT model
+to generate a commit message, or create a commit straight away.
+"""
+
+from argparse import ArgumentParser, Namespace
+from pathlib import Path
+import sys
+from typing import Final
+
+from ._git import commit_with_message, get_repo_root, get_staged_diff, has_staged_changes
+from ._gpt import (
+    generate_commit_message,
+    generate_commit_message_with_info,
+    CommitMessageResult,
+)
+
+
+def _build_parser() -> ArgumentParser:
+    """Create the CLI argument parser.
+
+    Returns
+    -------
+    ArgumentParser
+        A configured argument parser.
+    """
+
+    parser: ArgumentParser = ArgumentParser(
+        prog="git-commit-message",
+        description=(
+            "Generate a commit message with OpenAI GPT based on the staged changes."
+        ),
+    )
+
+    parser.add_argument(
+        "description",
+        nargs="?",
+        help="Optional auxiliary description of the changes.",
+    )
+
+    parser.add_argument(
+        "--commit",
+        action="store_true",
+        help="Commit immediately with the generated message.",
+    )
+
+    parser.add_argument(
+        "--edit",
+        action="store_true",
+        help="Open an editor to amend the message before committing. Use with '--commit'.",
+    )
+
+    parser.add_argument(
+        "--model",
+        default=None,
+        help=(
+            "OpenAI model name to use. If unspecified, uses the environment variables (GIT_COMMIT_MESSAGE_MODEL, OPENAI_MODEL) or 'gpt-5-mini'."
+        ),
+    )
+
+    parser.add_argument(
+        "--language",
+        dest="language",
+        default=None,
+        help=(
+            "Target language/locale IETF tag for the output (default: en-GB). "
+            "You may also set GIT_COMMIT_MESSAGE_LANGUAGE or OPENAI_LANGUAGE."
+        ),
+    )
+
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Print the request/response and token usage.",
+    )
+
+    parser.add_argument(
+        "--one-line",
+        dest="one_line",
+        action="store_true",
+        help="Use only a single-line subject.",
+    )
+
+    parser.add_argument(
+        "--max-length",
+        dest="max_length",
+        type=int,
+        default=None,
+        help="Maximum subject (first line) length (default: 72).",
+    )
+
+    return parser
+
+
+def _run(
+    *,
+    args: Namespace,
+) -> int:
+    """Main execution logic.
+
+    Parameters
+    ----------
+    args
+        Parsed CLI arguments.
+
+    Returns
+    -------
+    int
+        Process exit code. 0 indicates success; any other value indicates failure.
+    """
+
+    repo_root: Path = get_repo_root()
+
+    if not has_staged_changes(cwd=repo_root):
+        print("No staged changes. Run 'git add' and try again.", file=sys.stderr)
+        return 2
+
+    diff_text: str = get_staged_diff(cwd=repo_root)
+
+    hint: str | None = args.description if isinstance(args.description, str) else None
+
+    result: CommitMessageResult | None = None
+    try:
+        if args.debug:
+            result = generate_commit_message_with_info(
+                diff=diff_text,
+                hint=hint,
+                model=args.model,
+                single_line=getattr(args, "one_line", False),
+                subject_max=getattr(args, "max_length", None),
+                language=getattr(args, "language", None),
+            )
+            message = result.message
+        else:
+            message = generate_commit_message(
+                diff=diff_text,
+                hint=hint,
+                model=args.model,
+                single_line=getattr(args, "one_line", False),
+                subject_max=getattr(args, "max_length", None),
+                language=getattr(args, "language", None),
+            )
+    except Exception as exc:  # noqa: BLE001 - to preserve standard output messaging
+        print(f"Failed to generate commit message: {exc}", file=sys.stderr)
+        return 3
+
+    # Option: force single-line message
+    if getattr(args, "one_line", False):
+        # Use the first non-empty line only
+        for line in (ln.strip() for ln in message.splitlines()):
+            if line:
+                message = line
+                break
+        else:
+            message = ""
+
+    if not args.commit:
+        if args.debug and result is not None:
+            # Print debug information
+            print("==== OpenAI Usage ====")
+            print(f"model: {result.model}")
+            print(f"response_id: {getattr(result, 'response_id', '(n/a)')}")
+            if result.total_tokens is not None:
+                print(
+                    f"tokens: prompt={result.prompt_tokens} completion={result.completion_tokens} total={result.total_tokens}"
+                )
+            else:
+                print("tokens: (provider did not return usage)")
+            print("\n==== Prompt ====")
+            print(result.prompt)
+            print("\n==== Response ====")
+            print(result.response_text)
+            print("\n==== Commit Message ====")
+            print(message)
+        else:
+            print(message)
+        return 0
+
+    if args.debug and result is not None:
+        # Also print debug info before commit
+        print("==== OpenAI Usage ====")
+        print(f"model: {result.model}")
+        print(f"response_id: {getattr(result, 'response_id', '(n/a)')}")
+        if result.total_tokens is not None:
+            print(
+                f"tokens: prompt={result.prompt_tokens} completion={result.completion_tokens} total={result.total_tokens}"
+            )
+        else:
+            print("tokens: (provider did not return usage)")
+        print("\n==== Prompt ====")
+        print(result.prompt)
+        print("\n==== Response ====")
+        print(result.response_text)
+        print("\n==== Commit Message ====")
+        print(message)
+
+    if args.edit:
+        rc: int = commit_with_message(message=message, edit=True, cwd=repo_root)
+    else:
+        rc = commit_with_message(message=message, edit=False, cwd=repo_root)
+
+    return rc
+
+
+def main() -> None:
+    """Script entry point.
+
+    Parse command-line arguments, delegate to the execution logic, and exit with its code.
+    """
+
+    parser: Final[ArgumentParser] = _build_parser()
+    args: Namespace = parser.parse_args()
+
+    if args.edit and not args.commit:
+        print("'--edit' must be used together with '--commit'.", file=sys.stderr)
+        sys.exit(2)
+
+    code: int = _run(args=args)
+    sys.exit(code)

git_commit_message/_git.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+"""Git-related helper functions.
+
+Provides repository root discovery, extraction of staged changes, and
+creating commits from a message.
+"""
+
+from pathlib import Path
+import subprocess
+
+
+def get_repo_root(
+    *,
+    cwd: Path | None = None,
+) -> Path:
+    """Find the repository root from the current working directory.
+
+    Parameters
+    ----------
+    cwd
+        Starting directory for the search. Defaults to the current working directory.
+
+    Returns
+    -------
+    Path
+        The repository root path.
+    """
+
+    start: Path = cwd or Path.cwd()
+    try:
+        out: bytes = subprocess.check_output(
+            [
+                "git",
+                "rev-parse",
+                "--show-toplevel",
+            ],
+            cwd=str(start),
+        )
+    except subprocess.CalledProcessError as exc:  # noqa: TRY003
+        raise RuntimeError("Not a Git repository.") from exc
+
+    root = Path(out.decode().strip())
+    return root
+
+
+def has_staged_changes(
+    *,
+    cwd: Path,
+) -> bool:
+    """Check whether there are staged changes."""
+
+    try:
+        subprocess.check_call(
+            ["git", "diff", "--cached", "--quiet", "--exit-code"],
+            cwd=str(cwd),
+        )
+        return False
+    except subprocess.CalledProcessError:
+        return True
+
+
+def get_staged_diff(
+    *,
+    cwd: Path,
+) -> str:
+    """Return the staged changes as diff text."""
+
+    out: bytes = subprocess.check_output(
+        [
+            "git",
+            "diff",
+            "--cached",
+            "--patch",
+            "--minimal",
+            "--no-color",
+        ],
+        cwd=str(cwd),
+    )
+    return out.decode()
+
+
+def commit_with_message(
+    *,
+    message: str,
+    edit: bool,
+    cwd: Path,
+) -> int:
+    """Create a commit with the given message.
+
+    Parameters
+    ----------
+    message
+        Commit message.
+    edit
+        If True, use the `--edit` flag to open an editor for amendments.
+    cwd
+        Git working directory.
+
+    Returns
+    -------
+    int
+        The subprocess exit code.
+    """
+
+    cmd: list[str] = ["git", "commit", "-m", message]
+    if edit:
+        cmd.append("--edit")
+
+    try:
+        completed = subprocess.run(cmd, cwd=str(cwd), check=False)
+        return int(completed.returncode)
+    except OSError as exc:  # e.g., editor launch failure, etc.
+        raise RuntimeError(f"Failed to run 'git commit': {exc}") from exc

git_commit_message/_gpt.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+"""Generate Git commit messages by calling an OpenAI GPT model."""
+
+import os
+from typing import Final, Any, cast
+from openai import OpenAI
+
+
+_DEFAULT_MODEL: Final[str] = "gpt-5-mini"
+_DEFAULT_LANGUAGE: Final[str] = "en-GB"
+
+def _build_system_prompt(
+    *,
+    single_line: bool,
+    subject_max: int | None,
+    language: str,
+) -> str:
+    max_len = subject_max or 72
+    if single_line:
+        return (
+            f"You are an expert Git commit message generator. "
+            f"Always use '{language}' spelling and style. "
+            f"Return a single-line imperative subject only (<= {max_len} chars). "
+            f"Do not include a body, bullet points, or any rationale. Do not include any line breaks. "
+            f"Consider the user-provided auxiliary context if present. "
+            f"Return only the commit message text (no code fences or prefixes like 'Commit message:')."
+        )
+    return (
+        f"You are an expert Git commit message generator. "
+        f"Always use '{language}' spelling and style. "
+        f"The subject line is mandatory: you MUST start the output with the subject as the very first non-empty line, "
+        f"in imperative mood, and keep it <= {max_len} chars. Insert exactly one blank line after the subject. "
+        f"Never start with bullets, headings, labels, or any other text. Then include a body in this format.\n\n"
+        f"Example format (do not include the --- lines in the output):\n\n"
+        f"---\n\n"
+        f"<Subject line>\n\n"
+        f"- <detail 1>\n"
+        f"- <detail 2>\n"
+        f"- <detail N>\n\n"
+        f"<Rationale label translated into the target language>: <1-2 concise sentences explaining the intent and why>\n\n"
+        f"---\n\n"
+        f"Guidelines:\n"
+        f"- The first non-empty line MUST be the subject line; include exactly one blank line after it.\n"
+        f"- Never place bullets, headings, or labels before the subject line.\n"
+        f"- Use '-' bullets; keep each bullet short (<= 1 line).\n"
+        f"- Prefer imperative mood verbs (Add, Fix, Update, Remove, Refactor, Document, etc.).\n"
+        f"- Focus on what changed and why; avoid copying diff hunks verbatim.\n"
+        f"- The only allowed label is the equivalent of 'Rationale:' translated into the target language; do not add other headings or prefaces.\n"
+        f"- Do not include the '---' delimiter lines, code fences, or any surrounding labels like 'Commit message:'.\n"
+        f"- Do not copy or reuse any example text verbatim; produce original content based on the provided diff and context.\n"
+        f"- If few details are necessary, include at least one bullet summarising the key change.\n"
+        f"- If you cannot provide any body content, still output the subject line; the subject line must never be omitted.\n"
+        f"- Consider the user-provided auxiliary context if present.\n"
+        f"Return only the commit message text in the above format (no code fences or extra labels)."
+    )
+
+
+def _system_message(
+    *,
+    single_line: bool,
+    subject_max: int | None,
+    language: str,
+) -> dict[str, str]:
+    """Create the system message dictionary."""
+    return {"role": "system", "content": _build_system_prompt(single_line=single_line, subject_max=subject_max, language=language)}
+
+
+class CommitMessageResult:
+    """Hold the generated commit message and debugging information.
+
+    Notes
+    -----
+    Treat all fields as read-only by convention.
+    """
+
+    __slots__ = (
+        "message",
+        "model",
+        "prompt",
+        "response_text",
+        "response_id",
+        "prompt_tokens",
+        "completion_tokens",
+        "total_tokens",
+    )
+
+    def __init__(
+        self,
+        /,
+        *,
+        message: str,
+        model: str,
+        prompt: str,
+        response_text: str,
+        response_id: str | None,
+        prompt_tokens: int | None,
+        completion_tokens: int | None,
+        total_tokens: int | None,
+    ) -> None:
+        self.message = message
+        self.model = model
+        self.prompt = prompt
+        self.response_text = response_text
+        self.response_id = response_id
+        self.prompt_tokens = prompt_tokens
+        self.completion_tokens = completion_tokens
+        self.total_tokens = total_tokens
+
+
+def _resolve_model(
+    *,
+    model: str | None,
+) -> str:
+    """Resolve the model name."""
+
+    return (
+        model
+        or os.environ.get("GIT_COMMIT_MESSAGE_MODEL")
+        or os.environ.get("OPENAI_MODEL")
+        or _DEFAULT_MODEL
+    )
+
+
+def _resolve_language(
+    *,
+    language: str | None,
+) -> str:
+    """Resolve the target language/locale tag used for output style."""
+
+    return (
+        language
+        or os.environ.get("GIT_COMMIT_MESSAGE_LANGUAGE")
+        or os.environ.get("OPENAI_LANGUAGE")
+        or _DEFAULT_LANGUAGE
+    )
+
+
+def _build_user_messages(
+    *,
+    diff: str,
+    hint: str | None,
+) -> tuple[str, list[dict[str, str]]]:
+    """Compose user messages, separating auxiliary context and diff.
+
+    Returns
+    -------
+    tuple[str, list[dict[str, str]]]
+        The first element is the combined string for debugging output; the
+        second is the list of user messages to send to the Chat Completions API.
+    """
+
+    hint_content: str | None = (
+        f"# Auxiliary context (user-provided)\n{hint}" if hint else None
+    )
+    diff_content: str = f"# Changes (diff)\n{diff}"
+
+    messages: list[dict[str, str]] = []
+    if hint_content:
+        messages.append({"role": "user", "content": hint_content})
+    messages.append({"role": "user", "content": diff_content})
+
+    combined_prompt: str = "\n\n".join(
+        [part for part in (hint_content, diff_content) if part is not None]
+    )
+    return combined_prompt, messages
+
+
+def generate_commit_message(
+    *,
+    diff: str,
+    hint: str | None,
+    model: str | None,
+    single_line: bool = False,
+    subject_max: int | None = None,
+    language: str | None = None,
+) -> str:
+    """Generate a commit message using an OpenAI GPT model."""
+
+    chosen_model: str = _resolve_model(model=model)
+    chosen_language: str = _resolve_language(language=language)
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        raise RuntimeError("The OPENAI_API_KEY environment variable is required.")
+
+    client = OpenAI(api_key=api_key)
+
+    _combined_prompt, user_messages = _build_user_messages(diff=diff, hint=hint)
+
+    # Use Chat Completions API to generate a single response (send hint and diff as separate user messages)
+    all_messages: list[dict[str, str]] = [
+        _system_message(single_line=single_line, subject_max=subject_max, language=chosen_language),
+        *user_messages,
+    ]
+
+    resp = client.chat.completions.create(
+        model=chosen_model,
+        messages=cast(Any, all_messages),
+    )
+
+    text: str = (resp.choices[0].message.content or "").strip()
+    if not text:
+        raise RuntimeError("An empty commit message was generated.")
+    return text
+
+
+def generate_commit_message_with_info(
+    *,
+    diff: str,
+    hint: str | None,
+    model: str | None,
+    single_line: bool = False,
+    subject_max: int | None = None,
+    language: str | None = None,
+) -> CommitMessageResult:
+    """Return the OpenAI GPT call result together with debugging information.
+
+    Returns
+    -------
+    CommitMessageResult
+        The generated message, token usage, and prompt/response text.
+    """
+
+    chosen_model: str = _resolve_model(model=model)
+    chosen_language: str = _resolve_language(language=language)
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        raise RuntimeError("The OPENAI_API_KEY environment variable is required.")
+
+    client = OpenAI(api_key=api_key)
+    combined_prompt, user_messages = _build_user_messages(diff=diff, hint=hint)
+
+    all_messages = [
+        _system_message(single_line=single_line, subject_max=subject_max, language=chosen_language),
+        *user_messages,
+    ]
+
+    resp = client.chat.completions.create(
+        model=chosen_model,
+        messages=cast(Any, all_messages),
+    )
+
+    response_text: str = (resp.choices[0].message.content or "").strip()
+    if not response_text:
+        raise RuntimeError("An empty commit message was generated.")
+
+    response_id: str | None = getattr(resp, "id", None)
+    usage = getattr(resp, "usage", None)
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    total_tokens: int | None = None
+    if usage is not None:
+        prompt_tokens = getattr(usage, "prompt_tokens", None)
+        completion_tokens = getattr(usage, "completion_tokens", None)
+        total_tokens = getattr(usage, "total_tokens", None)
+
+    return CommitMessageResult(
+        message=response_text,
+        model=chosen_model,
+        prompt=combined_prompt,
+        response_text=response_text,
+        response_id=response_id,
+        prompt_tokens=prompt_tokens,
+        completion_tokens=completion_tokens,
+        total_tokens=total_tokens,
+    )

git_commit_message-0.4.0.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: git-commit-message
+Version: 0.4.0
+Summary: Generate Git commit messages from staged changes using OpenAI GPT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: openai>=2.6.1
+
+# git-commit-message
+
+Staged changes -> GPT commit message generator.
+
+## Install (editable)
+
+```fish
+python -m pip install -e .
+```
+
+## Usage
+
+- Print commit message only:
+
+```fish
+git add -A
+git-commit-message "optional extra context about the change"
+```
+
+- Force single-line subject only:
+
+```fish
+git-commit-message --one-line "optional context"
+```
+
+- Limit subject length (default 72):
+
+```fish
+git-commit-message --one-line --max-length 50 "optional context"
+```
+
+- Commit immediately with editor:
+
+```fish
+git-commit-message --commit --edit "refactor parser for speed"
+```
+
+- Select output language/locale (default: en-GB):
+
+```fish
+# American English
+git-commit-message --language en-US "optional context"
+
+# Korean
+git-commit-message --language ko-KR
+
+# Japanese
+git-commit-message --language ja-JP
+```
+
+Notes:
+
+- The model is instructed to write using the selected language/locale.
+- In multi-line mode, the only allowed label ("Rationale:") is also translated into the target language.
+
+Environment:
+
+- `OPENAI_API_KEY`: required
+- `GIT_COMMIT_MESSAGE_MODEL` or `OPENAI_MODEL`: optional (default: `gpt-5-mini`)
+- `GIT_COMMIT_MESSAGE_LANGUAGE` or `OPENAI_LANGUAGE`: optional (default: `en-GB`)
+
+## AI‑generated code notice
+
+Parts of this project were created with assistance from AI tools (e.g. large language models).
+All AI‑assisted contributions were reviewed and adapted by maintainers before inclusion.
+If you need provenance for specific changes, please refer to the Git history and commit messages.

git_commit_message-0.4.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+git_commit_message/__init__.py,sha256=cJvTj8-8_I1VYz3EO7Eq1LJZ6RS-WhNSAhjVVliVLtU,196
+git_commit_message/__main__.py,sha256=n5lvkLiCZ1Q4dwhEwonWntcKTeTaJL9qOJzdiLf0Gfk,99
+git_commit_message/_cli.py,sha256=N1ZF3hPTnIO-K6vh-VgT9JnqTOeWP-Xp2xZJ6Rz1Nig,6510
+git_commit_message/_git.py,sha256=-FNXmFtlsbuArgCvEcCqpXSB7CjwdLdhoXgdZk1qtcE,2435
+git_commit_message/_gpt.py,sha256=etsE_IcxR-atZKPzJqOl30wlOxtcRGTK6tTLm28L-U8,9040
+git_commit_message-0.4.0.dist-info/METADATA,sha256=VHuXMRfyiGJNqsRSjgJTZ4onUh7CKXPQIqHJWiyMpSw,1753
+git_commit_message-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+git_commit_message-0.4.0.dist-info/entry_points.txt,sha256=e2cRvoyZnmP7yVItmFKwZofYG86WWKhm8KbzZSo2mf0,63
+git_commit_message-0.4.0.dist-info/top_level.txt,sha256=qeP45y7y44R4KrPEihvMdwdM8tXYDY_3nCvCD3I9EcI,19
+git_commit_message-0.4.0.dist-info/RECORD,,

git_commit_message-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

git_commit_message-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+git-commit-message = git_commit_message:main

git_commit_message-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+git_commit_message