AI-driven CLI tool that generates optimal, context-aware commit messages, streamlining your version control process with precision and efficiency
Explore the docs »

Report Bug · Request Feature

• Commitron
  • Features
  • Example output
  • Installation
  • Using Homebrew (macOS)
  • Manual Installation
  • Docker Setup
  • Usage
  • Configuration
  • API Keys
  • License
    • Built With
  • Getting Started
    • Prerequisites
    • Installation
  • Usage
  • Roadmap
  • Contributing
  • License
  • Contact
  • Acknowledgements

Commitron is a CLI tool that generates AI-powered commit messages based on your staged changes in a git repository.

• 🤖 Uses AI to generate meaningful commit messages
• 🔍 Analyzes your staged changes to understand what has been modified
• 🧩 Supports multiple AI providers:
  • OpenAI (ChatGPT)
  • Google Gemini
  • Ollama (local inference)
  • Anthropic Claude
  • Custom web APIs (Open WebUI, local GPT instances, etc.)
• 📝 Supports various commit message conventions:
  • No convention (plain text)
  • Conventional Commits
  • Custom templates
• ⚙️ Customizable settings via configuration file

When you run commitron after staging some changes, you'll see output similar to this:

Generated Commit Message:
------------------------
feat(git): add support for detecting staged files and creating commits

Implement Git integration for detecting staged files and generating
commit messages based on the changes. This adds functionality to check
if the current directory is a Git repository, retrieve a list of staged
files, and create commits with AI-generated messages.
------------------------

Do you want to use this commit message? (y/n):

If you type y, the commit will be created using the generated message.

# Add the tap directly from the commitron repository
brew tap stiliajohny/commitron https://github.com/stiliajohny/commitron.git

# Then install commitron
brew install commitron

# Clone the repository
git clone https://github.com/johnstilia/commitron.git

# Navigate to the directory
cd commitron

# Build and install
go install ./cmd/commitron

For a complete local AI environment with Ollama and Open WebUI:

# Quick setup (recommended)
make docker-setup

# Pull a model
make docker-pull-model MODEL=mistral:latest

# Configure commitron to use Open WebUI
# Edit ~/.commitronrc and set:
# provider: custom
# api_endpoint: http://localhost:3000/v1/chat/completions

Available Docker commands:

• make docker-setup - Complete setup (env file + start services)
• make docker-up - Start services only
• make docker-down - Stop services
• make docker-pull-model MODEL=name - Pull a model
• make docker-list-models - List available models
• make docker-status - Show service status
• make docker-logs - Show all logs
• make docker-clean - Stop and remove all data

See DOCKER_SETUP.md for detailed instructions.

# Stage your changes
git add .

# Run commitron to generate a commit message
commitron

# Use with a custom config file
commitron --config /path/to/custom/config.yaml
# or using shorthand flags
commitron -c /path/to/custom/config.yaml

# Available commands
commitron generate            # Generate a commit message (default command)
commitron init                # Initialize a new configuration file
commitron version             # Show version information

# Command options
commitron generate --dry-run                  # Preview without committing
commitron generate -d                         # Shorthand for --dry-run
commitron generate -c /path/to/config         # Use custom config (shorthand)
commitron init --force                        # Overwrite existing config
commitron init -f                             # Shorthand for --force
commitron init -c /path/to/config             # Initialize at custom location (shorthand)

# Get help for any command
commitron --help
commitron [command] --help

Commitron looks for a configuration file at ~/.commitronrc. This is a YAML file that allows you to customize how the tool works.

Example configuration:

# AI provider configuration
ai:
  provider: openai
  api_key: your-api-key-here
  model: gpt-3.5-turbo

# Commit message configuration
commit:
  convention: conventional
  include_body: true
  max_length: 72

# Context settings for AI
context:
  include_file_names: true
  include_diff: true
  max_context_length: 4000

See example.commitronrc for a complete example with all available options.

To use Commitron, you'll need API keys for your chosen AI provider:

• OpenAI: https://platform.openai.com/api-keys
• Google Gemini: https://aistudio.google.com/app/apikey
• Anthropic Claude: https://console.anthropic.com/keys

For Ollama, you need to have it running locally. See Ollama documentation for more information.

For custom web APIs (like Open WebUI), you need to configure the api_endpoint URL in your configuration. The custom provider expects an OpenAI-compatible API endpoint that accepts chat completions requests.

For a complete local setup with Ollama and Open WebUI, see DOCKER_SETUP.md for detailed instructions.

The custom provider allows you to use any OpenAI-compatible API endpoint, such as:

• Open WebUI: A web interface for Ollama models
• Local API servers: Your own GPT API implementations
• Third-party API services: Any service with OpenAI-compatible endpoints

ai:
  provider: custom
  api_endpoint: http://localhost:8080/v1/chat/completions
  model: mistral:latest  # The model name as configured in Open WebUI
  api_key: ""  # Usually not required for local instances
  temperature: 0.7

ai:
  provider: custom
  api_endpoint: http://localhost:8000/v1/chat/completions
  model: gpt-3.5-turbo
  api_key: your-api-key-if-required
  temperature: 0.7

The custom provider expects the API endpoint to accept POST requests with a JSON payload in the OpenAI chat completions format and return responses in the same format.

See LICENSE.txt for details.

See the open issues for a list of proposed features (and known issues).

When you create a new release, the Homebrew formula is automatically updated via GitHub Actions. However, you can also update it manually:

1. Create a new release on GitHub with a tag (e.g., v0.2.0)
2. The GitHub Action will automatically:
   • Download the release tarball
   • Calculate the SHA256 checksum
   • Update the Homebrew formula
   • Commit and push the changes

If you need to update the formula manually, use the provided script:

# Make the script executable (first time only)
chmod +x scripts/update-homebrew-formula.sh

# Update formula for a new version
./scripts/update-homebrew-formula.sh v0.2.0

# Review changes and commit
git add Formula/commitron.rb
git commit -m "feat: update Homebrew formula for v0.2.0"
git push origin master

• URL: Points to the new release tarball
• SHA256: Updated checksum for the new release
• Comment: Updated to reflect the new version

After updating, users can install the new version with:

brew tap stiliajohny/commitron https://github.com/stiliajohny/commitron.git
brew install commitron

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Distributed under the GPLv3 License. See LICENSE for more information.

John Stilia - stilia.johny@gmail.com

• GitHub Emoji Cheat Sheet
• Img Shields
• Choose an Open Source License
• GitHub Pages