git-commit-ai/README.md

Git Commit AI

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

1. Stage your changes:

   git add .
   

2. Generate commit messages:

   git-commit-ai generate
   

3. Select a suggestion or use it directly

Configuration

Configuration can be done via:

1. Config file: .git-commit-ai/config.yaml
2. Environment variables: .git-commit-ai/.env

Example Config (~/.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

Variable	Description	Default
OLLAMA_MODEL	Default Ollama model	qwen2.5-coder:3b
OLLAMA_BASE_URL	Ollama API URL	http://localhost:11434
COMMIT_MAX_LENGTH	Max message length	80
CACHE_ENABLED	Enable caching	true

Usage

Commands

generate

Generate commit message suggestions for staged changes.

git-commit-ai generate [OPTIONS]

Options:

• --conventional / --no-conventional: Use conventional commit format
• --model MODEL: 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 format issues

status

Check Ollama and repository status.

git-commit-ai status

models

List available Ollama models.

git-commit-ai models

pull

Pull an Ollama model.

git-commit-ai pull [MODEL]

validate

Validate a commit message format.

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

cache

Manage cache.

git-commit-ai cache

Examples

Basic Usage

# Stage changes
git add src/auth.py tests/test_auth.py

# Generate suggestions
git-commit-ai generate

# Output:
# Suggested commit messages:
#   1. feat(auth): add user login functionality
#   2. fix(auth): resolve authentication bug
#   3. test(auth): add login tests

Conventional Commits

# Generate conventional format suggestions
git-commit-ai generate --conventional

# Output:
#   1. feat(api): implement user authentication endpoints
#   2. fix(db): resolve connection pool leak
#   3. docs(readme): update installation instructions

Custom Model

# Use a different Ollama model
git-commit-ai generate --model llama2 --conventional

Custom Prompts

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

default.txt

Custom default prompt template:

You are a commit message expert.
Analyze this diff and generate a concise message:
{diff}

{few_shot}

Suggestions:

conventional.txt

Custom conventional commit prompt:

Generate a conventional commit message.
Format: type(scope): description

Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Diff:
{diff}

{few_shot}

Generate 3 suggestions:

Conventional Commits

Git Commit AI supports the Conventional Commits specification:

<type>(<scope>): <description>

Valid Types

Type	Description
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
build	Changes that affect the build system or external dependencies
ci	Changes to our CI configuration files and scripts
chore	Other changes that don't modify src or test files
revert	Reverts a previous commit

Example

git-commit-ai generate --conventional

# Select or use the suggestion
git commit -m "feat(auth): add OAuth2 authentication flow"

Troubleshooting

Ollama server not running

Error: Ollama server is not available
Please ensure Ollama is running at http://localhost:11434

Solution: Start Ollama with ollama serve

Model not found

Model 'qwen2.5-coder:3b' not found

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

No staged changes

No staged changes found.
Please stage your changes first with 'git add <files>'

Solution: Run git add <files> to stage your changes

Not in a git repository

Error: Not in a git repository

Solution: Initialize a git repo with git init or navigate to a repository

LLM generation timeout

Increase the timeout in config:

ollama:
  timeout: 300  # 5 minutes

Development

Setup

git clone https://github.com/yourusername/git-commit-ai.git
cd git-commit-ai
pip install -e ".[dev]"

Running Tests

# Run all tests
python -m pytest git_commit_ai/tests/ -v

# Run with coverage
python -m pytest git_commit_ai/tests/ --cov=git_commit_ai --cov-report=term-missing

Linting

# Check code style
ruff check .

# Auto-fix issues
ruff check --fix .

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please read our Contributing Guide for details.