Metadata-Version: 2.4
Name: git-commit-msg-ai
Version: 2.1.1
Summary: AI-powered git commit message generator following Conventional Commits
License: MIT License
        
        Copyright (c) 2026 Ankit Joshi
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic
Provides-Extra: dev
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# git-commit-msg-ai

AI-powered git commit message generator that follows the [Conventional Commits](https://www.conventionalcommits.org/) specification.

## Prerequisites

- Python 3.14+
- An Anthropic API key set as an environment variable:

  ```sh
  export ANTHROPIC_API_KEY=sk-ant-...   # macOS/Linux
  ```

  ```powershell
  [System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-...', 'User')   # Windows
  ```

## Development Setup

Clone the repository, create a virtual environment, and install the project in editable mode with all dev dependencies:

```sh
python -m venv .venv
```

Activate the virtual environment:

```sh
# macOS/Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1
```

Install the project and dev dependencies:

```sh
pip install -e ".[dev]"
```

After activation the `git-commit-msg-ai` entry-point is on your PATH. You can also run the dev toolchain:

```sh
pytest          # run tests with coverage
ruff check .    # lint
mypy .          # type-check
```

## Installation

```sh
pip install git-commit-msg-ai
```

## Usage

Stage your changes, then run the tool from inside any git repository:

```sh
git add <files>
git-commit-msg-ai
```

The tool will:
1. Read your staged diff
2. Generate a commit message using Claude AI
3. Print the message and prompt you to choose:

```
[a]ccept / [e]dit / [r]eject:
```

- **a** - commits immediately with the generated message
- **e** - opens the message in your `$EDITOR` (defaults to `notepad` on Windows, `vi` on Linux/macOS), lets you modify it, then commits
- **r** - exits without committing

## Commit message format

Generated messages follow the Conventional Commits specification:

```
<type>(<optional scope>): <short subject>

- Bullet explaining why this change was made
- Another reason if applicable
```

For breaking changes, the subject line gets a `!` and a footer is added:

```
feat(api)!: remove deprecated endpoint

- Endpoint was unused and blocking the new auth rollout

BREAKING CHANGE: /v1/legacy is no longer available
```

Supported types: `feat`, `fix`, `revert`, `build`, `ci`, `docs`, `perf`, `refactor`, `style`, `test` (configurable — see [Configuration](#configuration))

`revert` commits always follow this format: the subject line begins with `revert: ` followed by the header of the reverted commit, and the body must contain `This reverts commit <hash>.`

## Configuration

The set of optional commit types the AI may use can be customised through a config file. `feat`, `fix`, and `revert` are always included regardless of any configuration.

### Config file locations and precedence

The tool checks the following locations in order, using the first one that defines a `types` list:

1. **Project-level** — `pyproject.toml` walked up from the current working directory, under `[tool.git-commit-msg-ai]`
2. **User-level** — `~/.git-commit-msg-ai.toml` in your home directory
3. **Built-in defaults** — used when neither config file is present or neither defines `types`

### Config file formats

Project-level (`pyproject.toml`):

```toml
[tool.git-commit-msg-ai]
types = ["build", "ci", "docs", "perf", "refactor", "style", "test"]
```

User-level (`~/.git-commit-msg-ai.toml`):

```toml
types = ["build", "ci", "docs", "chore"]
```

Setting `types = []` restricts the AI to only the three mandatory types (`feat`, `fix`, `revert`).

### Default optional types

| Type | Purpose |
|---|---|
| `build` | Changes to the build system or external dependencies |
| `ci` | Changes to CI configuration files and scripts |
| `docs` | Documentation-only changes |
| `perf` | A code change that improves performance |
| `refactor` | A code change that neither fixes a bug nor adds a feature |
| `style` | Changes that do not affect the meaning of the code (whitespace, formatting) |
| `test` | Adding missing tests or correcting existing tests |

## CI/CD

Every push to `main` and every pull request runs the full CI pipeline (lint, type-check, tests, build).

Pushing a version tag (e.g. `v1.5.2`) triggers the CD pipeline:

1. Tests are re-run as a gate
2. The tag version is verified to match the version in `pyproject.toml`
3. The package is built and published to [PyPI](https://pypi.org/project/git-commit-msg-ai/)
4. A GitHub Release is created with release notes generated by Claude Sonnet from the commit log

**Releasing a new version:**

```powershell
# 1. Bump the version in pyproject.toml
# 2. Commit and push
git add pyproject.toml
git commit -m "chore: bump version to 1.5.2"
git push origin main
# 3. Tag and push - this triggers the CD pipeline
git tag v1.5.2
git push origin v1.5.2
```

## Debugging

When a failure occurs (git error, API error, editor error), the tool always prints an error message to **stderr**. Diagnostic logs are disabled by default; to enable them, set the `GIT_COMMIT_AI_LOG_LEVEL` environment variable before running the command. Both error messages and logs are written to **stderr** and do not interfere with the generated commit message on **stdout**.

Valid values: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

```sh
# macOS/Linux - show all internal diagnostic messages
GIT_COMMIT_AI_LOG_LEVEL=DEBUG git-commit-msg-ai

# Windows PowerShell
$env:GIT_COMMIT_AI_LOG_LEVEL = 'DEBUG'
git-commit-msg-ai
```

| Level | What you see |
|---|---|
| `DEBUG` | git commands run, API model/token params, temp file paths, char counts |
| `INFO` | commit message generated (with char count), commit created |
| `WARNING` | no staged changes found |
| `ERROR` | git not found, API failures, editor errors |

## License

This project is released under the [MIT License](LICENSE).
