commitgen-tool 0.1.3

AI-powered Conventional Commit message generator for Git using OpenAI

CommitGen

AI-powered Conventional Commit message generator for Git

Stop writing bad commit messages. CommitGen uses AI to analyze your staged changes and generates clean, structured commits that follow the Conventional Commits standard.

Features

• Generate Conventional Commit messages from staged changes
• Interactive CLI with inline or editor-based editing
• Support for Git workflows of any size

# Before CommitGen
git commit -m "fix stuff"
git commit -m "final fix"
git commit -m "pls work"

# With CommitGen
[FIX]: resolve null pointer in authentication handler
[FEAT]: add user session management with Redis
[DOCS]: update API documentation with examples

---

Installation

pip install commitgen-tool

Requirements:

• Python 3.10+
• Git installed and configured
• OpenAI API key with available tokens (currently required)

⚠️ Important: This version requires an OpenAI API key and uses paid API calls. Support for free local LLMs is planned for future releases.

---

Quick Start

# 1. Set up your OpenAI API key (one-time setup)
commitgen config
# Enter your API key when prompted

# 2. Stage your changes
git add .

# 3. Generate and commit
commitgen commit

That's it! CommitGen will analyze your diff and suggest a commit message.

---

Getting an OpenAI API Key

1. Go to OpenAI Platform
2. Sign up or log in
3. Navigate to API Keys section
4. Create a new API key
5. Add credits to your account (pay-as-you-go)

Cost: Approximately $0.001-0.01 per commit message (very affordable!)

You can set usage limits in your OpenAI dashboard to control costs.

---

Basic Usage

Generate a Commit

commitgen commit

You'll see a suggested message:

💡 Suggested Commit Message
┌──────────────────────────────────────────┐
│ [FEAT]: add user authentication endpoint │
└──────────────────────────────────────────┘

(a)ccept, (r)egenerate with context, (i)nline edit, (e)xtended editor, or (q)uit?

Options When Reviewing

• a - Accept and commit immediately
• r - Add context to refine the message
• i - Edit the message in your terminal
• e - Open your preferred text editor
• q - Quit without committing

Commit and Push

# Commit and push in one command
commitgen commit --push

# Or use the short flag
commitgen commit -p

Other Commands

# Configure API key
commitgen config

# Show version
commitgen version

# Get help
commitgen --help

---

How It Works

1. Analyzes Your Changes: Reads git diff --staged to see what you've modified
2. AI Processing: Sends the diff to OpenAI's GPT-5-nano model with instructions to generate a Conventional Commit
3. Interactive Review: Lets you accept, edit, or regenerate the message
4. Safe Commit: Only commits after you approve the message

Current Model: CommitGen uses GPT-5-nano for fast, cost-effective commit generation. Model selection will be configurable in future releases.

What Gets Sent to OpenAI?

Only your git diff is sent - not your entire codebase. The diff shows:

• Which files changed
• What lines were added/removed
• Function and variable names in the changes

Privacy Note: If you're working with sensitive code, review the diff before committing or consider waiting for local LLM support.

---

Conventional Commit Types

CommitGen automatically categorizes your changes:

Type	When to Use	Example
FEAT	New features	[FEAT]: add OAuth2 authentication
FIX	Bug fixes	[FIX]: resolve memory leak in cache
DOCS	Documentation	[DOCS]: add API endpoint examples
STYLE	Code formatting	[STYLE]: apply black formatter
REFACTOR	Code restructuring	[REFACTOR]: extract helper functions
PERF	Performance improvements	[PERF]: optimize database queries
TEST	Adding tests	[TEST]: add unit tests for auth
CHORE	Maintenance	[CHORE]: update dependencies
CI	CI/CD changes	[CI]: add GitHub Actions workflow

---

Configuration

CommitGen stores your API key securely in:

• Linux/macOS: ~/.config/commitgen/config.env
• Windows: %USERPROFILE%\.config\commitgen\config.env

The key is stored locally and never transmitted except to OpenAI's API.

⚠️ Never commit this file to Git

---

Examples

Example 1: Simple Feature

# You made changes to add a login endpoint
git add src/auth.py

commitgen commit

Generated:

[FEAT]: add user login endpoint with JWT tokens

---

Example 2: Multiple Changes

# You updated API, tests, and docs
git add src/api.py tests/test_api.py README.md

commitgen commit

Generated:

[FEAT]: add user registration endpoint
[TEST]: add integration tests for registration
[DOCS]: update README with API examples

---

Example 3: Bug Fix with Context

commitgen commit

When prompted, choose (r) to regenerate with context:

Add context: Fixes issue #123 where special characters broke login

Generated:

[FIX]: sanitize special characters in login handler

Fixes #123

---

Example 4: Using Extended Editor

Choose (e) to open your editor:

# CommitGen opens your $GIT_EDITOR with:

# CommitGen – Extended Commit Message Editor
#
# Save the file before closing to apply changes.
# Lines starting with '#' will be ignored.
#

[FEAT]: add user authentication

Edit, save (Ctrl+S), and close. CommitGen will use your edited message.

---

Setting Your Preferred Editor

CommitGen respects the same editor settings as Git.

VS Code (Recommended)

Windows PowerShell:

setx GIT_EDITOR "code --wait"

Linux/macOS:

echo 'export GIT_EDITOR="code --wait"' >> ~/.bashrc
# or for zsh:
echo 'export GIT_EDITOR="code --wait"' >> ~/.zshrc

Other Editors

Vim:

export GIT_EDITOR=vim

Nano:

export GIT_EDITOR=nano

Sublime Text:

export GIT_EDITOR="subl -w"

---

Workflow Integration

Typical Development Flow

# 1. Make your changes
vim src/feature.py

# 2. Stage what you want to commit
git add src/feature.py

# 3. Let CommitGen handle the message
commitgen commit

# 4. Push when ready
git push

Working with Unstaged Changes

If you run commitgen commit without staging:

No staged changes detected.
(a) stage all, (s) select files, (q) quit?

• a - Stages everything (git add .)
• s - Lets you pick specific files
• q - Exits so you can stage manually

---

Troubleshooting

"OpenAI API key not found"

Solution:

commitgen config
# Enter your API key

Your key is stored in ~/.config/commitgen/config.env

---

"You are not inside a Git repository"

Solution: Navigate to a Git repository or initialize one:

git init

---

"No staged changes detected"

Solution: Stage your changes first:

git add <files>
# or
git add .

---

Editor doesn't wait for save

If using VS Code, ensure you have the --wait flag:

# Check your setting
echo $GIT_EDITOR

# Should show: code --wait
# If not, set it:
export GIT_EDITOR="code --wait"

---

Generic/unclear commit messages

Solution: Use the regenerate option with context:

1. Choose (r) when prompted
2. Provide specific details about what changed
3. CommitGen will regenerate with your context

Example:

Add context: Optimized query performance by adding database indexes

---

Advanced Usage

Customizing the Workflow

Skip the push prompt:

# Always push after commit
commitgen commit --push

# Never get asked to push
# (just press 'n' when prompted)

Working with branches:

# CommitGen works with any branch
git checkout -b feature/new-feature
# ... make changes ...
commitgen commit

Amending commits:

# CommitGen doesn't amend, but you can after:
git commit --amend

---

Comparison with Alternatives

vs Manual Writing

Manual	CommitGen
❌ Inconsistent format	✅ Always follows Conventional Commits
❌ Vague messages	✅ Specific, contextual descriptions
❌ Prone to typos	✅ Properly formatted
❌ Time-consuming	✅ Instant generation

vs GitHub Copilot

Copilot	CommitGen
Only suggests based on file names	Analyzes actual diff content
Generic suggestions	Context-aware with GPT-5-nano
No editing workflow	Interactive review and editing
No multiple change handling	Handles FEAT + FIX + DOCS in one commit
Fixed model	Model selection coming soon

---

Security & Privacy

What CommitGen Sends to OpenAI

• ✅ Git diff (added/removed lines)
• ✅ File paths
• ❌ Your full source code
• ❌ Git history
• ❌ Credentials or secrets

API Key Storage

• Stored locally in ~/.config/commitgen/
• Never transmitted except to OpenAI
• Never logged or committed

Best Practices

1. Review diffs before committing - Ensure no secrets are staged
2. Use .gitignore - Keep sensitive files out of commits
3. Set OpenAI usage limits - Control API costs in your OpenAI dashboard
4. Use environment variables for secrets - Never hardcode credentials

---

Limitations & Future Plans

Current Limitations

• ⚠️ Requires OpenAI API key (paid service)
• ⚠️ Requires internet connection to generate messages
• ⚠️ Fixed AI model (GPT-5-nano) - no model selection yet
• ⚠️ No support for commit templates yet
• ⚠️ English-only commit messages (for now)

Planned Features

• 🔄 Local LLM support - Use Ollama, LM Studio, or local models (offline commits!)
• 🎛️ Model selection - Choose your preferred OpenAI model (GPT-4, GPT-3.5, etc.)
• 🎨 Custom templates - Define your own commit format
• 🌍 Multi-language - Commits in your preferred language
• 🔗 Git hooks integration - Auto-suggest on git commit
• 📊 Commit history - Learn from your commit patterns
• 🎯 Team presets - Share commit style across teams

---

Project Roadmap

Version 0.1.0 (Current) ✅

• Basic commit generation with GPT-5-nano
• Interactive workflow (accept/regenerate/edit)
• OpenAI integration
• Configuration management
• Comprehensive test suite
• CI/CD pipeline

Version 0.2.0 (Planned)

• Local LLM support (Ollama, LM Studio)
• Configurable AI model selection
• Custom commit templates
• Commit message history/learning

Version 0.3.0 (Future)

• Multi-language commit messages
• Git hooks integration
• VS Code extension
• Team presets and shared configurations

---

Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature
   

3. Make your changes
4. Write or update tests
5. Commit using CommitGen!

   commitgen commit
   

6. Push and open a PR

   git push origin feature/amazing-feature
   

Development Setup

# Clone the repo
git clone https://github.com/<your-username>/commitgen.git
cd commitgen

# Install in editable mode
pip install -e .

# Run tests (when available)
pytest

---

FAQ

Why does CommitGen need an API key?

Currently, CommitGen uses OpenAI's GPT-5-nano model to understand your code changes. This model is hosted by OpenAI and requires authentication.

Future versions will support:

• Free local LLMs (Ollama, LM Studio)
• Model selection (GPT-4, GPT-3.5-turbo, etc.)

---

How much does it cost?

With GPT-5-nano, approximately $0.001 to $0.01 per commit depending on diff size. For most developers:

• 100 commits/month = ~$0.10 - $1.00
• Set usage limits in your OpenAI dashboard to control costs

GPT-5-nano is optimized for speed and cost-effectiveness.

---

Can I use other AI providers?

Not yet, but it's planned! Future versions will support:

• Anthropic Claude
• Google Gemini
• Local models (Ollama, LM Studio)
• Azure OpenAI

---

Is my code sent to OpenAI?

Only the git diff is sent - showing what changed in your staged files. Your full codebase, git history, and credentials are never transmitted.

---

What if I don't have internet?

CommitGen requires an internet connection to contact OpenAI's API. Local LLM support (which works offline) is planned for v0.2.0.

---

Can I customize the commit format?

Not yet, but custom templates are planned for v0.3.0. Currently, CommitGen follows standard Conventional Commits format.

---

Does CommitGen work with GitLab/Bitbucket?

Yes! CommitGen works with any Git repository, regardless of where it's hosted (GitHub, GitLab, Bitbucket, self-hosted, etc.).

---

Support

Found a bug?

Open an issue: GitHub Issues

Have a question?

Start a discussion: GitHub Discussions

Want to contribute?

See our Contributing section above!

---

Acknowledgments

Built with:

• OpenAI API - AI-powered analysis
• Typer - CLI framework
• Rich - Terminal formatting
• Conventional Commits - Commit standard

---

License

MIT License © [Christopher Kola]

See LICENSE for full details.

---

Links

• PyPI: commitgen-cli
• GitHub: github.com//commitgen
• Documentation: [Coming soon]
• Changelog: CHANGELOG.md

---

⭐ If CommitGen helps you write better commits, please star the repository!

---

Made with ❤️ by developers who care about commit quality