A privacy-first CLI tool that generates intelligent Git commit message suggestions using local LLM (Ollama), supporting conventional commit formats and multi-language analysis without external API costs.

Features

Privacy-First: All processing happens locally with Ollama - no data leaves your machine
Conventional Commits: Support for conventional commit format (type(scope): description)
Multi-Language Analysis: Detects and analyzes changes in multiple programming languages
Commit History Context: Uses recent commit history for better suggestions
Customizable Prompts: Use your own prompt templates
Message Caching: Avoids redundant LLM calls for the same diff
Interactive Mode: Select from multiple suggestions

Installation

Prerequisites

Python 3.9+
Ollama installed and running

Install Git Commit AI

pip install git-commit-ai

Install and Start Ollama

# Install Ollama from https://ollama.com/

# Pull a model (recommended: qwen2.5-coder for coding tasks)
ollama pull qwen2.5-coder:3b

# Start Ollama server
ollama serve

Quick Start

Stage your changes:
```
git add .
```
Generate commit messages:
```
git-commit-ai generate
```
Select a suggestion or use the first one

Usage

Generate Commit Messages

git-commit-ai generate

Options:

--conventional/--no-conventional: Generate conventional commit format
--model <name>: Specify Ollama model to use
--base-url <url>: Ollama API base URL
--interactive/--no-interactive: Interactive selection mode
--show-diff: Show the diff being analyzed
--auto-fix: Auto-fix conventional commit format issues

Check Status

git-commit-ai status

Shows:

Git repository status
Ollama server availability
Model status
Cache statistics

List Available Models

git-commit-ai models

Pull a Model

git-commit-ai pull --model qwen2.5-coder:3b

Manage Cache

git-commit-ai cache

Validate Commit Message

git-commit-ai validate "feat(auth): add login"

Configuration

Config File

Create .git-commit-ai/config.yaml:

ollama:
  model: "qwen2.5-coder:3b"
  base_url: "http://localhost:11434"
  timeout: 120

commit:
  max_length: 80
  num_suggestions: 3
  conventional_by_default: false

cache:
  enabled: true
  directory: ".git-commit-ai/cache"
  ttl_hours: 24

Environment Variables

export OLLAMA_MODEL=qwen2.5-coder:3b
export OLLAMA_BASE_URL=http://localhost:11434
export COMMIT_MAX_LENGTH=80
export CACHE_ENABLED=true

Custom Prompts

Create custom prompt templates in .git-commit-ai/prompts/:

default.txt: Standard commit message prompts
conventional.txt: Conventional commit prompts
system_default.txt: System prompt for standard mode
system_conventional.txt: System prompt for conventional mode

Conventional Commits

Supported commit types:

feat: A new feature
fix: A bug fix
docs: Documentation only changes
style: Changes that do not affect the meaning of the code (white-space, formatting, etc)
refactor: A code change that neither fixes a bug nor adds a feature
perf: A code change that improves performance
test: Adding missing tests or correcting existing tests
chore: Changes to the build process or auxiliary tools
ci: Changes to our CI configuration files and scripts
build: Changes that affect the build system or external dependencies
revert: Reverts a previous commit

Example:

git-commit-ai generate --conventional
# Output:
# 1. feat(auth): add user authentication
# 2. fix: resolve login validation issue
# 3. docs: update API documentation

Troubleshooting

Ollama server not running

# Start Ollama server
ollama serve

Model not found

# Pull the model
ollama pull qwen2.5-coder:3b

# Or use git-commit-ai to pull
git-commit-ai pull --model qwen2.5-coder:3b

No staged changes

# Stage your changes first
git add <files>
git-commit-ai generate

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests: pytest git_commit_ai/tests/ -v
Submit a pull request

License

MIT License - see LICENSE file for details