diff --git a/README.md b/README.md index 55f4632..7224f2a 100644 --- a/README.md +++ b/README.md @@ -49,65 +49,16 @@ ollama serve 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 `: Specify Ollama model to use -- `--base-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" -``` +3. Select a suggestion or use it directly ## Configuration -### Config File +Configuration can be done via: -Create `.git-commit-ai/config.yaml`: +1. **Config file**: `.git-commit-ai/config.yaml` +2. **Environment variables**: `.git-commit-ai/.env` + +### Example Config (`~/.git-commit-ai/config.yaml`) ```yaml ollama: @@ -128,81 +79,258 @@ cache: ### 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 -export OLLAMA_MODEL=qwen2.5-coder:3b -export OLLAMA_BASE_URL=http://localhost:11434 -export COMMIT_MAX_LENGTH=80 -export CACHE_ENABLED=true +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`: 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 +### `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 -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 +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 -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 + +# Select or use the suggestion +git commit -m "feat(auth): add OAuth2 authentication flow" ``` ## Troubleshooting ### Ollama server not running -```bash -# Start Ollama server -ollama serve ``` +Error: Ollama server is not available +Please ensure Ollama is running at http://localhost:11434 +``` + +**Solution**: Start Ollama with `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 ``` +Model 'qwen2.5-coder:3b' not found +``` + +**Solution**: Pull the model with `ollama pull qwen2.5-coder:3b` ### No staged changes -```bash -# Stage your changes first -git add -git-commit-ai generate +``` +No staged changes found. +Please stage your changes first with 'git add ' ``` -## Contributing +**Solution**: Run `git add ` to stage your changes -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 +### 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 file for details +MIT License - see [LICENSE](LICENSE) file for details. + +## Contributing + +Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.