276 lines
6.5 KiB
Markdown
276 lines
6.5 KiB
Markdown
# Local Commit Message Generator
|
|
|
|
[](https://7000pct.gitea.bloupla.net/7000pctAUTO/local-commit-message-generator/actions)
|
|
[](https://pypi.org/project/local-commit-message-generator/)
|
|
[](https://pypi.org/project/local-commit-message-generator/)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
A CLI tool that generates conventional commit messages by analyzing staged git changes. Runs completely offline using pattern matching to detect changes and produce standardized commit messages.
|
|
|
|
## Features
|
|
|
|
- **Auto-detect commit type**: Automatically detects `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` based on file patterns
|
|
- **Scope detection**: Detects scopes from changed directories
|
|
- **Customizable templates**: Define your own commit message format via configuration
|
|
- **Git hook integration**: Automatically generate commit messages on `git commit`
|
|
- **Offline operation**: Runs completely offline with no external dependencies
|
|
- **Multiple scopes**: Supports comma-separated scopes for changes across multiple directories
|
|
|
|
## Installation
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
# Clone and install
|
|
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/local-commit-message-generator.git
|
|
cd local-commit-message-generator
|
|
pip install -e .
|
|
```
|
|
|
|
### Using pip
|
|
|
|
```bash
|
|
pip install local-commit-message-generator
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
1. Stage your changes:
|
|
```bash
|
|
git add src/
|
|
```
|
|
|
|
2. Generate a commit message:
|
|
```bash
|
|
commit-gen generate
|
|
```
|
|
|
|
3. Or preview what the message would be:
|
|
```bash
|
|
commit-gen preview
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Commands
|
|
|
|
#### generate
|
|
Generate and display a commit message from staged changes.
|
|
```bash
|
|
commit-gen generate
|
|
```
|
|
|
|
#### preview
|
|
Preview the commit message without printing it directly.
|
|
```bash
|
|
commit-gen preview
|
|
```
|
|
|
|
#### status
|
|
Show current staged changes status.
|
|
```bash
|
|
commit-gen status
|
|
```
|
|
|
|
#### install-hook
|
|
Install the prepare-commit-msg git hook for automatic message generation.
|
|
```bash
|
|
commit-gen install-hook
|
|
```
|
|
|
|
#### uninstall-hook
|
|
Remove the git hook.
|
|
```bash
|
|
commit-gen uninstall-hook
|
|
```
|
|
|
|
#### config
|
|
Manage configuration settings.
|
|
```bash
|
|
commit-gen config show # Show current configuration
|
|
commit-gen config set-template "custom: {description}" # Set template
|
|
commit-gen config reset # Reset to defaults
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The tool uses `~/.local_commit_gen.toml` for configuration.
|
|
|
|
### Default Configuration
|
|
|
|
```toml
|
|
template = "{type}{scope}: {description}"
|
|
description_length = 72
|
|
max_files = 5
|
|
include_file_list = true
|
|
file_list_template = "\n\nFiles changed:\n{files}"
|
|
|
|
[type_rules]
|
|
feat = ["src/", "lib/", "app/", "controllers/", "models/"]
|
|
fix = ["src/", "lib/", "bug", "fix", "issue", "hotfix"]
|
|
docs = [".md", ".rst", "docs/", "documentation/"]
|
|
style = [".css", ".scss", ".sass", ".less", "styles/"]
|
|
refactor = ["refactor/", "rewrite/", "restructure/"]
|
|
test = ["test/", "tests/", "__tests__/", ".test.", ".spec."]
|
|
chore = ["package.json", "pyproject.toml", "requirements", ".gitignore", "Makefile"]
|
|
perf = ["performance/", "perf/", "optimize/", "optimization/"]
|
|
ci = [".github/", ".gitlab-ci.yml", ".travis.yml", "Jenkinsfile", "tox.ini"]
|
|
build = ["build/", "webpack/", "vite.config", "babel.config", "rollup.config"]
|
|
```
|
|
|
|
### Custom Templates
|
|
|
|
Template variables available:
|
|
- `{type}` - Commit type (feat, fix, docs, etc.)
|
|
- `{scope}` - Commit scope in parentheses
|
|
- `{description}` - Generated description
|
|
- `{body}` - Extended body text
|
|
- `{files}` - List of changed files
|
|
|
|
Example:
|
|
```toml
|
|
template = "[{type}] ({scope}): {description}\n\n{files}"
|
|
```
|
|
|
|
### Custom Type Rules
|
|
|
|
Define patterns to match for each commit type:
|
|
|
|
```toml
|
|
[type_rules]
|
|
feat = ["src/features/", "myapp/"]
|
|
fix = ["bugfix/", "hotfix/"]
|
|
```
|
|
|
|
### Scope Mapping
|
|
|
|
Map directories to custom scope names:
|
|
|
|
```toml
|
|
[scopes]
|
|
"app/features/auth" = "auth"
|
|
"app/features/payments" = "payments"
|
|
```
|
|
|
|
## Git Hook Integration
|
|
|
|
Install the prepare-commit-msg hook to automatically generate commit messages:
|
|
|
|
```bash
|
|
commit-gen install-hook
|
|
```
|
|
|
|
The hook will:
|
|
1. Generate a commit message based on staged changes
|
|
2. Write it to the commit message file
|
|
3. Let you edit before finalizing
|
|
|
|
To uninstall:
|
|
```bash
|
|
commit-gen uninstall-hook
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Feature Change
|
|
```bash
|
|
$ git add src/features/user.py
|
|
$ commit-gen generate
|
|
feat(user): add user.py
|
|
```
|
|
|
|
### Bug Fix
|
|
```bash
|
|
$ git add src/utils.py
|
|
$ commit-gen generate
|
|
fix(utils): update utils.py
|
|
```
|
|
|
|
### Documentation Update
|
|
```bash
|
|
$ git add README.md docs/guide.md
|
|
$ commit-gen generate
|
|
feat(docs): add files
|
|
|
|
Files changed:
|
|
- README.md
|
|
- docs/guide.md
|
|
```
|
|
|
|
### Multiple Scopes
|
|
```bash
|
|
$ git add src/cli.py lib/core.py
|
|
$ commit-gen generate
|
|
feat(cli,lib): add files
|
|
|
|
Files changed:
|
|
- src/cli.py
|
|
- lib/core.py
|
|
```
|
|
|
|
## Development
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Create virtual environment
|
|
python -m venv venv
|
|
source venv/bin/activate # or `venv\Scripts\activate` on Windows
|
|
|
|
# Install dependencies
|
|
pip install -e ".[dev]"
|
|
|
|
# Run tests
|
|
pytest tests/ -v --cov=src --cov-report=term-missing
|
|
|
|
# Run linting
|
|
ruff check .
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
local-commit-message-generator/
|
|
├── src/
|
|
│ ├── __init__.py # Package init, version
|
|
│ ├── analyzer.py # Git change analysis
|
|
│ ├── cli.py # CLI interface
|
|
│ ├── config.py # Configuration management
|
|
│ ├── generator.py # Message generation logic
|
|
│ ├── hooks.py # Git hook integration
|
|
│ └── templates.py # Template management
|
|
├── tests/
|
|
│ ├── test_analyzer.py
|
|
│ ├── test_cli.py
|
|
│ ├── test_config.py
|
|
│ ├── test_generator.py
|
|
│ ├── test_hooks.py
|
|
│ └── test_templates.py
|
|
├── pyproject.toml
|
|
├── README.md
|
|
└── LICENSE
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
### "Not in git repository"
|
|
Make sure you're running the command from within a git repository.
|
|
|
|
### "No staged changes found"
|
|
Run `git add <files>` to stage your changes before generating a commit message.
|
|
|
|
### "Hook installation failed"
|
|
Check that you have write permissions to the `.git/hooks/` directory.
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Run tests: `pytest tests/ -v`
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
MIT License
|