AI Commit Message Generator

Generate conventional commit messages from git diffs using local LLMs. Analyzes staged changes, understands context, and produces clear, standardized commit messages.

Features

• Offline-First: Works with local Ollama models - no API keys required
• Conventional Commits: Follows the Conventional Commits specification
• Context-Aware: Understands file types, change patterns, and project structure
• Git Hook Integration: Auto-suggest on git commit
• Style Learning: Adapts to your commit message patterns

Installation

Prerequisites

1. Python 3.11 or higher
2. Ollama installed and running
3. A code-focused model pulled (recommended: qwen2.5-coder:7b)

# Install Ollama (if not already installed)
# See: https://ollama.ai/download

# Pull a recommended model
ollama pull qwen2.5-coder:7b

Install from source

# Clone the repository
git clone https://github.com/example/ai-commit-gen.git
cd ai-commit-gen

# Install in development mode
pip install -e .

# Or install with dev dependencies
pip install -e ".[dev]"

Quick Start

# Stage your changes
git add .

# Generate commit message suggestions
ai-commit suggest

# Install git hooks for automatic suggestions
ai-commit install-hooks

Usage

Generate Suggestions

# Basic usage - generates 3 suggestions
ai-commit suggest

# Use a different model
ai-commit suggest --model llama3.2:3b

# Generate more suggestions
ai-commit suggest --num 5

# Skip style learning from history
ai-commit suggest --no-learn-style

# Auto-commit with the best suggestion
ai-commit suggest --auto-commit

Git Hooks

# Install hooks for automatic suggestions
ai-commit install-hooks

# Force overwrite existing hooks
ai-commit install-hooks --force

# Check hook status
ai-commit hook-status

# Remove hooks
ai-commit uninstall-hooks

Analyze Your Style

# Analyze your commit history patterns
ai-commit analyze-style

# Analyze more commits
ai-commit analyze-style --limit 200

Validate Messages

# Validate a commit message file
ai-commit validate .git/COMMIT_EDITMSG

Example Output

$ ai-commit suggest

Analyzing changes...
  Files changed: 3
  Insertions: +45
  Deletions: -12
  Primary language: python

Learned from commit history:
  Analyzed: 50 commits
  Conventional: 42 (84%)
  Style: Uses imperative mood, starts with lowercase

Generating suggestions using qwen2.5-coder:7b...

Suggestions:

  1. feat(analyzer): add support for renamed file detection
     Detects renamed files in git diff and includes them in analysis
     Confidence: 90%

  2. feat(analyzer): implement file rename tracking
     Adds renamed files list to analysis output
     Confidence: 85%

  3. refactor(analyzer): improve diff parsing for renames
     Better handling of renamed files in git diff output
     Confidence: 75%

Use one of these messages? [Y/n]:

Conventional Commits Format

Messages follow the format: type(scope): description

Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation changes
style	Code style (formatting, semicolons, etc)
refactor	Code refactoring
perf	Performance improvements
test	Adding or updating tests
chore	Maintenance tasks
ci	CI/CD changes
build	Build system changes

Examples

feat(auth): add OAuth2 login support
fix(api): handle null response from server
docs: update installation instructions
refactor(utils): extract date formatting logic
test(auth): add unit tests for login flow

Configuration

Copy config/default-config.yaml to ~/.config/ai-commit/config.yaml to customize:

llm:
  model: "qwen2.5-coder:7b"
  temperature: 0.3

suggestions:
  count: 3
  learn_from_history: true

conventional:
  require_scope: false
  max_description_length: 72

Recommended Models

Model	Size	Speed	Quality
qwen2.5-coder:7b	4.7GB	Fast	Excellent
llama3.2:3b	2.0GB	Very Fast	Good
codellama:7b	3.8GB	Fast	Good
deepseek-coder:6.7b	3.8GB	Fast	Excellent

Project Structure

ai-commit-gen/
├── commit_gen/
│   ├── __init__.py
│   ├── cli.py           # Click CLI commands
│   ├── analyzer.py      # Git diff analysis
│   ├── generator.py     # LLM-based message generation
│   ├── learner.py       # Commit history style learning
│   └── hooks.py         # Git hook installation
├── templates/
│   ├── commit-msg-hook
│   └── prepare-commit-msg-hook
├── config/
│   └── default-config.yaml
├── tests/
├── pyproject.toml
└── README.md

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=commit_gen

# Format code
black commit_gen tests
ruff check commit_gen tests

# Type checking
mypy commit_gen

Troubleshooting

"Ollama not available"

Make sure Ollama is installed and running:

# Check if Ollama is running
ollama list

# Start Ollama service
ollama serve

"Model not found"

Pull the required model:

ollama pull qwen2.5-coder:7b

"No staged changes found"

Stage your changes first:

git add .
# or
git add <specific-files>

Git hooks not working

Check hook permissions and status:

ai-commit hook-status

# Reinstall hooks
ai-commit install-hooks --force

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (use ai-commit suggest of course!)
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request