Initial upload: Git Commit AI - privacy-first CLI for generating commit messages with local LLM

2026-01-31 03:00:14 +00:00
parent d61c862388
commit b40ecdc860
1 changed files with 207 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,208 @@
-# 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 without external API costs.
+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 the first one
+
+## Usage
+
+### Generate Commit Messages
+
+```bash
+git-commit-ai generate
+```
+
+Options:
+- `--conventional/--no-conventional`: Generate conventional commit format
+- `--model <name>`: 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 commit format issues
+
+### Check Status
+
+```bash
+git-commit-ai status
+```
+
+Shows:
+- Git repository status
+- Ollama server availability
+- Model status
+- Cache statistics
+
+### List Available Models
+
+```bash
+git-commit-ai models
+```
+
+### Pull a Model
+
+```bash
+git-commit-ai pull --model qwen2.5-coder:3b
+```
+
+### Manage Cache
+
+```bash
+git-commit-ai cache
+```
+
+### Validate Commit Message
+
+```bash
+git-commit-ai validate "feat(auth): add login"
+```
+
+## Configuration
+
+### Config File
+
+Create `.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
+
+```bash
+export OLLAMA_MODEL=qwen2.5-coder:3b
+export OLLAMA_BASE_URL=http://localhost:11434
+export COMMIT_MAX_LENGTH=80
+export CACHE_ENABLED=true
+```
+
+## Custom Prompts
+
+Create custom prompt templates in `.git-commit-ai/prompts/`:
+
+- `default.txt`: Standard commit message prompts
+- `conventional.txt`: Conventional commit prompts
+- `system_default.txt`: System prompt for standard mode
+- `system_conventional.txt`: System prompt for conventional mode
+
+## Conventional Commits
+
+Supported commit types:
+- `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
+- `chore`: Changes to the build process or auxiliary tools
+- `ci`: Changes to our CI configuration files and scripts
+- `build`: Changes that affect the build system or external dependencies
+- `revert`: Reverts a previous commit
+
+Example:
+```bash
+git-commit-ai generate --conventional
+# Output:
+# 1. feat(auth): add user authentication
+# 2. fix: resolve login validation issue
+# 3. docs: update API documentation
+```
+
+## Troubleshooting
+
+### Ollama server not running
+
+```bash
+# Start Ollama server
+ollama serve
+```
+
+### Model not found
+
+```bash
+# Pull the model
+ollama pull qwen2.5-coder:3b
+
+# Or use git-commit-ai to pull
+git-commit-ai pull --model qwen2.5-coder:3b
+```
+
+### No staged changes
+
+```bash
+# Stage your changes first
+git add <files>
+git-commit-ai generate
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `pytest git_commit_ai/tests/ -v`
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details