Metadata-Version: 2.4
Name: comit-cli
Version: 1.0.0
Summary: An AI-powered Git commit assistant that understands your repository's commit style
Author: Comit Team
License-Expression: MIT
Keywords: git,commit,ai,cli,groq,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: groq>=0.9.0
Requires-Dist: prompt-toolkit>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Provides-Extra: tests
Requires-Dist: pytest>=7.0.0; extra == "tests"
Provides-Extra: gemini
Requires-Dist: google-genai>=0.1.0; extra == "gemini"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: ollama
Requires-Dist: ollama>=0.3.0; extra == "ollama"
Provides-Extra: all
Requires-Dist: groq>=0.9.0; extra == "all"
Requires-Dist: google-genai>=0.1.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: ollama>=0.3.0; extra == "all"

# Comit

> AI-powered Git commit messages that understand your project's commit style.

Comit is a lightweight developer CLI for Git. It analyzes your staged changes and recent commit history, learns your repository's commit conventions, and generates concise, accurate commit messages using your choice of AI provider.

## Features

- **Multi-Provider Support** — Use Groq, Google Gemini, OpenAI, or local models with Ollama.
- **Context-aware** — Analyzes your staged diff and recent commit history to match your repository's style.
- **Commit message validation** — Deterministically validates generated commit messages against staged files to catch mismatches before committing.
- **Developer in control** — Review, edit, regenerate, or cancel a suggested commit message before committing.
- **Push Integration** — Optional safe remote pushing after creating a commit.
- **Fast-track mode** — Use `-y` to automatically commit the generated message without confirmation.
- **Settings management** — Configure your provider, model, API keys, and endpoints interactively or via CLI commands.
- **Safe and non-destructive** — Only analyzes staged changes with `git diff --cached`. Comit never stages files or modifies unstaged changes.

## Supported Providers

| Provider | Default Model | Authentication | Setup / Env Variable |
| :--- | :--- | :--- | :--- |
| **Groq** *(Default)* | `qwen/qwen3.8-27b` | API Key | `GROQ_API_KEY` |
| **Google Gemini** | `gemini-2.5-flash` | API Key | `GEMINI_API_KEY` |
| **OpenAI** | `gpt-4o-mini` | API Key | `OPENAI_API_KEY` |
| **Ollama** | `llama3.2` | None (Local) | `OLLAMA_HOST` (default: `http://localhost:11434`) |

## Installation

### Requirements

- Python 3.11+
- Git

### Installing from Source (Current Development)

Clone the repository and install Comit into your environment:

```bash
git clone https://github.com/blackin4k/comit.git
cd comit
pip install .
```

For editable development mode:

```bash
pip install -e .
```

To install with additional provider SDKs and testing dependencies:

```bash
# Google Gemini SDK
pip install -e ".[gemini]"

# OpenAI SDK
pip install -e ".[openai]"

# Ollama SDK
pip install -e ".[ollama]"

# All providers and testing tools
pip install -e ".[all,test]"
```

### Installing from PyPI (After Release)

Once published to PyPI, Comit can be installed directly:

```bash
pip install comit-cli
```

With optional provider extras:

```bash
pip install "comit-cli[all]"
```

Note: The PyPI package distribution name is `comit-cli`, while the Python import package remains `comit`, providing both the `comit` and `git ai` CLI entry points.

### Windows PATH Note

When installing Python packages with CLI scripts, pip places executables (like `git-ai.exe`) into your Python Scripts directory.

Make sure your Python Scripts directory is on your system or user `PATH` so Git discovers the `git ai` extension from any terminal session.

Common Python Scripts locations on Windows:
- System Python: `C:\Users\<Username>\AppData\Local\Programs\Python\Python313\Scripts`
- Virtual Environment: `<venv_path>\Scripts`

## Quick Start

### 1. Verify Installation

```powershell
git ai --version
```

### 2. Configure Your Provider & API Key

Open the interactive settings menu:

```powershell
git ai settings
```

Or configure via CLI:

```powershell
# Select provider (groq, gemini, openai, ollama)
git ai settings set-provider groq

# Set API key for the active provider
git ai settings set-key

# Or specify the provider directly
git ai settings set-key --provider gemini
```

### 3. Generate Commit Messages

Stage your files:

```bash
git add <files>
```

Run Comit:

```bash
git ai commit
```

---

## Configuration & Settings

Comit provides an interactive configuration interface as well as non-interactive subcommands.

### Interactive Settings Menu

```powershell
git ai settings
```

Options:
1. View configuration
2. Select AI provider
3. Configure API key / host
4. Configure model
5. Reset configuration
6. Exit

### Settings Commands

- **View configuration:**
  ```powershell
  git ai settings show
  ```

- **Set AI provider:**
  ```powershell
  git ai settings set-provider gemini
  ```

- **Set API key (masked prompt):**
  ```powershell
  git ai settings set-key
  git ai settings set-key --provider openai
  ```

- **Set model:**
  ```powershell
  git ai settings set-model qwen/qwen3.8-27b
  git ai settings set-model gpt-4o --provider openai
  ```

- **Set Ollama host URL:**
  ```powershell
  git ai settings set-host http://localhost:11434
  ```

- **Reset user configuration:**
  ```powershell
  git ai settings reset
  ```

### Configuration Precedence

Comit resolves settings in the following order:

1. **Environment variables**:
   - Provider: `COMIT_PROVIDER`
   - Model: `COMIT_MODEL`, `GROQ_MODEL`, `GEMINI_MODEL`, `OPENAI_MODEL`, `OLLAMA_MODEL`
   - API Keys / Endpoints: `GROQ_API_KEY`, `GEMINI_API_KEY`, `OPENAI_API_KEY`, `OLLAMA_HOST`
2. **User configuration** (`config.json` stored in `%APPDATA%\comit` on Windows or `~/.config/comit` on Linux/macOS)
3. **Application defaults** (Provider: `groq`, Model: `qwen/qwen3.8-27b`)

---

## Usage

### Interactive Mode

First, stage your changes:

```bash
git add <files>
```

Then run:

```bash
git ai commit
```

Comit performs a deterministic safety review of your staged changes, generates a commit suggestion, and validates the message against staged files:

```text
No issues detected.

Generated:

  feat: add JWT refresh token support

> Accept
  Edit
  Regenerate
  Cancel
```

Navigate with **Up/Down arrow keys** or **k/j**, and press **Enter** to select.

If safety issues or sensitive files are detected during review, Comit displays the findings and requests confirmation before proceeding to AI generation:

```text
Review findings:

WARNING
Sensitive environment or credential file staged
.env

Continue to commit? [y/N]
```

Choosing `No` stops the commit flow safely without calling the AI or modifying files.

### Actions

- **Accept (`a` or `1`)** — Creates the commit using the generated message. After the local commit succeeds, you are asked whether to push to the remote (`[y/N]`, default No).
- **Edit (`e` or `2`)** — Opens an interactive inline editor with the generated message pre-populated. Press **Enter** to save your changes, or **Esc** / **Ctrl+C** to cancel and keep the original generated message.
- **Regenerate (`r` or `3`)** — Requests an alternative commit message from the AI provider while avoiding previous attempts.
- **Cancel (`c`, `q`, or `4`)** — Exits cleanly without creating a commit or modifying staged changes.

---

### Commit Message Validation

Before you accept a generated commit message, Comit deterministically validates the message against your staged changes:
- **Syntax and structure** — Checks Conventional Commit format (`feat`, `fix`, `docs`, `refactor`, `test`, etc.), scopes, and breaking-change notation.
- **Context matching** — Detects high-confidence mismatches, such as claiming a feature when only documentation or test files are staged, or referencing files absent from staged changes.

If a mismatch is detected, Comit displays a warning:

```text
Generated:

  feat: add authentication endpoints

Validation warning:

  Commit message type 'feat' does not match documentation-only staged changes.
  All 1 staged file(s) are documentation files.

> Accept
  Edit
  Regenerate
  Cancel
```

You remain in full control to:
- **Accept anyway** if the generated message accurately reflects your intent.
- **Edit** the message directly.
- **Regenerate** a new message from the AI provider.
- **Cancel** without creating a commit.

> **Note:** Commit validation is a deterministic consistency check to catch obvious mismatches before committing. It does not guarantee semantic correctness or full intent understanding of arbitrary code.

---

### Change Review & Safety Analysis

Analyze staged changes for potential security and configuration issues before committing:

```bash
git ai review
```

Comit performs deterministic, local analysis on your staged changes to detect common problematic files and accidental additions:
- **Sensitive files** — `.env`, `.env.*`, `credentials.json`, `secrets.yaml`, private keys (ignoring `.env.example` templates).
- **Hardcoded secrets** — AWS keys, OpenAI/Groq/Google API keys, GitHub tokens, and literal credential assignments in added lines.
- **Private keys** — PEM format RSA, EC, DSA, and OpenSSH private keys.
- **Database files** — Binary databases (`.db`, `.sqlite`, `.sqlite3`, `.rdb`).
- **Large files** — Staged files exceeding 5 MB.
- **Generated artifacts** — `__pycache__`, `.pyc`, `dist/`, `build/`, `node_modules/`, test caches.
- **Git internal files** — `.git-credentials`, `.gitconfig`, or staged internal `.git/` files.

Example output:

```text
Review findings:

HIGH
Possible hardcoded secret or API key detected
src/config.py
  Detected pattern: Groq API Key (gsk...xyz)

WARNING
Sensitive environment or credential file staged
.env
```

If no issues are found:

```text
No issues detected.
```

> **Note:** `git ai review` is a deterministic helper to assist developers before committing; it is not a full security scanner and does not guarantee security. It does not modify files, stage/unstage files, or create commits.

---

### Pushing Commits

Pushing is strictly opt-in and safe.

#### 1. Interactive commit with push confirmation

```bash
git ai commit
```

After accepting the commit, Comit asks:

```text
Commit created successfully.

  feat: add JWT refresh token support

Push this commit to the remote? [y/N]
```

Choosing `N` leaves the commit local:

```text
Commit created locally. Nothing was pushed.
```

#### 2. Automatic push after commit

```bash
git ai commit --push
```

Reviews the commit message interactively, and pushes automatically to `origin/<branch>` upon acceptance without a secondary prompt.

#### 3. Fast mode without push

```bash
git ai commit -y
```

Automatically accepts the generated commit message. Does **not** push to the remote.

#### 4. Fast mode with automatic push

```bash
git ai commit -y --push
```

Automatically accepts the generated message, creates the commit, and pushes to `origin/<branch>`.

---

## Safety Guarantees

Comit only reads staged changes:

```bash
git diff --cached
```

Comit does NOT:
- Automatically run `git add`
- Modify unstaged files
- Modify working tree files
- Create a commit without approval (unless `-y` is explicitly passed)
- Push to a remote without explicit confirmation or `--push`
- Force push (`git push --force` is never executed)
- Write API keys or credentials into repository files

If no changes are staged, Comit exits without calling the AI provider.
If no Git remote is configured, Comit reports that no remote exists and leaves your commit local.

---

## Testing & Quality Assurance

### Running Tests

Run the complete test suite:

```bash
pytest
```

Run tests with verbose output:

```bash
pytest -v
```

### Building and Verifying Distributions

Build the source distribution and wheel:

```bash
python -m build
```

Validate package metadata with twine:

```bash
twine check --strict dist/*
```

---

## Continuous Integration & Release

### Continuous Integration (CI)

The GitHub Actions CI workflow runs automatically on all pushes and pull requests to `main`. It:
- Tests on both `ubuntu-latest` and `windows-latest`.
- Validates against supported Python versions (3.11, 3.12, 3.13).
- Runs the complete automated test suite.
- Builds source distributions (`.tar.gz`) and binary wheels (`.whl`).
- Validates distribution metadata with `twine check --strict`.

### Release Process & PyPI Publishing

Releases use PyPI Trusted Publishing via OpenID Connect (OIDC). No long-lived API tokens or credentials are stored in repository secrets.

#### Release Workflow

1. Update the version in `pyproject.toml` and `src/comit/__init__.py`.
2. Push a version tag matching `v*` (for example, `v0.2.0`):
   ```bash
   git tag v0.2.0
   git push origin v0.2.0
   ```
3. The release workflow automatically:
   - Builds the wheel and source distribution.
   - Validates package metadata.
   - Publishes verified artifacts to PyPI via OIDC.

#### PyPI Trusted Publisher Configuration

To configure PyPI Trusted Publishing for this repository:
1. Navigate to your PyPI account settings and go to **Publishing**.
2. Add a new **GitHub Publisher**:
   - **PyPI Project Name**: `comit-cli`
   - **Owner**: `blackin4k`
   - **Repository Name**: `comit`
   - **Workflow name**: `release.yml`
   - **Environment name**: `pypi`
3. In GitHub repository settings, create the `pypi` environment under **Settings > Environments**.

---

## License

MIT License.
