337 lines
6.5 KiB
Markdown
337 lines
6.5 KiB
Markdown
# 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](https://ollama.com/) installed and running
|
|
|
|
### Install Git Commit AI
|
|
|
|
```bash
|
|
pip install git-commit-ai
|
|
```
|
|
|
|
### Install and Start Ollama
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
git add .
|
|
```
|
|
|
|
2. Generate commit messages:
|
|
```bash
|
|
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`)
|
|
|
|
```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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
git-commit-ai status
|
|
```
|
|
|
|
#### models
|
|
|
|
List available Ollama models.
|
|
|
|
```bash
|
|
git-commit-ai models
|
|
```
|
|
|
|
#### pull
|
|
|
|
Pull an Ollama model.
|
|
|
|
```bash
|
|
git-commit-ai pull [MODEL]
|
|
```
|
|
|
|
#### validate
|
|
|
|
Validate a commit message format.
|
|
|
|
```bash
|
|
git-commit-ai validate "feat(auth): add login"
|
|
```
|
|
|
|
#### cache
|
|
|
|
Manage cache.
|
|
|
|
```bash
|
|
git-commit-ai cache
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](https://www.conventionalcommits.org/) 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```yaml
|
|
ollama:
|
|
timeout: 300 # 5 minutes
|
|
```
|
|
|
|
## Development
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
git clone https://github.com/yourusername/git-commit-ai.git
|
|
cd git-commit-ai
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Check code style
|
|
ruff check .
|
|
|
|
# Auto-fix issues
|
|
ruff check --fix .
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License - see [LICENSE](LICENSE) file for details.
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
|