diff --git a/README.md b/README.md index 7224f2a..3664e67 100644 --- a/README.md +++ b/README.md @@ -1,336 +1,71 @@ -# Git Commit AI +# 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. +A privacy-first CLI tool that generates intelligent Git commit message suggestions using local LLM (Ollama), supporting conventional commit formats 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 +- Generate intelligent commit message suggestions from staged changes +- Support for Conventional Commits format +- Multi-language analysis +- Privacy-first (no external APIs, runs entirely locally) +- Customizable prompts and configurations +- Context-aware suggestions using commit history ## 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: +1. Ensure [Ollama](https://ollama.ai) is installed and running +2. Pull a model (recommended: qwen2.5-coder:3b): + ```bash + ollama pull qwen2.5-coder:3b + ``` +3. Stage your changes: ```bash git add . ``` - -2. Generate commit messages: +4. Generate a commit message: ```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: - -``` -(): -``` - -### 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 +### With Conventional Commits ```bash git-commit-ai generate --conventional +``` -# Select or use the suggestion -git commit -m "feat(auth): add OAuth2 authentication flow" +### Specify Model + +```bash +git-commit-ai generate --model llama3.2 +``` + +## Configuration + +Create a `.git-commit-ai/config.yaml` file in your repository: + +```yaml +model: qwen2.5-coder:3b +base_url: http://localhost:11434 +conventional: true +max_length: 80 ``` ## 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 ' -``` - -**Solution**: Run `git add ` 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. +- Ensure Ollama is running: `ollama list` +- Check model is available: `ollama pull ` +- Verify git repository has staged changes