# Git-AI
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
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
```bash
# using pipx (recommended)
pipx install enhanced-git
# or using pip
pip install enhanced-git
```
### Setup (Optional AI Integration)
**With OpenAI:**
```bash
export OPENAI_API_KEY="your-api-key-here"
```
**With Ollama (Local AI):**
```bash
# 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
```bash
# 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.
```bash
# 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.
```bash
# 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.
```bash
# 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:
```bash
# 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:
1. **Global config**: `~/.config/gitai/config.toml` (applies to all repositories)
2. **Project config**: `.gitai.toml` in git repository root (overrides global config)
Create a global configuration easily with:
```bash
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:
```toml
[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
1. **Diff Analysis**: Parses `git diff --staged` to understand changes
2. **Type Inference**: Detects commit type from file paths and content:
- `tests/` → `test`
- `docs/` → `docs`
- `fix`/`bug` in content → `fix`
- New files → `feat`
3. **AI Enhancement**: Uses LLM to polish the message while preserving accuracy
4. **Formatting**: Ensures Conventional Commit compliance:
- Subject < 70 chars
- `type(scope): description` format
- Proper body wrapping at 72 columns
### Changelog Generation
1. **Commit Parsing**: Extracts commits between references
2. **Grouping**: Groups by Conventional Commit types
3. **AI Polish**: Improves clarity while preserving facts
4. **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
```bash
# 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
```bash
# 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](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
```markdown
## [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
```
Raw data
{
"_id": null,
"home_page": null,
"name": "enhanced-git",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Abdullah Zahid <abdullahzahid229@gmail.com>",
"keywords": "ai, changelog, commit, conventional-commits, git, llm",
"author": null,
"author_email": "Abdullah Zahid <abdullahzahid229@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a8/73/a0a74cb0ec2a5548fee225ce79564d47beabd7c6e1b08dbaa873bcc3e8eb/enhanced_git-1.0.6.tar.gz",
"platform": null,
"description": "# Git-AI\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\nGenerate Conventional Commit messages and changelog sections using AI. Simple to install, works with\nUse Local models with Ollama or OpenAI, gracefully degrades when no AI is available.\n\n## Features\n\n- **AI-Powered**: Generate commit messages using OpenAI or local Ollama models\n- **Conventional Commits**: Follows strict Conventional Commit formatting rules\n- **Changelog Generation**: Create Keep a Changelog formatted sections\n- **Git Hook Integration**: Automatic commit message generation on `git commit`\n- **Fallback Mode**: Works without AI using intelligent heuristics\n- **Cross-Platform**: Linux, macOS support\n- **Zero Dependencies**: Single Python package, minimal runtime deps\n\n## Quick Start (60 seconds)\n\n### Install\n\n```bash\n# using pipx (recommended)\npipx install enhanced-git\n\n# or using pip\npip install enhanced-git\n```\n\n### Setup (Optional AI Integration)\n\n**With OpenAI:**\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n**With Ollama (Local AI):**\n```bash\n# install Ollama and pull a model\nollama pull qwen2.5-coder:3b\n\n# set environment variables\nexport OLLAMA_BASE_URL=\"http://localhost:11434\"\nexport OLLAMA_MODEL=\"qwen2.5-coder:3b\"\n```\n\n### Basic Usage\n\n```bash\n# stage some changes\ngit add .\n\n# Install Git hook for automatic generation\ngit-ai hook install\n\n#if using git-ai hook, then just do git commit -m \"some sample message\"\n#if not using git-ai hook use this:\ngit commit -m \"$(git-ai commit)\"\n\n\n# generate changelog\ngit-ai changelog --since v1.0.0 --version v1.1.0\n```\n\n## Usage\n\n### Commands\n\n#### `git-ai commit`\n\nGenerate a commit message from staged changes.\n\n```bash\n# Basic usage\ngit-ai commit\n\n# Preview without committing\ngit-ai commit --dry-run\n\n# Subject line only\ngit-ai commit --no-body\n\n# Force plain style (no conventional format)\ngit-ai commit --style plain\n\n# Used by Git hook\ngit-ai commit --hook /path/to/.git/COMMIT_EDITMSG\n```\n\n#### `git-ai hook install`\n\nInstall Git hook for automatic commit message generation.\n\n```bash\n# Install hook\ngit-ai hook install\n\n# Force overwrite existing hook\ngit-ai hook install --force\n\n# Remove hook\ngit-ai hook uninstall\n```\n\n#### `git-ai changelog`\n\nGenerate changelog section from commit history.\n\n```bash\n# generate changelog from commits since v1.0.0\ngit-ai changelog --since v1.0.0\n\n# with version header\ngit-ai changelog --since v1.0.0 --version v1.1.0\n\n# custom output file\ngit-ai changelog --since v1.0.0 --output HISTORY.md\n\n# different end reference\ngit-ai changelog --since v1.0.0 --to main\n```\n\n### Environment Variables\n\n- `OPENAI_API_KEY`: Your OpenAI API key\n- `OLLAMA_BASE_URL`: Ollama server URL (default: http://localhost:11434)\n- `OLLAMA_MODEL`: Ollama model name (default: qwen2.5-coder:3b)\n\n**Important for pipx users**: pipx creates isolated environments that don't inherit shell environment variables. Use one of these solutions:\n\n```bash\n# Solution 1: Use the setup command (easiest)\ngit-ai setup --provider ollama --model qwen2.5-coder:3b\n# This creates ~/.config/gitai/config.toml for global configuration\n\n# Solution 2: Use .gitai.toml config file (per-project)\n# Create .gitai.toml in your project root with:\n[llm]\nprovider = \"ollama\"\nmodel = \"qwen2.5-coder:3b\"\n\n# Solution 3: Set variables in your shell profile (.bashrc, .zshrc, etc.)\nexport OLLAMA_BASE_URL=\"http://localhost:11434\"\nexport OLLAMA_MODEL=\"qwen2.5-coder:3b\"\n# Then restart your terminal\n\n# Solution 4: Use environment variables inline\nOLLAMA_BASE_URL=\"http://localhost:11434\" OLLAMA_MODEL=\"qwen2.5-coder:3b\" git-ai commit\n```\n\n### Configuration Files\n\nGitAI supports configuration at multiple levels:\n\n1. **Global config**: `~/.config/gitai/config.toml` (applies to all repositories)\n2. **Project config**: `.gitai.toml` in git repository root (overrides global config)\n\nCreate a global configuration easily with:\n```bash\ngit-ai setup --provider ollama --model qwen2.5-coder:3b\n```\n\n**Auto-detection**: GitAI automatically detects your LLM provider based on environment variables (no config file needed!):\n- If `OPENAI_API_KEY` is set \u2192 uses OpenAI\n- If `OLLAMA_BASE_URL` or `OLLAMA_MODEL` is set \u2192 uses Ollama\n- Otherwise \u2192 falls back to OpenAI\n\n**Custom configuration**: Create `.gitai.toml` in your project root for advanced settings:\n\n```toml\n[llm]\nprovider = \"ollama\" # \"openai\" | \"ollama\"\nmodel = \"qwen2.5-coder:3b\" # I suggest using one of: qwen2.5-coder:3b, qwen2.5-coder:1.5b, codellama:7b, deepseek-coder:6.7b\nmax_tokens = 300\ntemperature = 0.1\ntimeout_seconds = 45\n\n[commit]\nstyle = \"conventional\" # \"conventional\" | \"plain\"\nscope_detection = true\ninclude_body = true\ninclude_footers = true\nwrap_width = 72\n\n[changelog]\ngrouping = \"type\" # group by Conventional Commit type\nheading_style = \"keep-a-changelog\"\n\n[debug]\ndebug_mode = false\n```\n\n## How It Works\n\n### Commit Message Generation\n\n1. **Diff Analysis**: Parses `git diff --staged` to understand changes\n2. **Type Inference**: Detects commit type from file paths and content:\n - `tests/` \u2192 `test`\n - `docs/` \u2192 `docs`\n - `fix`/`bug` in content \u2192 `fix`\n - New files \u2192 `feat`\n3. **AI Enhancement**: Uses LLM to polish the message while preserving accuracy\n4. **Formatting**: Ensures Conventional Commit compliance:\n - Subject < 70 chars\n - `type(scope): description` format\n - Proper body wrapping at 72 columns\n\n### Changelog Generation\n\n1. **Commit Parsing**: Extracts commits between references\n2. **Grouping**: Groups by Conventional Commit types\n3. **AI Polish**: Improves clarity while preserving facts\n4. **Insertion**: Adds new section to top of CHANGELOG.md\n\n### Fallback Mode\n\nWhen no AI is configured, GitAI uses intelligent heuristics:\n\n- Path-based type detection\n- Content analysis for keywords\n- Statistical analysis of changes\n- Scope inference from directory structure\n\n## Development\n\n### Setup\n\n```bash\n# clone repository\ngit clone https://github.com/yourusername/git-ai.git\ncd gitai\n\n# install with dev dependencies\npip install -e \".[dev]\"\n\n# run tests\npytest\n\n# run linting\nruff check .\nmypy gitai\n```\n\n### Project Structure\n\n```\ngitai/\n\u251c\u2500\u2500 cli.py # Main CLI entry point\n\u251c\u2500\u2500 commit.py # Commit message generation\n\u251c\u2500\u2500 changelog.py # Changelog generation\n\u251c\u2500\u2500 config.py # Configuration management\n\u251c\u2500\u2500 constants.py # Prompts and constants\n\u251c\u2500\u2500 diff.py # Git diff parsing and chunking\n\u251c\u2500\u2500 hook.py # Git hook management\n\u251c\u2500\u2500 providers/ # LLM providers\n\u2502 \u251c\u2500\u2500 base.py\n\u2502 \u251c\u2500\u2500 openai_provider.py\n\u2502 \u2514\u2500\u2500 ollama_provider.py\n\u251c\u2500\u2500 util.py # Utility functions\n\u2514\u2500\u2500 __init__.py\n\ntests/ # Test suite\n\u251c\u2500\u2500 test_commit.py\n\u251c\u2500\u2500 test_changelog.py\n\u251c\u2500\u2500 test_diff.py\n\u2514\u2500\u2500 test_hook_integration.py\n```\n\n## Contributing\n\nI welcome contributions! Be kind\n\n### Development Requirements\n\n- Python 3.11+\n- Poetry for dependency management\n- Pre-commit for code quality\n\n### Testing\n\n```bash\n# run test suite\npytest\n\n# with coverage\npytest --cov=gitai --cov-report=html\n\n# run specific tests\npytest tests/test_commit.py -v\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Privacy & Security\n\n- **No Code Storage**: Your code never leaves your machine\n- **Local AI Option**: Use Ollama for complete local processing\n- **API Usage**: Only sends commit diffs and prompts to configured LLM\n- **Graceful Degradation**: Works without any network access\n\n## Troubleshooting\n\n### No staged changes\n```\nError: No staged changes found. Did you forget to run 'git add'?\n```\n**Solution**: Stage your changes with `git add` before running `git-ai commit`\n\n### Missing API key\n```\nWarning: OPENAI_API_KEY environment variable is required\n```\n**Solution**: Set your API key or use Ollama for local AI\n\n### Hook conflicts\n```\nWarning: Existing commit-msg hook found\n```\n**Solution**: Use `git-ai hook install --force` to overwrite, or manually merge\n\n### Network timeouts\n```\nError: Ollama API error: Connection timeout\n```\n**Solution**: Check Ollama is running: `ollama serve`\n\n### Large diffs\nGitAI automatically chunks large diffs to stay within LLM token limits\n\n## Examples\n\n### Example Commit Messages\n\n**AI-Generated:**\n```\nfeat(auth): add user registration and login system\n\n- Implement user registration with email validation\n- Add login endpoint with JWT token generation\n- Create password hashing utilities\n- Add input validation and error handling\n```\n\n**Fallback Mode:**\n```\nfeat(src): add user authentication module\n\n- add src/auth.py (45 additions)\n- update src/models.py (12 additions, 3 deletions)\n```\n\n### Example Changelog\n\n```markdown\n## [v1.1.0] - 2024-01-15\n\n### Features\n- **auth**: Add user registration and login system (#123)\n- **api**: Implement RESTful user management endpoints\n\n### Fixes\n- **core**: Fix null pointer exception in user validation (#456)\n- **db**: Resolve connection timeout issues\n\n### Documentation\n- Update API documentation with authentication examples\n- Add installation instructions for local development\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate Conventional Commit messages and changelog sections using AI",
"version": "1.0.6",
"project_urls": {
"Documentation": "https://github.com/mxzahid/git-ai#readme",
"Homepage": "https://github.com/mxzahid/git-ai",
"Issues": "https://github.com/mxzahid/git-ai/issues",
"Repository": "https://github.com/mxzahid/git-ai"
},
"split_keywords": [
"ai",
" changelog",
" commit",
" conventional-commits",
" git",
" llm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "55c1b1261eef65dba922b1026ef2bb1613128a38e633e7983f91feec3359376f",
"md5": "ce57350387566aaeac18a3a4e20fb7b6",
"sha256": "8f922c781bd094017076f2b912b65fa5f31dd9ca739a2c09efeb3fd12ad26b4c"
},
"downloads": -1,
"filename": "enhanced_git-1.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ce57350387566aaeac18a3a4e20fb7b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 24549,
"upload_time": "2025-09-09T00:32:47",
"upload_time_iso_8601": "2025-09-09T00:32:47.397538Z",
"url": "https://files.pythonhosted.org/packages/55/c1/b1261eef65dba922b1026ef2bb1613128a38e633e7983f91feec3359376f/enhanced_git-1.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a873a0a74cb0ec2a5548fee225ce79564d47beabd7c6e1b08dbaa873bcc3e8eb",
"md5": "72dce24d6da0331cac6dc51ff9bc81fd",
"sha256": "1152a11823fc536b69bfb7487c9018163021ef9c180283e555d1df155010d856"
},
"downloads": -1,
"filename": "enhanced_git-1.0.6.tar.gz",
"has_sig": false,
"md5_digest": "72dce24d6da0331cac6dc51ff9bc81fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 25459,
"upload_time": "2025-09-09T00:32:48",
"upload_time_iso_8601": "2025-09-09T00:32:48.490309Z",
"url": "https://files.pythonhosted.org/packages/a8/73/a0a74cb0ec2a5548fee225ce79564d47beabd7c6e1b08dbaa873bcc3e8eb/enhanced_git-1.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 00:32:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mxzahid",
"github_project": "git-ai#readme",
"github_not_found": true,
"lcname": "enhanced-git"
}
JSON
