commitmate 1.0.0__py3-none-any.whl

commitmate/cli.py

@@ -0,0 +1,129 @@
+from commitmate.git_utils import get_staged_diff, get_staged_files, git_commit
+from commitmate.message_gen import build_prompt, clean_response, parse_model_response, assemble_commit_message
+from commitmate.ollama_client import generate_commit_message
+from commitmate.exceptions import CommitMateError, InvalidModelResponseError
+from rich.console import Console
+from rich.prompt import Prompt
+from rich.markup import escape
+import os
+import tempfile
+import subprocess
+import shlex
+import argparse
+
+MAX_ATTEMPTS = 3
+DEFAULT_MODEL = "llama3"
+
+def edit_in_editor(initial_text: str) -> str:
+    """
+    Opens the user's $EDITOR with initial_text pre-filled in a temp file,
+    waits for them to edit and close it, then returns the saved content.
+    Falls back to nano (Mac/Linux) or notepad (Windows) if $EDITOR isn't set.
+    """
+    editor_cmd = os.environ.get("EDITOR", "notepad" if os.name == "nt" else "nano")
+
+    with tempfile.NamedTemporaryFile(suffix=".txt", mode="w", delete=False) as tf:
+        tf.write(initial_text)
+        temp_path = tf.name
+
+    try:
+        subprocess.run(shlex.split(editor_cmd) + [temp_path])
+        with open(temp_path, "r") as tf:
+            edited = tf.read()
+    finally:
+        os.remove(temp_path)
+
+
+    return edited.strip()
+
+
+
+def generate_valid_commit_message(prompt: str, console: Console, model: str) -> dict:
+    """
+    Calls Ollama and validates the response, retrying up to MAX_ATTEMPTS times
+    if the model returns something that fails validation.
+    """
+    last_error = None
+    for attempt in range(1, MAX_ATTEMPTS + 1):
+        with console.status(f"[bold cyan]Generating commit message with {model} (attempt {attempt}/{MAX_ATTEMPTS})..."):
+            raw = generate_commit_message(prompt, model)
+        try:
+            cleaned = clean_response(raw)
+            parsed = parse_model_response(cleaned)
+            return parsed
+        except InvalidModelResponseError as e:
+            last_error = e
+            continue
+    raise last_error
+
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        prog="commitmate",
+        description="Generate a Conventional Commits-style message from staged git changes using a local Ollama model."
+    )
+    parser.add_argument(
+        "--model",
+        default=DEFAULT_MODEL,
+        help=f"Ollama model to use (default: {DEFAULT_MODEL}). Example: qwen2.5-coder:7b"
+    )
+    return parser.parse_args()
+
+
+
+def main():
+    console = Console()
+    args = parse_args()
+
+    try:
+        codes_changed = get_staged_diff()
+        files_changed = get_staged_files()
+        prompt = build_prompt(codes_changed, files_changed)
+        parsed = generate_valid_commit_message(prompt, console, model=args.model)
+        commit_message = assemble_commit_message(parsed)
+
+    except InvalidModelResponseError:
+        console.print(
+            "[bold red]Error:[/bold red] The model couldn't produce a well-formatted "
+            "commit message after several attempts."
+        )
+        console.print(
+            "[yellow]Tip: this often happens with diffs spanning many unrelated files. "
+            "Try staging fewer files at a time.[/yellow]"
+        )
+        return
+    except CommitMateError as e:
+        console.print(f"[bold red]Error:[/bold red] {escape(str(e))}")
+        return
+
+    while True:
+        console.print("\n[bold]Generated commit message:[/bold]")
+
+        console.print(f"[cyan]{escape(commit_message)}[/cyan]")
+
+        choice = Prompt.ask(
+            "Select an action",
+            choices=["accept", "edit", "cancel"],
+            default="accept"
+        )
+
+        if choice == "accept":
+            try:
+                git_commit(commit_message)
+                console.print("[bold green]Committed.[/bold green]")
+            except CommitMateError as e:
+                console.print(f"[bold red]Commit failed:[/bold red] {escape(str(e))}")
+            return
+
+        elif choice == "cancel":
+            console.print("[bold red]Cancelled. No commit made.[/bold red]")
+            return
+
+        elif choice == "edit":
+            console.print("[dim]Opening editor — save and close the file/tab when you're done.[/dim]")
+            commit_message = edit_in_editor(commit_message)
+
+
+if __name__ == "__main__":
+    main()

commitmate/exceptions.py

@@ -0,0 +1,47 @@
+class CommitMateError(Exception):
+    """Base exception for all CommitMate-specific errors."""
+    pass
+
+
+class NotAGitRepositoryError(CommitMateError):
+    """Raised when the current directory is not inside a git repository."""
+    def __init__(self, message="This command must be run inside a valid Git repository."):
+        super().__init__(message)
+
+
+class NoStagedChangesError(CommitMateError):
+    """Raised when there are no staged changes to generate a commit message from."""
+    def __init__(self, message="No staged changes found. Stage your changes with 'git add' first."):
+        super().__init__(message)
+
+
+class GitCommandError(CommitMateError):
+    """Raised when a git command fails for a reason other than 'not a repo'.
+    No default message — the caller must supply the actual git stderr output,
+    since the failure reason varies every time."""
+    def __init__(self, message):
+        super().__init__(message)
+
+
+class GitNotInstalledError(CommitMateError):
+    """Raised when the git executable can't be found on PATH."""
+    def __init__(self, message="Git is not installed or not found on PATH."):
+        super().__init__(message)
+
+
+
+# Ollama Errors
+class OllamaConnectionError(CommitMateError):
+    """ Raised when the Ollama is not running at all"""
+    def __init__(self, message="Ollama is not running"):
+        super().__init__(message)
+
+class OllamaTimeoutError(CommitMateError):
+    """ Raised when the Ollama connection timed out"""
+    def __init__(self, message="Connection timed out, Ollama taking too long to respond"):
+        super().__init__(message)
+
+class InvalidModelResponseError(CommitMateError):
+    """Raised when the model's response isn't valid JSON or is missing required fields."""
+    def __init__(self, message):
+        super().__init__(message)

commitmate/git_utils.py

@@ -0,0 +1,90 @@
+import subprocess
+from commitmate.exceptions import (
+    GitNotInstalledError, 
+    NotAGitRepositoryError, 
+    GitCommandError,
+    NoStagedChangesError
+)
+
+
+def _ensure_in_git_repo():
+    """
+    Uses `git rev-parse --is-inside-work-tree` to reliably check whether the
+    current directory is inside a git repository. This is more robust than
+    parsing `git diff`'s error text, which can vary across git versions.
+    """
+    try:
+        subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+    except subprocess.CalledProcessError as e:
+        raise NotAGitRepositoryError() from e
+    except FileNotFoundError as e:
+        raise GitNotInstalledError() from e
+
+
+
+def get_staged_diff():
+    """
+    Runs `git diff --staged` and returns the diff as a string.
+    Raises NoStagedChangesError if there's nothing staged.
+    """
+    _ensure_in_git_repo()
+    try:
+        result = subprocess.run(
+            ['git', 'diff', '--staged'],
+            capture_output=True, 
+            text=True,
+            check=True
+        )
+    except subprocess.CalledProcessError as e:
+        if "not a git repository" in e.stderr.strip().casefold():
+            raise NotAGitRepositoryError() from e
+        else:
+            raise GitCommandError(e.stderr.strip()) from e
+    except FileNotFoundError as e:
+        raise GitNotInstalledError() from e
+    
+    if not result.stdout.strip():
+        raise NoStagedChangesError()
+    
+    return result.stdout
+    
+
+def get_staged_files():
+    """
+      Runs `git diff --staged --name-only` and returns a list of changed file paths.
+    """
+    _ensure_in_git_repo()
+    try:
+        result = subprocess.run(
+            ['git', 'diff', '--staged', '--name-only'], 
+            capture_output=True,
+            text=True,
+            check=True
+        )
+    except subprocess.CalledProcessError as e:
+        if "not a git repository" in e.stderr.strip().casefold():
+            raise NotAGitRepositoryError() from e
+        else:
+            raise GitCommandError(e.stderr.strip()) from e
+    except FileNotFoundError as e:
+        raise GitNotInstalledError() from e
+    
+    return result.stdout.strip().splitlines()
+    
+
+def git_commit(message: str):
+    """Runs 'git commit -m ...' with the approved message."""
+    try:
+        subprocess.run(
+            ["git", "commit", "-m", message],
+            capture_output=True,
+            text= True,
+            check=True
+        )
+    except subprocess.CalledProcessError as e:
+        raise GitCommandError(e.stderr.strip()) from e

commitmate/message_gen.py

@@ -0,0 +1,136 @@
+import json
+from commitmate.exceptions import InvalidModelResponseError
+
+
+COMMIT_TYPES = ["feat", "fix", "docs", "refactor", "test", "chore", "style", "perf"]
+
+
+def build_prompt(diff: str, files: list[str]) -> str:
+    """Constructs the full prompt sent to Ollama for commit message generation."""
+
+    file_list = "\n".join(f"- {f}" for f in files)
+    types_list = ", ".join(COMMIT_TYPES)
+
+    return f"""You are an expert software engineer writing a Conventional Git Commit message.
+
+Your task is to analyze the staged changes below and output a single JSON object.
+
+CRITICAL RULES:
+1. Output ONLY valid JSON. Do not include markdown code blocks (```), introductory text, or explanations.
+2. "reasoning": briefly note, in one short sentence, what the key change is across all files. This is scratch space to help you think before answering, keep it under 15 words.
+3. "type": must be exactly one of {types_list}.
+4. "scope": a short noun for the changed module. Leave empty ("") if broad.
+5. "description": MUST be a short, descriptive phrase starting with an imperative verb (e.g., "add support for user login", NOT just a single word like "add" or "update").
+6. "description": MUST NOT have trailing punctuation (no periods or semicolons at the end). MUST be 5-9 words long, this is a hard limit, not a suggestion.
+7. "body": 1-3 short bullet points explaining WHY the change was made, or an empty string ("").
+
+Respond with ONLY the JSON object, with keys in this exact order: reasoning, type, scope, description, body. No markdown fences, no explanation, no text outside the JSON.
+
+[EXAMPLES]
+Input changes: Added support for fetching from tavily and startup search.
+Output:
+{{
+  "reasoning": "added tavily search integration and startup-specific query support",
+  "type": "feat",
+  "scope": "web_search",
+  "description": "add tavily search and startup query support",
+  "body": "- integrate tavily API for expanded data sources\\n- enable targeted startup queries"
+}}
+
+Input changes: fixed the api timeout crash
+Output:
+{{
+  "reasoning": "client was crashing on slow api responses due to no timeout handling",
+  "type": "fix",
+  "scope": "api",
+  "description": "resolve timeout crash in client module",
+  "body": ""
+}}
+[END OF EXAMPLES]
+Before writing your answer, briefly consider each changed file listed above individually.
+CHANGED FILES:
+{file_list}
+
+--- DIFF ---
+{diff}
+--- END DIFF ---
+""".strip()
+
+def clean_response(raw: str) -> str:
+    """
+    Strips markdown code fences that Ollama sometimes adds even with format=json.
+    """
+    text = raw.strip()
+    lines = text.splitlines()
+
+    if lines and lines[0].strip().startswith("```"):
+        lines = lines[1:]
+    if lines and lines[-1].strip().startswith("```"):
+        lines = lines[:-1]
+
+    return "\n".join(lines).strip()
+
+def parse_model_response(cleaned: str) -> dict:
+    """
+    Parses the cleaned JSON string into a dict and validates required fields.
+    Raises InvalidModelResponseError if parsing fails, fields are missing,
+    or fields are the wrong type.
+    """
+    try:
+        data = json.loads(cleaned)
+    except json.JSONDecodeError as e:
+        raise InvalidModelResponseError(f"Model did not return valid JSON: {e}") from e
+
+    if not isinstance(data, dict):
+        raise InvalidModelResponseError(f"Model response must be a JSON object, got {type(data).__name__}")
+
+    if "type" not in data or "description" not in data:
+        raise InvalidModelResponseError(
+            f"Model response missing required fields 'type' or 'description': {data}"
+        )
+
+    if data["type"] not in COMMIT_TYPES:
+        raise InvalidModelResponseError(
+            f"Model returned invalid commit type '{data['type']}'. Expected one of {COMMIT_TYPES}."
+        )
+
+    if not isinstance(data["description"], str):
+        raise InvalidModelResponseError(
+            f"'description' must be a string, got {type(data['description']).__name__}"
+        )
+
+    if len(data["description"].split()) < 3:
+        raise InvalidModelResponseError(
+            f"Description too short (must be at least 3 words): '{data['description']}'"
+        )
+
+    if "scope" in data and not isinstance(data["scope"], str):
+        raise InvalidModelResponseError(
+            f"'scope' must be a string, got {type(data['scope']).__name__}"
+        )
+
+    if isinstance(data.get("body"), list):
+        data["body"] = "\n".join(str(item) for item in data["body"])
+    elif "body" in data and not isinstance(data["body"], str):
+        raise InvalidModelResponseError(
+            f"'body' must be a string or list, got {type(data['body']).__name__}"
+        )
+
+    return data
+
+
+def assemble_commit_message(data: dict) -> str:
+    """
+    Builds the final 'type(scope): description' string (plus optional body)
+    from the parsed JSON dict. Pure string formatting, no LLM involved.
+    """
+    commit_type = data["type"]
+    scope = data.get("scope", "").strip()
+    description = data["description"].strip()
+    body = data.get("body", "").strip()
+
+    header = f"{commit_type}({scope}): {description}" if scope else f"{commit_type}: {description}"
+
+    if body:
+        return f"{header}\n\n{body}"
+    return header

commitmate/ollama_client.py

@@ -0,0 +1,31 @@
+import requests
+from commitmate.exceptions import (
+    OllamaConnectionError,
+    OllamaTimeoutError
+)
+
+
+def generate_commit_message(prompt: str, model: str = "llama3", timeout: int = 30, num_ctx: int = 8192) -> str:
+
+    url = "http://localhost:11434/api/generate"
+
+    payload = {
+        "model": model,
+        "prompt": prompt,
+        "format" : "json",
+        "stream": False,
+        "options": {
+            "num_ctx": num_ctx
+        }
+    }
+
+    try:
+        response = requests.post(url, json = payload, timeout=timeout)
+        response.raise_for_status()
+
+        data = response.json()
+        return data["response"]
+    except requests.exceptions.Timeout as e:
+        raise OllamaTimeoutError() from e
+    except requests.exceptions.ConnectionError as e:
+        raise OllamaConnectionError() from e

commitmate-1.0.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: commitmate
+Version: 1.0.0
+Summary: Generates Conventional Commits-style messages from staged git diffs using a local Ollama model.
+Project-URL: Homepage, https://github.com/theishanpathak/commitmate
+Author: Ishan Pathak
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: requests
+Requires-Dist: rich
+Description-Content-Type: text/markdown
+
+# CommitMate
+
+A command-line tool that reads your staged git changes and generates a [Conventional Commits](https://www.conventionalcommits.org/)-style commit message using a local LLM via [Ollama](https://ollama.com/) — no cloud API, no API keys, nothing leaves your machine.
+
+You review the generated message and choose to accept it, edit it, or cancel — CommitMate never commits anything without your explicit approval.
+
+## Why
+
+Writing good commit messages consistently is tedious, and generic "wip" or "fix stuff" commits make a project's history much less useful. CommitMate looks at what you've actually staged and proposes a properly formatted message you can accept as-is or tweak, without sending your code to any external service.
+
+## Prerequisites
+
+- Python 3.11 or later
+- [Ollama](https://ollama.com/) installed and running locally
+- A model pulled in Ollama. The tool defaults to `llama3`:
+  ```bash
+  ollama pull llama3
+  ```
+  `qwen2.5-coder:7b` is also recommended and performed better in testing on multi-file diffs (see Known Limitations below). If you want to use it, pull it too and pass `--model qwen2.5-coder:7b`:
+  ```bash
+  ollama pull qwen2.5-coder:7b
+  ```
+- Ollama's server running (usually automatic after install, or start manually):
+  ```bash
+  ollama serve
+  ```
+
+## Installation
+
+Clone the repo and install it as an editable local package:
+
+```bash
+git clone https://github.com/theishanpathak/commitmate.git
+cd commitmate
+pip install -e .
+```
+
+This registers a `commitmate` command on your system, callable from any git repository.
+
+## Usage
+
+1. Stage some changes:
+   ```bash
+   git add <files>
+   ```
+   Tip: for best results, stage related changes together rather than many unrelated files at once. Smaller local models can struggle to summarize a diff spanning several unrelated files into a single, well-formatted commit message.
+2. Run:
+   ```bash
+   commitmate
+   ```
+3. CommitMate will show a generated commit message and prompt you to choose:
+   - **accept** — commits immediately with the generated message
+   - **edit** — opens the message in your `$EDITOR` (falls back to `nano` on Mac/Linux, `notepad` on Windows) so you can revise it before committing
+   - **cancel** — exits without committing; your staged changes are left untouched
+
+## How It Works
+
+- **`git_utils.py`** — the only module that shells out to git (via `subprocess`). Retrieves the staged diff and file list, and performs the actual commit.
+- **`ollama_client.py`** — a thin HTTP wrapper around Ollama's local `/api/generate` endpoint. Knows nothing about commit messages or git; it just sends a prompt and returns whatever text comes back.
+- **`message_gen.py`** — pure, I/O-free logic. Builds the prompt (asking the model to return structured JSON rather than free text), and parses/validates/assembles that JSON into the final `type(scope): description` message.
+- **`exceptions.py`** — a small hierarchy of custom exceptions (e.g. `NotAGitRepositoryError`, `NoStagedChangesError`, `OllamaConnectionError`, `InvalidModelResponseError`) so failures are caught and reported cleanly instead of surfacing as raw stack traces.
+- **`cli.py`** — the composition root. Orchestrates the pipeline above, retries generation a few times if the model's response fails validation, and drives the accept/edit/cancel loop using [`rich`](https://github.com/Textualize/rich) for terminal output.
+
+The model is prompted to return a JSON object (`reasoning`, `type`, `scope`, `description`, `body`) rather than a fully formatted commit message string. The actual `type(scope): description` text is then assembled in plain Python. This was a deliberate pivot after an earlier version — which asked the model to return the final formatted string directly — proved unreliable: local models frequently added preambles, markdown fences, or trailing explanations despite explicit instructions not to. Constraining the model to fill in a small number of discrete fields, and letting Python own the final formatting, removed that failure mode almost entirely.
+
+A `reasoning` field is requested first in the JSON schema, before the other fields. Since JSON keys are generated in order, this gives the model a place to briefly "think" about the change before committing to a `type`/`description`, without breaking strict JSON output. This measurably improved how often the description stayed within a reasonable length.
+
+If the model's response fails validation (wrong type, description too short, malformed JSON, etc.) after a few attempts, CommitMate shows a friendly message suggesting the diff may be too large or span too many unrelated files, rather than surfacing the raw internal validation error.
+
+## Known Limitations
+
+- **Multi-file diffs can produce longer subject lines.** Smaller/general-purpose local models (tested: `llama3`, the default) sometimes struggle to keep the commit description under the ~72-character convention when a diff spans multiple unrelated files. In testing, `qwen2.5-coder:7b` performed noticeably better at staying within length limits on the same diffs. Consider passing `--model qwen2.5-coder:7b` if you run into this.
+- **No diff truncation.** Very large staged diffs are sent to the model in full, with no length guard. This could hit context limits or slow down generation on large changes.
+- **Self-referential prompt confusion.** If a staged diff itself contains text that looks like prompt instructions (for example, testing CommitMate on a diff to its own `message_gen.py`, which contains the prompt-building code), the model can occasionally get confused about what's an instruction versus what's data to summarize.
+- **GUI editors need a `--wait`-style flag.** The `edit` flow waits for your editor process to exit before continuing. Terminal editors (`nano`, `vim`) work out of the box. GUI editors need an explicit wait flag, e.g.:
+  ```bash
+  export EDITOR="code --wait"
+  ```
+  Without it, editors like VS Code return immediately and CommitMate will read the file back before you've finished editing.
+- **No automated test suite yet.** The pure functions in `message_gen.py` (especially `clean_response` and `parse_model_response`) are strong candidates for unit tests; this hasn't been added yet.
+
+## Configuration
+
+- **`$EDITOR`** — controls which editor opens during the `edit` flow. Defaults to `nano` (Mac/Linux) or `notepad` (Windows) if unset.
+- **`--model`** — choose which Ollama model to use. Defaults to `llama3`:
+  ```bash
+  commitmate --model qwen2.5-coder:7b
+  ```
+  See Known Limitations above for why `qwen2.5-coder:7b` may give better results on multi-file diffs.
+
+## Requirements
+
+- `requests`
+- `rich`
+
+(See `requirements.txt`.)
+
+## Author
+
+Ishan Pathak
+[theishanpathak.com](https://theishanpathak.com)

commitmate-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+commitmate/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+commitmate/cli.py,sha256=3TWeJn65hJNQr8nKVf5ZSfKFYd5E06mcxerb5uumvvk,4275
+commitmate/exceptions.py,sha256=UhUiEewAZ65tc2Djm9UfxIIQ2JXV7ArT0rkNih763I8,1807
+commitmate/git_utils.py,sha256=g7JV2UPfrz2T6nEHRn10oaRAbB7UHtvrzWxe0oPH12w,2645
+commitmate/message_gen.py,sha256=ahysigKOhfXFYW4WPbFSL3YZpCA63gt_AFCLukKoE7E,5188
+commitmate/ollama_client.py,sha256=yt1rGXNANA9XpkA2Fd9T0tyZRDLLkG1YrfFE0JmDs3U,820
+commitmate-1.0.0.dist-info/METADATA,sha256=KBi3-8HaxKf7xsaHVuRrbFM7E2rlRnC4UugT3RZTE9s,7172
+commitmate-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+commitmate-1.0.0.dist-info/entry_points.txt,sha256=6YQ6ml1hqruxutoSfnAy6JdxwKsYdnapOyoFxtcnEuk,51
+commitmate-1.0.0.dist-info/RECORD,,

commitmate-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

commitmate-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+commitmate = commitmate.cli:main