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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: pytest git_commit_ai/tests/ -v
5. Submit a pull request

License

MIT License - see LICENSE file for details