Initial upload: Add git-commit-ai project with CLI tool for AI-powered commit messages

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 <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"
-```
+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:
+
+```
+<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
 
-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 <files>
-git-commit-ai generate
+```
+No staged changes found.
+Please stage your changes first with 'git add <files>'
 ```
 
-## Contributing
+**Solution**: Run `git add <files>` 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.