🤖 commity

|

Generate intelligent Git commit messages with AI. Supports Conventional Commits, emoji, and multiple LLM providers like OpenAI, Ollama, and Gemini.

🤔 What is Commity?

Commity is an open-source, AI-powered Git commit message generation tool. It analyzes your staged code changes and automatically generates commit messages that follow the Conventional Commits specification, and can even add emojis for you!

With a simple commity --emoji command, you can get a professional and clear commit message like this:

feat(api): ✨ add user authentication endpoint

🔧 Installation

Install with pip:

pip install commity

Or install with uv:

uv tool install commity

⚙️ Configuration

commity supports three configuration methods, with the following priority: Command-line Arguments > Environment Variables > Configuration File.

Supported model providers are: Gemini (default), Ollama, OpenAI, OpenRouter, NVIDIA.

Gemini, OpenAI, OpenRouter, and NVIDIA always require an API key. Commity aborts early if those keys are missing so you get fast feedback before hitting the network.

Model repository tools are disabled by default. Set ALLOW_TOOLS to true to let a tool-capable provider inspect staged changes, commit history, and tracked files. If ALLOWED_TOOLS is omitted, every built-in read-only tool is available. Valid names are get_staged_summary, get_staged_diff, list_recent_commits, get_commit, and read_file.

✨ Method 1: Specify Model Parameters via Command-line

OpenAI

commity --provider openai --model gpt-3.5-turbo --api_key <your-api-key>

Ollama

commity --provider ollama --model llama2 --base_url http://localhost:11434

Gemini

commity --provider gemini --model gemini-2.5-flash --base_url https://generativelanguage.googleapis.com --api_key <your-api-key> --timeout 30

or

commity \
--provider gemini \
--model gemini-2.5-flash \
--base_url https://generativelanguage.googleapis.com \
--api_key <your-api-key> \
--timeout 30 \

OpenRouter

commity --provider openrouter --model openai/gpt-3.5-turbo --api_key <your-openrouter-api-key>

or

commity \
--provider openrouter \
--model anthropic/claude-3.5-sonnet \
--api_key <your-openrouter-api-key> \

NVIDIA

commity --provider nvidia --model nvidia/llama-3.1-70b-instruct --api_key <your-nvidia-api-key>

or

commity \
--provider nvidia \
--model nvidia/llama-3.1-nemotron-70b-instruct \
--api_key <your-nvidia-api-key> \

🌱 Method 2: Set Environment Variables as Defaults

You can add the following to your .bashrc, .zshrc, or .env file:

export COMMITY_ALLOW_TOOLS=true
export COMMITY_ALLOWED_TOOLS=get_staged_diff,read_file

For GLM-4.5+ models through BigModel's OpenAI-compatible API, thinking can be disabled for short structured tasks:

commity --disable-thinking
# Or set COMMITY_DISABLE_THINKING=true / "DISABLE_THINKING": true.

Commity rejects this option for other providers and models because thinking controls are not portable across LLM APIs.

OpenAI

export COMMITY_PROVIDER=openai
export COMMITY_MODEL=gpt-3.5-turbo
export COMMITY_API_KEY=your-api-key

Ollama

export COMMITY_PROVIDER=ollama
export COMMITY_MODEL=llama2
export COMMITY_BASE_URL=http://localhost:11434

Gemini

export COMMITY_PROVIDER=gemini
export COMMITY_MODEL=gemini-2.5-flash
export COMMITY_BASE_URL=https://generativelanguage.googleapis.com
export COMMITY_API_KEY=your-api-key
export COMMITY_TEMPERATURE=0.5

OpenRouter

export COMMITY_PROVIDER=openrouter
export COMMITY_MODEL=openai/gpt-3.5-turbo
export COMMITY_API_KEY=your-openrouter-api-key
export COMMITY_TEMPERATURE=0.5

NVIDIA

export COMMITY_PROVIDER=nvidia
export COMMITY_MODEL=nvidia/llama-3.1-70b-instruct
export COMMITY_API_KEY=your-nvidia-api-key
export COMMITY_TEMPERATURE=0.5

📝 Method 3: Use a Configuration File (Recommended)

For easier configuration management, create either ~/.commity/config.jsonc or ~/.commity/config.json in your user's home directory. JSONC supports line comments, block comments, and trailing commas. If both files exist, config.jsonc takes priority.

1. Create the directory:

   mkdir -p ~/.commity

2. Create and edit the config.jsonc file:

   touch ~/.commity/config.jsonc

3. Add your configuration to config.jsonc, for example:

   {
     "PROVIDER": "ollama",
     "MODEL": "llama3",

1 "BASE_URL": "http://localhost:11434", "MAX_ATTEMPTS": 3 }

Or using Gemini:

```json
{
  "PROVIDER": "gemini",
  "MODEL": "gemini-1.5-flash",
  "BASE_URL": "https://generativelanguage.googleapis.com",
  "API_KEY": "your-gemini-api-key"
}

Or using OpenAI:

{
  "PROVIDER": "openai",
  "MODEL": "gpt-3.5-turbo",
  "API_KEY": "your-openai-api-key",
  "ALLOW_TOOLS": true,
  "ALLOWED_TOOLS": ["get_staged_diff", "read_file"]
}

Or using OpenRouter:

{
  "PROVIDER": "openrouter",
  "MODEL": "openai/gpt-3.5-turbo",
  "API_KEY": "your-openrouter-api-key"
}

Or using NVIDIA:

{
  "PROVIDER": "nvidia",
  "MODEL": "nvidia/llama-3.1-70b-instruct",
  "API_KEY": "your-nvidia-api-key"
}

🚀 Usage

# Run
commity

# View help
commity --help

# Use Chinese (--lang is kept as an alias)
commity --language zh

# Include emojis
commity --emoji

# Override the model context window for smaller local models
commity --context_window_tokens 8192

# Show token budgeting, compression, and change-group diagnostics
commity --debug

# Allow all read-only repository tools (OpenAI provider)
commity --provider openai --api_key <your-api-key> --allow_tools

# Allow only selected repository tools
commity --provider openai --api_key <your-api-key> \
  --allow_tools --allowed_tools get_staged_diff read_file

# Use OpenRouter with specific model
commity --provider openrouter --model anthropic/claude-3.5-sonnet --api_key <your-openrouter-api-key>

# Use OpenRouter with emoji support
commity --provider openrouter --model openai/gpt-4o --api_key <your-openrouter-api-key> --emoji

# Use NVIDIA with specific model
commity --provider nvidia --model nvidia/llama-3.1-70b-instruct --api_key <your-nvidia-api-key>

# Use NVIDIA with emoji support
commity --provider nvidia --model nvidia/llama-3.1-nemotron-70b-instruct --api_key <your-nvidia-api-key> --emoji

# Skip interactive confirmation and commit immediately
commity --confirm n

# Generate, commit, and push without interactive confirmation
commity -y

# Run via Python module entry point
python -m commity --language zh --emoji

In interactive mode, choose c to commit, e to edit the generated message in your Git editor, r to regenerate it with optional guidance, or n to cancel. Commity uses only the staged diff and staged-file metadata to generate the message. When code, build, CI, and documentation changes appear independently, Commity warns before generating one combined message.