py-opencommit 0.1.1

AI-powered commit message generator

PyOC - Python OpenCommit CLI (Experimental)

PyOC is an AI-powered git commit message generator. This is a port of https://github.com/di-sukharev/opencommit in python. The python implementation provides similar functionality as the original Node.js OpenCommit tool with a clean, Pythonic interface. This repo is in BETA/experimental stage, it was hastily ported until basics were working for me. There are some issues, much of it was auto-generated by AI. I'm providing this mainly to folks that want a python fork for any reason - it may help in any scenario that requires pythonic interface or runtime.

Table of Contents

• Installation
  • Using pipx (Recommended)
  • Using pip
  • Using UV
  • From Source
• Usage
  • Generate Commit Messages
  • Configure PyOC
  • Setup Git Hooks
  • Using the Python Module Directly
• Configuration
  • Available Options
  • Configuration File
  • Environment Variables
• Differences from Node.js Version
• Troubleshooting

Installation

Using pipx (Recommended)

pipx is the recommended installation method for CLI tools as it installs the package in an isolated environment but makes it available globally.

pipx install py-opencommit

Using pip

You can install PyOC using pip:

pip install py-opencommit

From Source

git clone https://github.com/ariel-frischer/py-opencommit.git
cd py-opencommit
uv venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv install -e .

Usage

Once installed, PyOC CLI can be accessed with the pyoc command.

Generate Commit Messages

Generate an AI-powered commit message from your staged changes:

# Generate commit message from staged changes
pyoc commit

# Generate commit message and automatically stage all changes
pyoc commit --stage-all

# Generate commit message with additional context
pyoc commit --context "This commit fixes the bug in the login form"

# Skip confirmation prompt
pyoc commit --skip-confirmation

# Pass additional arguments to git commit
pyoc commit -- -m "Custom message" --no-verify

Example Workflow

$ git add src/feature.py
$ pyoc commit
✨ Analyzing your changes...
📝 Generated commit message:
   feat: implement user authentication in login form

? Use this commit message? [Y/n] y
🎉 Commit successful!

Configure PyOC

Configure the CLI settings:

# Show current configuration
pyoc config

# Set OpenAI API key
pyoc config --set api_key=sk-your-api-key

# Set preferred language
pyoc config --set language=en

# Set model
pyoc config --set model=gpt-3.5-turbo

Setup Git Hooks

Set up git hooks for automatic commit message generation:

# Install git hooks in the current repository
pyoc githook --install

# Uninstall git hooks
pyoc githook --uninstall

# Show current hook status
pyoc githook --status

Using the Python Module Directly

You can also run PyOC directly as a Python module without installing it globally. This is useful for:

• Using the tool without installing it globally
• Development and testing
• Running from source code

# Generate commit message from staged changes
python -m src.python.cli commit

# Generate commit message and automatically stage all changes
python -m src.python.cli commit --stage-all

# Generate commit message with additional context
python -m src.python.cli commit --context "This commit fixes the bug in the login form"

# Configure PyOC
python -m src.python.cli config --set api_key=sk-your-api-key

# Install git hooks
python -m src.python.cli githook --install

Example Workflow Using Python Module

$ git add src/feature.py
$ python -m src.python.cli commit
✨ Analyzing your changes...
📝 Generated commit message:
   feat: implement user authentication in login form

? Use this commit message? [Y/n] y
🎉 Commit successful!

Configuration

PyOC can be configured through the CLI, a configuration file, or environment variables.

Available Options

Option	Description	Default
api_key	The API key for the LLM provider (e.g., OpenAI)	None
model	The LLM model to use	gpt-3.5-turbo
language	The language for commit messages	en
message_template	Template for commit messages	None
emoji	Whether to include emoji in commit messages	true
prompt_template	Custom prompt template for the AI	Default template

Configuration File

The configuration file is located at:

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

Example configuration file:

[pyoc]
api_key = sk-your-api-key
model = gpt-3.5-turbo
language = en
emoji = true

Environment Variables

You can also use environment variables to configure PyOC:

# Set API key
export OCO_API_KEY=sk-your-api-key

# Set model
export OCO_MODEL=gpt-3.5-turbo

# Set language
export OCO_LANGUAGE=en

LiteLLM Integration

PyOC uses LiteLLM for interfacing with AI providers:

┌─────────┐     ┌───────────┐     ┌─────────────┐
│  PyOC   │────▶│  LiteLLM  │────▶│  OpenAI API │
└─────────┘     └───────────┘     └─────────────┘

Benefits of using LiteLLM:

• Unified interface to multiple LLM providers
• Error handling and retries
• Token counting and cost tracking
• Potential for future provider expansion

Differences from Node.js Version

The Python CLI implementation aims to provide the same functionality as the Node.js version with some differences:

1. LLM Provider Support: Initially, only OpenAI is supported (via LiteLLM)
2. Configuration Structure: Uses INI format instead of JSON
3. Command Structure: Uses Click instead of Commander.js
4. Package Management: Uses UV instead of npm
5. Performance: May have different performance characteristics

Troubleshooting

Common Issues

• All pytest tests are not passing

API Key Issues

Error: Invalid API key

Solution: Set your API key using:

pyoc config --set api_key=sk-your-api-key

Or set it as an environment variable:

export OCO_API_KEY=sk-your-api-key

Git Repository Issues

Error: Not a git repository

Solution: Make sure you're in a valid git repository. Run:

git init

No Staged Changes

Error: No staged changes to commit

Solution: Stage your changes before generating a commit message:

git add <files>

Or use the --stage-all option:

pyoc commit --stage-all

Large Diffs

Error: Diff too large for token limit

Solution: Commit changes in smaller batches or use a model with a larger context window:

pyoc config --set model=gpt-4-turbo

Configuration Errors

Error: Cannot read configuration file

Solution: Reinitialize the configuration:

pyoc config --init

Debugging

For advanced debugging, set the debug environment variable:

OCO_DEBUG=1 pyoc commit

This will provide verbose output to help troubleshoot issues.

Getting Help

If you encounter issues not covered here, please:

1. Check the GitHub issues
2. Run commands with verbose logging as shown above
3. Report issues on GitHub with the full debug output

Notice

This repository was meant to be a python alternative to https://github.com/di-sukharev/opencommit We have tried to emulate its functionality from typescript to python. We have kept most of the original *.ts files for reference and for development if new features are added. Why did I port this? I wanted a full python dependency chain for my application, not requiring node kept a slim docker runtime container.

Roadmap

• Remove older *.ts file references if they are not yet implelmented.
• Impelement most of the other core functionality of original opencommit.
• Commit command seems to work
• Have not fully tested config command
• Have not fully tested githook command