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:

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

For editable development mode:

pip install -e .

To install with additional provider SDKs and testing dependencies:

# 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:

pip install comit-cli

With optional provider extras:

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

git ai --version

2. Configure Your Provider & API Key

Open the interactive settings menu:

git ai settings

Or configure via CLI:

# 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:

git add <files>

Run Comit:

git ai commit

---

Configuration & Settings

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

Interactive Settings Menu

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:

  git ai settings show
  

• Set AI provider:

  git ai settings set-provider gemini
  

• Set API key (masked prompt):

  git ai settings set-key
  git ai settings set-key --provider openai
  

• Set model:

  git ai settings set-model qwen/qwen3.8-27b
  git ai settings set-model gpt-4o --provider openai
  

• Set Ollama host URL:

  git ai settings set-host http://localhost:11434
  

• Reset user configuration:

  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:

git add <files>

Then run:

git ai commit

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

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:

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:

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:

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:

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:

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

git ai commit

After accepting the commit, Comit asks:

Commit created successfully.

  feat: add JWT refresh token support

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

Choosing N leaves the commit local:

Commit created locally. Nothing was pushed.

2. Automatic push after commit

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

git ai commit -y

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

4. Fast mode with automatic push

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:

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:

pytest

Run tests with verbose output:

pytest -v

Building and Verifying Distributions

Build the source distribution and wheel:

python -m build

Validate package metadata with twine:

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):

   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.