local-commit-message-generator/README.md

Local Commit Message Generator

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

# 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

pip install local-commit-message-generator

Quick Start

1. Stage your changes:

   git add src/
   

2. Generate a commit message:

   commit-gen generate
   

3. Or preview what the message would be:

   commit-gen preview
   

Usage

Commands

generate

Generate and display a commit message from staged changes.

commit-gen generate

preview

Preview the commit message without printing it directly.

commit-gen preview

status

Show current staged changes status.

commit-gen status

install-hook

Install the prepare-commit-msg git hook for automatic message generation.

commit-gen install-hook

uninstall-hook

Remove the git hook.

commit-gen uninstall-hook

config

Manage configuration settings.

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

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:

template = "[{type}] ({scope}): {description}\n\n{files}"

Custom Type Rules

Define patterns to match for each commit type:

[type_rules]
feat = ["src/features/", "myapp/"]
fix = ["bugfix/", "hotfix/"]

Scope Mapping

Map directories to custom scope names:

[scopes]
"app/features/auth" = "auth"
"app/features/payments" = "payments"

Git Hook Integration

Install the prepare-commit-msg hook to automatically generate commit messages:

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:

commit-gen uninstall-hook

Examples

Feature Change

$ git add src/features/user.py
$ commit-gen generate
feat(user): add user.py

Bug Fix

$ git add src/utils.py
$ commit-gen generate
fix(utils): update utils.py

Documentation Update

$ git add README.md docs/guide.md
$ commit-gen generate
feat(docs): add files

Files changed:
  - README.md
  - docs/guide.md

Multiple Scopes

$ 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

# 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