Git-LLM-Tool

AI-powered git commit message and changelog generator using LLM APIs.

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Advanced Features
• CLI Commands Reference
• Environment Variables
• Usage Examples
• Supported Models
• Development
• Contributing
• Git Custom Command Integration
• Troubleshooting
• License

Features

• 🤖 Smart Commit Messages: Automatically generate commit messages from git diff using AI
• 📝 Changelog Generation: Generate structured changelogs from git history
• 🔧 Multiple LLM Providers: Support for OpenAI, Anthropic Claude, Google Gemini, Azure OpenAI, and Ollama
• 🚀 Intelligent Chunking: Automatic diff splitting with parallel processing for large changes
• 🔄 Hybrid Processing: Use local Ollama for chunk processing + cloud LLM for final quality
• 📊 Progress Indicators: Beautiful progress bars with Halo for long-running operations
• ⚙️ Hierarchical Configuration: Project-level and global configuration support
• 🎯 Jira Integration: Automatic ticket detection and work hours tracking
• 🌐 Multi-language Support: Generate messages in different languages
• ✏️ Editor Integration: Configurable editor support for reviewing commit messages
• 🛠️ Easy Setup: Simple installation and configuration

Installation

From PyPI (Coming Soon)

pip install git-llm-tool

From Source

git clone https://github.com/z0890142/git-llm-tool.git
cd git-llm-tool
poetry install

Quick Start

1. Initialize Configuration

git-llm config init

2. Configure Your API Key

Choose one of the supported providers:

# OpenAI
git-llm config set llm.api_keys.openai sk-your-openai-key-here

# Anthropic Claude
git-llm config set llm.api_keys.anthropic sk-ant-your-key-here

# Google Gemini
git-llm config set llm.api_keys.google your-gemini-key-here

# Azure OpenAI
git-llm config set llm.api_keys.azure_openai your-azure-key
git-llm config set llm.azure_openai.endpoint https://your-resource.openai.azure.com/
git-llm config set llm.azure_openai.deployment_name gpt-4o

3. Generate Commit Messages

# Stage your changes
git add .

# Generate and review commit message (opens editor)
git-llm commit

# Or apply directly without review
git-llm commit --apply

4. Generate Changelogs

# Generate changelog from last tag to HEAD
git-llm changelog

# Generate changelog for specific range
git-llm changelog --from v1.0.0 --to v2.0.0

Configuration

Configuration Hierarchy

The tool uses a hierarchical configuration system (highest to lowest priority):

1. CLI flags (highest priority)
2. Project config .git-llm-tool.yaml
3. Global config ~/.git-llm-tool/config.yaml
4. Environment variables
5. Default values

Configuration Options

LLM Settings

# Set default model
git-llm config set llm.default_model gpt-4o

# Set output language (en, zh, ja, etc.)
git-llm config set llm.language en

# API Keys
git-llm config set llm.api_keys.openai sk-your-key
git-llm config set llm.api_keys.anthropic sk-ant-your-key
git-llm config set llm.api_keys.google your-key

# Azure OpenAI specific settings
git-llm config set llm.azure_openai.endpoint https://your-resource.openai.azure.com/
git-llm config set llm.azure_openai.api_version 2024-12-01-preview
git-llm config set llm.azure_openai.deployment_name gpt-4o

# Hybrid Ollama processing (optional)
git-llm config set llm.use_ollama_for_chunks true
git-llm config set llm.ollama_model llama3:8b
git-llm config set llm.ollama_base_url http://localhost:11434

Editor Configuration

# Set preferred editor for commit message review
git-llm config set editor.preferred_editor vi
git-llm config set editor.preferred_editor nano
git-llm config set editor.preferred_editor "code --wait"  # VS Code
git-llm config set editor.preferred_editor "subl --wait"  # Sublime Text

Editor Priority (highest to lowest):

1. editor.preferred_editor config
2. git config core.editor
3. Environment variables (GIT_EDITOR, VISUAL, EDITOR)
4. System defaults (nano, vim, vi)

Jira Integration

# Enable Jira integration
git-llm config set jira.enabled true

# Set branch regex pattern for ticket extraction
git-llm config set jira.branch_regex '^(feat|fix|chore)\/([A-Z]+-\d+)\/.+$'

Example Configuration File

Global config (~/.git-llm-tool/config.yaml):

llm:
  default_model: 'gpt-4o'
  language: 'en'
  api_keys:
    openai: 'sk-your-openai-key'
    anthropic: 'sk-ant-your-key'
    google: 'your-gemini-key'
  azure_openai:
    endpoint: 'https://your-resource.openai.azure.com/'
    api_version: '2024-12-01-preview'
    deployment_name: 'gpt-4o'

  # LangChain and intelligent processing
  use_langchain: true
  chunking_threshold: 12000  # Enable chunking for diffs larger than 12k tokens

  # Hybrid Ollama processing (optional)
  use_ollama_for_chunks: false   # Set to true to enable
  ollama_model: "llama3:8b"      # Local model for chunk processing
  ollama_base_url: "http://localhost:11434"

editor:
  preferred_editor: 'vi'

jira:
  enabled: true
  ticket_pattern: '^(feat|fix|chore)\/([A-Z]+-\d+)\/.+$'

View Configuration

# View all configuration
git-llm config get

# View specific setting
git-llm config get llm.default_model
git-llm config get editor.preferred_editor

Advanced Features

Intelligent Chunking & Parallel Processing

For large diffs, git-llm-tool automatically uses intelligent chunking to break down changes into manageable pieces:

• Automatic Threshold Detection: Diffs larger than 12,000 tokens are automatically chunked
• Smart Splitting: Prioritizes file-based splitting, then hunks, then size-based splitting
• Parallel Processing: Multiple chunks processed simultaneously for faster results
• Progress Indicators: Beautiful progress bars show real-time processing status

# Enable verbose mode to see chunking details
git-llm commit --verbose

# Example output:
# 🔄 Analyzing diff and creating intelligent chunks...
# ✅ Created 4 intelligent chunks
# 📄 Smart chunking stats:
#    Total chunks: 4
#    File chunks: 2
#    Hunk chunks: 2
#    Complete files: 2
# 🚀 Processing 4 chunks in parallel (4/4 completed)...
# ✅ Parallel processing completed: 4/4 chunks successful
# 🔄 Combining 4 summaries into final commit message...
# ✅ Final commit message generated successfully

Hybrid Ollama Processing

Use local Ollama for chunk processing combined with cloud LLM for final quality:

Setup Ollama

# Install Ollama (macOS/Linux)
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama3:8b
# or
ollama pull llama3.1:8b
ollama pull codellama:7b

Enable Hybrid Mode

# Enable hybrid processing
git-llm config set llm.use_ollama_for_chunks true
git-llm config set llm.ollama_model llama3:8b

# Verify Ollama is running
curl http://localhost:11434/api/version

How It Works

1. Map Phase: Each chunk processed locally with Ollama (fast, private)
2. Reduce Phase: Final combination using cloud LLM (high quality)
3. Cost Efficient: Reduces cloud API usage while maintaining quality
4. Privacy: Sensitive code chunks processed locally

# With verbose mode, you'll see:
git-llm commit --verbose

# 🔄 Hybrid processing mode:
#    Map phase (chunks): Ollama (llama3:8b)
#    Reduce phase (final): gpt-4o
# 🚀 Processing 4 chunks in parallel (4/4 completed)...

LangChain Integration

Advanced LLM provider management with automatic model selection:

• Automatic Provider Detection: Based on model name
• Retry Logic: Exponential backoff for failed requests
• Rate Limiting: Prevents API quota exhaustion
• Error Recovery: Graceful fallbacks

CLI Commands Reference

Commit Command

git-llm commit [OPTIONS]

Options:
  -a, --apply          Apply commit message directly without opening editor
  -m, --model TEXT     Override LLM model (e.g., gpt-4, claude-3-sonnet)
  -l, --language TEXT  Override output language (e.g., en, zh, ja)
  -v, --verbose        Enable verbose output
  --help               Show help message

Changelog Command

git-llm changelog [OPTIONS]

Options:
  --from TEXT     Starting reference (default: last tag)
  --to TEXT       Ending reference (default: HEAD)
  -o, --output TEXT  Output file (default: stdout)
  -f, --force        Force overwrite existing output file
  --help             Show help message

Config Commands

git-llm config init                    # Initialize configuration
git-llm config get [KEY]              # Get configuration value(s)
git-llm config set KEY VALUE          # Set configuration value

Environment Variables

You can also configure the tool using environment variables:

# LLM API Keys
export OPENAI_API_KEY="sk-your-openai-key"
export ANTHROPIC_API_KEY="sk-ant-your-key"
export GOOGLE_API_KEY="your-gemini-key"

# Azure OpenAI
export AZURE_OPENAI_API_KEY="your-azure-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o"

# Override default model
export GIT_LLM_MODEL="gpt-4o"
export GIT_LLM_LANGUAGE="en"

Usage Examples

Basic Workflow

# 1. Make changes to your code
echo "console.log('Hello World');" > app.js

# 2. Stage changes
git add app.js

# 3. Generate commit message with review
git-llm commit
# Opens your editor with AI-generated message for review

# 4. Or apply directly
git-llm commit --apply

Using Different Models

# Use specific model for this commit
git-llm commit --model claude-3-sonnet

# Use different language
git-llm commit --language zh

Project-specific Configuration

Create .git-llm-tool.yaml in your project root:

llm:
  default_model: 'claude-3-sonnet'
  language: 'zh'
editor:
  preferred_editor: 'code --wait'
jira:
  enabled: true
  branch_regex: '^(feat|fix|docs)\/([A-Z]+-\d+)\/.+$'

Supported Models

OpenAI

• gpt-4o (recommended)
• gpt-4o-mini
• gpt-4-turbo
• gpt-3.5-turbo

Anthropic Claude

• claude-3-5-sonnet-20241022 (recommended)
• claude-3-5-haiku-20241022
• claude-3-opus-20240229

Google Gemini

• gemini-1.5-pro
• gemini-1.5-flash

Azure OpenAI

• Any deployment of the above OpenAI models

Ollama (Local)

For hybrid processing (chunk processing only):

• llama3:8b (recommended)
• llama3.1:8b
• llama3:70b
• codellama:7b
• codellama:13b
• mistral:7b
• qwen2:7b

Note: Ollama models are used only for chunk processing in hybrid mode. Final commit message generation still uses cloud LLMs for optimal quality.

Development

Setup Development Environment

# Clone repository
git clone https://github.com/z0890142/git-llm-tool.git
cd git-llm-tool

# Install dependencies
poetry install

# Install pre-commit hooks
poetry run pre-commit install

Running Tests

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=git_llm_tool

# Run specific test file
poetry run pytest tests/test_config.py

Code Formatting

# Format code
poetry run black .
poetry run isort .

# Check formatting
poetry run black --check .
poetry run flake8 .

Building and Publishing

# Build package
poetry build

# Publish to PyPI (maintainers only)
poetry publish

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (poetry run pytest)
6. Format code (poetry run black . && poetry run isort .)
7. Commit your changes (git-llm commit 😉)
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Git Custom Command Integration

You can integrate git-llm as a native git subcommand, allowing you to use git llm instead of git-llm.

Method 1: Git Aliases (Recommended)

Add aliases to your git configuration:

# Add git aliases for all commands
git config --global alias.llm-commit '!git-llm commit'
git config --global alias.llm-changelog '!git-llm changelog'
git config --global alias.llm-config '!git-llm config'

# Or create a general alias
git config --global alias.llm '!git-llm'

Now you can use:

git llm commit              # Instead of git-llm commit
git llm changelog           # Instead of git-llm changelog
git llm config get          # Instead of git-llm config get

# Or with specific aliases
git llm-commit              # Direct alias to git-llm commit
git llm-changelog           # Direct alias to git-llm changelog

Method 2: Shell Aliases

Add to your shell profile (.bashrc, .zshrc, etc.):

# Simple alias
alias gllm='git-llm'

# Or git-style aliases
alias gllmc='git-llm commit'
alias gllmcl='git-llm changelog'
alias gllmcfg='git-llm config'

Usage:

gllm commit                 # git-llm commit
gllmc                       # git-llm commit
gllmcl                      # git-llm changelog

Method 3: Custom Git Script

Create a custom git command script:

# Create git-llm script in your PATH
sudo tee /usr/local/bin/git-llm > /dev/null << 'EOF'
#!/bin/bash
# Git-LLM integration script
exec git-llm "$@"
EOF

sudo chmod +x /usr/local/bin/git-llm

Now you can use:

git llm commit              # Calls git-llm commit
git llm changelog           # Calls git-llm changelog

Recommended Git Workflow

With git aliases configured, your workflow becomes:

# Make changes
echo "console.log('Hello');" > app.js

# Stage changes
git add .

# Generate AI commit message (opens editor)
git llm commit

# Or commit directly
git llm commit --apply

# Generate changelog
git llm changelog

# Check configuration
git llm config get

Requirements

• Python 3.12+
• Git
• At least one LLM provider API key (OpenAI, Anthropic, Google, or Azure OpenAI)
• Optional: Ollama for hybrid processing (local chunk processing)

Troubleshooting

Common Issues

"No suitable editor found"

• Set your preferred editor: git-llm config set editor.preferred_editor vi
• Or set git editor: git config --global core.editor vi

"No staged changes found"

• Stage your changes first: git add .

"API Error: Invalid API key"

• Check your API key configuration: git-llm config get
• Ensure the key is correctly set: git-llm config set llm.api_keys.openai sk-your-key

"No commits found in range"

• Make sure you have commits in the specified range
• Check git log: git log --oneline

"Ollama not available, using main LLM for chunks"

• Make sure Ollama is installed and running: ollama serve
• Check Ollama is accessible: curl http://localhost:11434/api/version
• Verify the model is pulled: ollama list
• Pull the model if needed: ollama pull llama3:8b

"Processing is slower than expected"

• For large diffs, enable hybrid mode with Ollama for faster chunk processing
• Check your chunking_threshold setting - lower values use chunking sooner
• Use --verbose to see processing details and bottlenecks

"Chunk processing failed"

• If using Ollama, ensure sufficient system resources (RAM)
• Try a smaller model like llama3:8b instead of larger models
• Check Ollama logs: ollama logs

License

MIT License