Metadata-Version: 2.4
Name: commitgen-ai
Version: 0.2.0
Summary: AI-powered git commit message generator with local and cloud support
Author-email: Sourav Tripathy <lipuntripathy74@gmail.com>
License: MIT
Project-URL: Homepage, https://souravtripathy.com
Project-URL: Documentation, https://github.com/Sourav-Tripathy/commitgen#readme
Project-URL: Repository, https://github.com/Sourav-Tripathy/commitgen
Project-URL: Issues, https://github.com/Sourav-Tripathy/commitgen/issues
Keywords: git,commit,ai,ollama,openrouter,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: ollama>=0.1.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: toml>=0.10.0
Requires-Dist: tiktoken>=0.5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

<div align="center">
  <img src="assets/image.png" alt="CommitGen Banner" width="100%" />

  [![PyPI version](https://badge.fury.io/py/commitgen-ai.svg)](https://badge.fury.io/py/commitgen-ai)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://pypi.org/project/commitgen-ai/)
  [![Ollama](https://img.shields.io/badge/AI-Ollama-white?logo=ollama)](https://ollama.ai)
  [![Gemini](https://img.shields.io/badge/AI-Gemini-blue?logo=googlegemini)](https://deepmind.google/technologies/gemini/)
  [![OpenRouter](https://img.shields.io/badge/AI-OpenRouter-7434eb)](https://openrouter.ai)
</div>

**CommitGen** is a CLI tool that automatically generates conventional git commit messages for your staged changes. It analyzes your `git diff`, summarizes the changes, and uses local LLMs (via Ollama) or cloud providers (Gemini, OpenRouter) to write clean, descriptive commit messages.

## Features

- **LLM-Powered**: Uses advanced LLMs to understand your code changes.
- **Local First**: First-class support for [Ollama](https://ollama.ai) models (Llama 3, DeepSeek, Qwen, Phi-3, etc.).
- **Google Gemini Native**: Built-in support for Gemini models (like `gemini-1.5-flash`) for lightning-fast and free cloud generations.
- **OpenRouter Cloud Option**: Supports **OpenRouter** for accessing top-tier models and dynamic auto-free routing (`openrouter/free`).
- **Git Hook Integration**: Automatically populate commit messages when you run `git commit` using the `prepare-commit-msg` hook.
- **Robust Amend Support**: Modify or refine your previous commit message based on new staged diffs, or improve the last message directly by diffing the last commit itself.
- **Smart Chunking**: Group and segment large files by git hunks (`@@`) rather than whole files to fit within small local model context windows.
- **Configurable**: Easy-to-use CLI config manager with project-specific overrides.

## Installation

### Prerequisites

- Python 3.8+
- Git
- [Ollama](https://ollama.ai) (optional, for local models)

### Install from PyPI

```bash
pip install commitgen-ai
```

### Install from Source

```bash
git clone https://github.com/souravtripathy/commitgen.git
cd commitgen
pip install -e .
```

## Quick Start

1. **Initialize Configuration**:
   Run the interactive setup wizard to choose your provider, configure keys, and select models.

   ```bash
   commitgen init
   ```

   - **Ollama**: Automatically detects running local models or guides you to download `llama3.2:1b`.
   - **Gemini**: Setup your Google Gemini API Key (or use the `GEMINI_API_KEY` env variable).
   - **OpenRouter**: Paste your OpenRouter API Key (or use `OPENROUTER_API_KEY` env). Features an interactive setup to choose dynamic auto-free routing or browse popular models.

2. **Stage Your Changes**:
   
   ```bash
   git add .
   ```

3. **Generate a Commit**:

   ```bash
   commitgen commit
   ```

   Review the generated message, edit it on the fly, or confirm to commit!

4. **Install Git Hook (Optional)**:
   Integrate commitgen natively into your git workflow. Every time you run `git commit`, the message will automatically be prepopulated in your text editor.

   ```bash
   commitgen install-hook
   ```

## Configuration

Manage your settings easily with the `config` command.

### View Configuration

```bash
commitgen config
# Or get specific value
commitgen config --get ollama.model
```

### Change Defaults

```bash
# Switch to a different Ollama model
commitgen config --set ollama.model=deepseek-r1:1.5b

# Switch to Gemini provider
commitgen config --set general.provider=gemini

# Set OpenRouter model
commitgen config --set openrouter.model=openrouter/free
```

### Project-Specific Guidelines & Overrides

You can share commit style guidelines with your entire team by checking in a `.commitgen.toml` or `commitgen.toml` file at the root of your git repository. CommitGen automatically merges these settings on top of the user's global config.

Example `.commitgen.toml`:

```toml
[general]
conventional_commits = true
max_length = 72
custom_instructions = "Prefix each commit message with JIRA-XYZ: or LINEAR-[ID]: (replace XYZ or ID with the active ticket identifier)."
```

### Reset Configuration

If you want to restore default settings:

```bash
commitgen config --reset
```

## Usage Tips

- **Auto-Commit**: Skip confirmation with `--auto` flag.
  ```bash
  commitgen commit --auto
  ```

- **Amending Last Commit**: Improve or append to the last commit message:
  ```bash
  commitgen commit --amend
  ```
  If staged changes are present, it merges them into the context. If no staged changes are present, it pulls the diff of the last commit to rewrite/refine the message.

- **Dynamic Changelog Generation**: Auto-compile git history into release-ready markdown changelogs (grouped into Features, Bug Fixes, Docs, Chores, etc.).
  ```bash
  # Generate a changelog from the latest tag to HEAD
  commitgen changelog

  # Generate a changelog between specific tags/branches
  commitgen changelog --from-ref v1.0.0 --to-ref v1.1.0

  # Save the generated changelog directly to a file
  commitgen changelog --output CHANGELOG.md
  ```

- **Hook Mode**: If installed, the pre-configured git hook runs `commitgen commit --hook <temp_file> --hook-source <source>` in non-interactive mode. It fails gracefully (exits with code 0) if keys are missing or offline to make sure it never blocks your normal commit workflow.

- **Ollama Upgrade**: If your local model fails due to memory, CommitGen will automatically fall back to CPU.

## License

MIT License - see LICENSE file

## Author

[Sourav Tripathy](https://souravtripathy.com)
