git-commit-msg-ai 2.1.1

AI-powered git commit message generator following Conventional Commits

git-commit-msg-ai

AI-powered git commit message generator that follows the Conventional Commits specification.

Prerequisites

• Python 3.14+

• An Anthropic API key set as an environment variable:

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

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

python -m venv .venv

Activate the virtual environment:

# macOS/Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

Install the project and dev dependencies:

pip install -e ".[dev]"

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

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

Installation

pip install git-commit-msg-ai

Usage

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

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)

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

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

User-level (~/.git-commit-msg-ai.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
4. A GitHub Release is created with release notes generated by Claude Sonnet from the commit log

Releasing a new version:

# 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

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