Commit GPT

A CLI that writes your git commit messages for you with AI. Never write a commit message again.

Installation

Method 1: Homebrew (Recommended)

The easiest way to install and keep CommitGPT updated.

Install:

brew tap ZPVIP/commitgpt https://github.com/ZPVIP/commitgpt
brew trust zpvip/commitgpt
brew install commitgpt

Note: Recent Homebrew versions refuse to load formulae from third-party taps until you trust them, so brew trust is required before installing.

Upgrade:

brew update
brew upgrade commitgpt

Uninstall:

brew uninstall commitgpt
# Optional: Remove configuration files manually
rm -rf ~/.config/commitgpt

Method 2: RubyGems (For Ruby Developers)

Click to expand RubyGems installation instructions

Prerequisites: Install Ruby

If you don't have Ruby installed, follow these steps first.

macOS

1. Install Homebrew (skip if already installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. Install Ruby dependencies

brew install openssl@3 libyaml gmp rust
Ubuntu / Debian

Install Ruby dependencies

sudo apt-get update
sudo apt install build-essential rustc libssl-dev libyaml-dev zlib1g-dev libgmp-dev

Install Ruby with Mise (version manager)

# Install Mise
curl https://mise.run | sh

# For zsh (macOS default)
echo 'eval "$(~/.local/bin/mise activate)"' >> ~/.zshrc
source ~/.zshrc

# For bash (Ubuntu default)
# echo 'eval "$(~/.local/bin/mise activate)"' >> ~/.bashrc
# source ~/.bashrc

# Install Ruby
mise use --global ruby@3

# Verify installation
ruby --version
#=> 3.4.7

# Update RubyGems
gem update --system

Install CommitGPT

gem install commitgpt

Configuration

CommitGPT uses a YAML configuration system (~/.config/commitgpt/) to support multiple providers and per-provider settings.

Interactive Setup (Recommended)

Run the setup wizard to configure your provider:

$ aicm setup

You'll be guided to:

  1. Set the model list fetch timeout in seconds (defaults to 30; raise it if a provider is slow to respond)
  2. Choose an AI provider (Presets: Cerebras, OpenAI, Ollama, Groq, etc.)
  3. Enter your API Key (stored securely in config.local.yml)
  4. Select a model interactively
  5. Set maximum diff length

The timeout is saved as a top-level model_fetch_timeout key in config.yml and applies to every provider, including aicm -p and aicm -m. You can also edit it there directly.

Note: Please add ~/.config/commitgpt/config.local.yml to your .gitignore if you are syncing your home directory, as it contains your API keys.

Usage

Generate Commit Message

Stage your changes and run aicm:

$ git add .
$ aicm

Switch Provider

Switch between configured providers easily:

$ aicm -p
# or
$ aicm --provider

Select Model

Interactively list and select a model for your current provider:

$ aicm -m
# or
$ aicm --models

Choose Commit Message Format

Select your preferred commit message format:

$ aicm -f
# or
$ aicm --format

CommitGPT supports three commit message formats:

  • Simple - Concise commit message (default)
  • Conventional - Follow Conventional Commits specification
  • Gitmoji - Use Gitmoji emoji standard

Your selection will be saved in ~/.config/commitgpt/config.yml and used for all future commits until changed.

Format Examples

Simple:

Add user authentication feature

Conventional:

feat: add user authentication feature
fix: resolve login timeout issue
docs: update API documentation

Gitmoji:

✨ add user authentication feature
🐛 resolve  timeout issue
📝 update API documentation

Choose Commit Message Detail Level

Select how much the commit message says:

$ aicm -d
# or
$ aicm --detail
  • Concise - Subject line only (default)
  • Detailed - Subject line, an explanatory paragraph, and a bullet list of notable changes

This is independent of the format above: the format decides how the subject line is written, the detail level decides how much follows it. Your selection is saved as commit_detail in ~/.config/commitgpt/config.yml.

Detail Examples

Concise:

feat(dfb): store and expand DFB event and speed logs

Detailed:

feat(dfb): store and expand DFB event and speed logs

Persist DFB device logs ingested from the proactive `evt` (event log) and
`lge` (speed stats) topics, one record per message.

- Add `dfb_event_logs` and `dfb_speed_stats` tables and models, each with an
  idempotent unique index so re-delivery and overlapping backfills are safe.
- Associate both log tables on `Product`.
- Update `README_DFB.md` to document the cloud tables.

Check Configuration

View your current configuration (Provider, Model, Format, Detail, Base URL, Diff Len):

$ aicm help

(Use the help command to see current active provider settings)

View Git Diff

Preview the diff that will be sent to the AI:

$ aicm -v

Update

To update to the latest version (if installed via Gem):

$ gem update commitgpt

Supported Providers

We support any OpenAI-compatible API. Presets available for:

  • Cerebras (Fast & Recommended)
  • OpenAI (Official)
  • Ollama (Local)
  • Groq
  • DeepSeek
  • Anthropic (Claude)
  • Google AI (Gemini)
  • Mistral
  • OpenRouter
  • AMD Radeon (China)
  • Local setups (Apple via apple-to-openai, LM Studio, LLaMa.cpp, Llamafile)

OpenAI (https://platform.openai.com)

gpt-4o
gpt-4o-mini

Apple Local Models (via apple-to-openai) ⭐ Recommended, Free, fast, privacy-focused

apple-intelligence  # Max Context Length: 4,096 tokens

Note: Due to the context window limits of Apple's local models, it is highly recommended to set your max diff length (diff_len) to 10000 during setup. When prompted for large diffs, select the Smart chunked mode to avoid context window overflow.

Cerebras (https://cloud.cerebras.ai)

llama3.1-8b          # Max Context Length:  8,192 tokens
gpt-oss-120b         # Max Context Length: 65,536 tokens

Groq (https://console.groq.com)

llama-3.3-70b-versatile
llama-3.1-8b-instant

AMD Radeon (China) — free OpenAI-compatible API

Get an API key at https://developer.amd.com.cn/radeon/tokenfactory

Note: Registration requires both an email address and a Chinese (+86) mobile phone number. Without a Chinese phone number you cannot complete sign-up, so this provider is only usable if you have one.

Note: The gateway in front of this endpoint always answers GET /models with 403, so models cannot be discovered automatically. CommitGPT ships the list below and offers it directly during setup — no detection request is made for this provider.

DeepSeek-V4-Flash    # Max Context Length: 1,000,000 tokens
Qwen3.6-35B-A3B      # Max Context Length:   262,144 tokens
MiniCPM-V46          # Max Context Length:   262,144 tokens
MiniCPM5-1B          # Max Context Length:   131,072 tokens

Setup reports the selected model's context window and suggests a matching diff_len, so you don't have to work the number out yourself.

How It Works

This CLI tool runs a git diff command to grab all staged changes, sends this to OpenAI's GPT API (or compatible endpoint), and returns an AI-generated commit message. The tool uses the /v1/chat/completions endpoint with optimized prompts/system instructions for generating conventional commit messages.

Special Thanks

I used ChatGPT to convert AICommits from TypeScript to Ruby. Special thanks to https://github.com/Nutlope/aicommits

Development Guide

Requirements

  • Ruby >= 2.6.0
  • Git

Local Setup

  1. Clone the repository: 
    git clone https://github.com/ZPVIP/commitgpt.git
cd commitgpt
  2. Install dependencies: 
    bundle install

Local Build and Install

To test your changes locally (builds the gem and installs it to your system):

gem build commitgpt.gemspec
gem install ./commitgpt-*.gem

Publishing

RubyGems

To publish a new version to RubyGems.org (requires RubyGems account permissions):

gem push commitgpt-*.gem

Homebrew (GitHub Distribution)

We use a custom script to automate the GitHub Release and Homebrew Formula update process. This enables users to install via brew tap.

Steps:

./scripts/release.sh <version>
# Example: ./scripts/release.sh 0.3.1

This script automates:

  1. Creating and pushing a Git Tag.
  2. Creating a GitHub Release (which generates the source tarball).
  3. Calculating the SHA256 checksum of the tarball.
  4. Updating Formula/commitgpt.rb with the new URL and checksum.
  5. Committing and pushing the updated Formula to the repository.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ZPVIP/commitgpt. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the CommitGpt project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.