enhanced-git

Git-AI

Generate Conventional Commit messages and changelog sections using AI. Simple to install, works with Use Local models with Ollama or OpenAI, gracefully degrades when no AI is available.

Features

• AI-Powered: Generate commit messages using OpenAI or local Ollama models
• Conventional Commits: Follows strict Conventional Commit formatting rules
• Changelog Generation: Create Keep a Changelog formatted sections
• Git Hook Integration: Automatic commit message generation on git commit
• Fallback Mode: Works without AI using intelligent heuristics
• Cross-Platform: Linux, macOS support
• Zero Dependencies: Single Python package, minimal runtime deps

Quick Start (60 seconds)

Install

# using pipx (recommended)
pipx install enhanced-git

# or using pip
pip install enhanced-git

Setup (Optional AI Integration)

With OpenAI:

export OPENAI_API_KEY="your-api-key-here"

With Ollama (Local AI):

# install Ollama and pull a model
ollama pull qwen2.5-coder:3b

# set environment variables
export OLLAMA_BASE_URL="http://localhost:11434"
export OLLAMA_MODEL="qwen2.5-coder:3b"

Basic Usage

# stage some changes
git add .

# Install Git hook for automatic generation
git-ai hook install

#if using git-ai hook, then just do git commit -m "some sample message"
#if not using git-ai hook use this:
git commit -m "$(git-ai commit)"


# generate changelog
git-ai changelog --since v1.0.0 --version v1.1.0

Usage

Commands

git-ai commit

Generate a commit message from staged changes.

# Basic usage
git-ai commit

# Preview without committing
git-ai commit --dry-run

# Subject line only
git-ai commit --no-body

# Force plain style (no conventional format)
git-ai commit --style plain

# Used by Git hook
git-ai commit --hook /path/to/.git/COMMIT_EDITMSG

git-ai hook install

Install Git hook for automatic commit message generation.

# Install hook
git-ai hook install

# Force overwrite existing hook
git-ai hook install --force

# Remove hook
git-ai hook uninstall

git-ai changelog

Generate changelog section from commit history.

# generate changelog from commits since v1.0.0
git-ai changelog --since v1.0.0

# with version header
git-ai changelog --since v1.0.0 --version v1.1.0

# custom output file
git-ai changelog --since v1.0.0 --output HISTORY.md

# different end reference
git-ai changelog --since v1.0.0 --to main

Environment Variables

• OPENAI_API_KEY: Your OpenAI API key
• OLLAMA_BASE_URL: Ollama server URL (default: http://localhost:11434)
• OLLAMA_MODEL: Ollama model name (default: qwen2.5-coder:3b)

Important for pipx users: pipx creates isolated environments that don't inherit shell environment variables. Use one of these solutions:

# Solution 1: Use the setup command (easiest)
git-ai setup --provider ollama --model qwen2.5-coder:3b
# This creates ~/.config/gitai/config.toml for global configuration

# Solution 2: Use .gitai.toml config file (per-project)
# Create .gitai.toml in your project root with:
[llm]
provider = "ollama"
model = "qwen2.5-coder:3b"

# Solution 3: Set variables in your shell profile (.bashrc, .zshrc, etc.)
export OLLAMA_BASE_URL="http://localhost:11434"
export OLLAMA_MODEL="qwen2.5-coder:3b"
# Then restart your terminal

# Solution 4: Use environment variables inline
OLLAMA_BASE_URL="http://localhost:11434" OLLAMA_MODEL="qwen2.5-coder:3b" git-ai commit

Configuration Files

GitAI supports configuration at multiple levels:

• Global config: ~/.config/gitai/config.toml (applies to all repositories)
• Project config: .gitai.toml in git repository root (overrides global config)

Create a global configuration easily with:

git-ai setup --provider ollama --model qwen2.5-coder:3b

Auto-detection: GitAI automatically detects your LLM provider based on environment variables (no config file needed!):

• If OPENAI_API_KEY is set → uses OpenAI
• If OLLAMA_BASE_URL or OLLAMA_MODEL is set → uses Ollama
• Otherwise → falls back to OpenAI

Custom configuration: Create .gitai.toml in your project root for advanced settings:

[llm]
provider = "ollama"          # "openai" | "ollama"
model = "qwen2.5-coder:3b"        # I suggest using one of: qwen2.5-coder:3b, qwen2.5-coder:1.5b, codellama:7b, deepseek-coder:6.7b
max_tokens = 300
temperature = 0.1
timeout_seconds = 45

[commit]
style = "conventional"       # "conventional" | "plain"
scope_detection = true
include_body = true
include_footers = true
wrap_width = 72

[changelog]
grouping = "type"            # group by Conventional Commit type
heading_style = "keep-a-changelog"

[debug]
debug_mode = false

How It Works

Commit Message Generation

• Diff Analysis: Parses git diff --staged to understand changes
• Type Inference: Detects commit type from file paths and content:
  • tests/ → test
  • docs/ → docs
  • fix/bug in content → fix
  • New files → feat
• AI Enhancement: Uses LLM to polish the message while preserving accuracy
• Formatting: Ensures Conventional Commit compliance:
  • Subject < 70 chars
  • type(scope): description format
  • Proper body wrapping at 72 columns

Changelog Generation

• Commit Parsing: Extracts commits between references
• Grouping: Groups by Conventional Commit types
• AI Polish: Improves clarity while preserving facts
• Insertion: Adds new section to top of CHANGELOG.md

Fallback Mode

When no AI is configured, GitAI uses intelligent heuristics:

• Path-based type detection
• Content analysis for keywords
• Statistical analysis of changes
• Scope inference from directory structure

Development

Setup

# clone repository
git clone https://github.com/yourusername/git-ai.git
cd gitai

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

# run tests
pytest

# run linting
ruff check .
mypy gitai

Project Structure

gitai/
├── cli.py              # Main CLI entry point
├── commit.py           # Commit message generation
├── changelog.py        # Changelog generation
├── config.py           # Configuration management
├── constants.py        # Prompts and constants
├── diff.py             # Git diff parsing and chunking
├── hook.py             # Git hook management
├── providers/          # LLM providers
│   ├── base.py
│   ├── openai_provider.py
│   └── ollama_provider.py
├── util.py             # Utility functions
└── __init__.py

tests/                  # Test suite
├── test_commit.py
├── test_changelog.py
├── test_diff.py
└── test_hook_integration.py

Contributing

I welcome contributions! Be kind

Development Requirements

• Python 3.11+
• Poetry for dependency management
• Pre-commit for code quality

Testing

# run test suite
pytest

# with coverage
pytest --cov=gitai --cov-report=html

# run specific tests
pytest tests/test_commit.py -v

License

MIT License - see LICENSE file for details.

Privacy & Security

• No Code Storage: Your code never leaves your machine
• Local AI Option: Use Ollama for complete local processing
• API Usage: Only sends commit diffs and prompts to configured LLM
• Graceful Degradation: Works without any network access

Troubleshooting

No staged changes

Error: No staged changes found. Did you forget to run 'git add'?

Solution: Stage your changes with git add before running git-ai commit

Missing API key

Warning: OPENAI_API_KEY environment variable is required

Solution: Set your API key or use Ollama for local AI

Hook conflicts

Warning: Existing commit-msg hook found

Solution: Use git-ai hook install --force to overwrite, or manually merge

Network timeouts

Error: Ollama API error: Connection timeout

Solution: Check Ollama is running: ollama serve

Large diffs

GitAI automatically chunks large diffs to stay within LLM token limits

Examples

Example Commit Messages

AI-Generated:

feat(auth): add user registration and login system

- Implement user registration with email validation
- Add login endpoint with JWT token generation
- Create password hashing utilities
- Add input validation and error handling

Fallback Mode:

feat(src): add user authentication module

- add src/auth.py (45 additions)
- update src/models.py (12 additions, 3 deletions)

Example Changelog

## [v1.1.0] - 2024-01-15

### Features
- **auth**: Add user registration and login system (#123)
- **api**: Implement RESTful user management endpoints

### Fixes
- **core**: Fix null pointer exception in user validation (#456)
- **db**: Resolve connection timeout issues

### Documentation
- Update API documentation with authentication examples
- Add installation instructions for local development