Git Commit AI

Intelligent commit messages powered by AI

Quick Install · Usage · Documentation · Report Bug

Git Commit AI analyzes your staged changes and generates meaningful, conventional commit messages using AI. Works seamlessly with your existing git workflow - just use git commitai instead of git commit.

🚀 Quick Install

Linux/macOS/WSL

Run this single command to install and set up everything:

curl -sSL https://raw.githubusercontent.com/semperai/git-commitai/master/install.sh | bash

Windows

Run in PowerShell:

# Download and run the installer
irm https://raw.githubusercontent.com/semperai/git-commitai/master/install.ps1 | iex

# Or download first, then run
Invoke-WebRequest -Uri https://raw.githubusercontent.com/semperai/git-commitai/master/install.ps1 -OutFile install.ps1
.\install.ps1

The installer will:

✅ Download and install git-commitai
✅ Set up the git commitai command
✅ Install the man page for git commitai --help (Unix/Linux)
✅ Guide you through API configuration
✅ Add to your PATH automatically

Alternative Installation Methods

Manual installation from Git

# Clone the repository
git clone https://github.com/semperai/git-commitai.git
cd git-commitai

# Make the script executable
chmod +x git_commitai.py

# Option 1: Copy to your PATH
sudo cp git_commitai.py /usr/local/bin/git-commitai
# Or for user installation:
mkdir -p ~/.local/bin
cp git_commitai.py ~/.local/bin/git-commitai

# Option 2: Set up git alias directly
git config --global alias.commitai '!python3 '"$(pwd)"'/git_commitai.py'


sudo cp git-commitai.1 /usr/local/share/man/man1/
sudo mandb  # Update man database on Linux

# Set up environment variables (add to ~/.bashrc or ~/.zshrc)
export GIT_COMMIT_AI_KEY="your-api-key"
export GIT_COMMIT_AI_URL="https://openrouter.ai/api/v1/chat/completions"
export GIT_COMMIT_AI_MODEL="qwen/qwen3-coder"

Development installation

# Clone and set up for development
git clone https://github.com/semperai/git-commitai.git
cd git-commitai

# Create virtual environment (optional but recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements.txt

# Run tests
pytest

# Create git alias pointing to your dev version
git config --global alias.commitai '!python3 '"$(pwd)"'/git_commitai.py'

⚙️ Configuration

After installation, the script will guide you through setting up your API credentials. You can also configure manually:

# Example with OpenRouter (recommended)
export GIT_COMMIT_AI_KEY="sk-or-v1-..."
export GIT_COMMIT_AI_URL="https://openrouter.ai/api/v1/chat/completions"
export GIT_COMMIT_AI_MODEL="qwen/qwen3-coder"

Add these to your ~/.bashrc or ~/.zshrc to make them permanent.

You can also override these settings per-command using CLI flags:

# Use a different model for a specific commit
git commitai --model "gpt-4o" --api-key "sk-..."

# Test with a local LLM
git commitai --api-url "http://localhost:11434/v1/chat/completions" --model "qwen2.5-coder:7b"

Running with Local LLMs (Ollama)

For enhanced privacy and offline usage, you can run Git Commit AI with local LLMs using Ollama:

Setting up Ollama

1. Install Ollama

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.ai/install.sh | sh

# Windows
# Download from https://ollama.ai/download

2. Start Ollama service

# Start Ollama (if not already running)
ollama serve

# Pull a code-optimized model
ollama pull qwen2.5-coder:7b

# Verify the model is downloaded
ollama list

3. Configure Git Commit AI for Ollama

# Set environment variables for Ollama
export GIT_COMMIT_AI_URL="http://localhost:11434/v1/chat/completions"
export GIT_COMMIT_AI_MODEL="qwen2.5-coder:7b"
export GIT_COMMIT_AI_KEY="not-needed"

# Add to ~/.bashrc or ~/.zshrc to make permanent

4. Test the setup

# Make a test commit
git add .
git commitai --debug  # Use debug to see the API calls

# Or use per-command overrides without setting env vars
git commitai --api-url "http://localhost:11434/v1/chat/completions" \
             --model "qwen2.5-coder:7b" \
             --api-key "not-needed"

Troubleshooting

Connection refused: Make sure Ollama is running (ollama serve)
Model not found: Pull the model first (ollama pull qwen2.5-coder:7b)
Slow generation: Try a smaller model like llama3.2:3b or upgrade your hardware
Out of memory: Use a smaller model or increase Ollama's memory limit

Performance Tips

Models with "instruct" or "chat" variants typically work better for commit messages
Code-specific models like qwen2.5-coder understand diffs better
Run ollama serve in the background or as a service for convenience
For faster responses on limited hardware, consider qwen2.5-coder:3b

Commit Message Templates (.gitmessage)

Git Commit AI automatically reads and uses your .gitmessage template files to understand your project's commit conventions. This helps generate messages that match your team's style guide.

The tool looks for templates in this precedence order (first found wins):

Repository template: .gitmessage in your repository root
Git config template: Set via git config commit.template
Global template: ~/.gitmessage in your home directory

Note: Repository-specific .gitmessage files take precedence over configured templates. This ensures teams can enforce project-specific conventions by including a .gitmessage file in their repository, regardless of individual developer configurations.

Setting Up a Template

Create a .gitmessage file with your project's commit guidelines:

# Create a repository-specific template
cat > .gitmessage << 'EOF'
# Format: <type>(<scope>): <subject>
#
# <type> must be one of:
#   feat: A new feature
#   fix: A bug fix
#   docs: Documentation changes
#   style: Code style changes (formatting, semicolons, etc)
#   refactor: Code refactoring without adding features or fixing bugs
#   test: Adding or updating tests
#   chore: Maintenance tasks, dependency updates, etc
#
# <scope> is optional and indicates the module affected
#
# Example: feat(auth): Add OAuth2 login support
#
# The body should explain the motivation for the change
EOF

# Or configure a template via git config
git config --global commit.template ~/.gitmessage
git config commit.template .github/commit-template  # Repository-specific config

# Or use a global fallback template
cp .gitmessage ~/.gitmessage

When a template is found, Git Commit AI uses it as additional context to generate messages that follow your conventions while still adhering to Git best practices.

Template Precedence Example

If you have:

.gitmessage in your repository root
A template configured via git config commit.template
~/.gitmessage in your home directory

Git Commit AI will use the .gitmessage from your repository root, ignoring the others. This ensures project-specific conventions always take precedence.

Custom AI Prompts (.gitcommitai)

You can customize the AI prompt used for generating commit messages by creating a .gitcommitai file in your repository root.

Basic Configuration

The .gitcommitai file can optionally start with a model specification, followed by your custom prompt template:

# Create a .gitcommitai file with custom prompt
cat > .gitcommitai << 'EOF'
model: gpt-4

You are a commit message generator for our project.
Use conventional commits format.

Context: {CONTEXT}
Changes: {DIFF}
Files: {FILES}

Generate the commit message:
EOF

Available Placeholders

Your custom prompt template can use these placeholders:

{CONTEXT} - User-provided context via -m flag
{DIFF} - The git diff of changes
{FILES} - The modified files with their content
{GITMESSAGE} - Content from .gitmessage template if exists

Configuration Precedence

For model selection, the precedence is:

CLI flag (--model)
Environment variable (GIT_COMMIT_AI_MODEL)
.gitcommitai file model specification
Default (qwen/qwen3-coder)

📖 Usage

# Basic usage - just like git commit!
git add .
git commitai

# With context for better messages
git commitai -m "Refactored auth system for JWT"

# Auto-stage tracked files
git commitai -a

# Preview without committing
git commitai --dry-run

# Override API settings for this commit
git commitai --model "claude-3.5-sonnet" --api-key "sk-ant-..."

# Debug mode for troubleshooting
git commitai --debug

# See all options
git commitai --help

📚 Documentation

Get Help

man git-commitai

Git Commit AI Specific Commands

These commands are unique to git commitai and not found in standard git commit:

Flag	Description	Purpose
`-m, --message <context>`	Provide context for AI	Modified behavior: Unlike `git commit` where this sets the entire message, in `git commitai` this provides context to help the AI understand your intent
`--debug`	Enable debug logging	Outputs debug information to stderr for troubleshooting. Shows git commands, API requests, and decision points
`--api-key <key>`	Override API key	Temporarily use a different API key for this commit only. Overrides `GIT_COMMIT_AI_KEY` environment variable
`--api-url <url>`	Override API endpoint	Use a different API endpoint for this commit. Useful for testing different providers or local models
`--model <name>`	Override model name	Use a different AI model for this commit. Overrides `GIT_COMMIT_AI_MODEL` environment variable

Standard Git Commit Commands Support

The following table shows all standard git commit flags and their support status in git commitai:

Flag	Description	Status
`-a, --all`	Auto-stage all tracked modified files	✅ Supported
`--interactive`	Interactively add files	❌ Not supported
`-p, --patch`	Interactively add hunks of patch	❌ Not supported
`-C <commit>, --reuse-message=<commit>`	Reuse message from specified commit	❌ Not supported
`-c <commit>, --reedit-message=<commit>`	Reuse and edit message from specified commit	❌ Not supported
`--fixup=[(amend\|reword):]<commit>`	Construct commit for autosquash rebase	❌ Not supported
`--squash=<commit>`	Construct commit for squashing	❌ Not supported
`--reset-author`	Reset author information	❌ Not supported
`--short`	Show short-format status (dry-run)	❌ Not supported
`--branch`	Show branch info in short-format	❌ Not supported
`--porcelain`	Machine-readable output (dry-run)	❌ Not supported
`--long`	Show long-format status (dry-run)	❌ Not supported
`-z, --null`	Terminate entries with NUL	❌ Not supported
`-F <file>, --file=<file>`	Read commit message from file	❌ Not supported
`--author=<author>`	Override author information	✅ Supported
`--date=<date>`	Override author date	✅ Supported
`-m <msg>, --message=<msg>`	Commit message	⚠️ Modified (provides context to AI)
`-t <file>, --template=<file>`	Use template file for message	❌ Not supported
`-s, --signoff, --no-signoff`	Add Signed-off-by trailer	❌ Not supported
`--trailer <token>[(=\|:)<value>]`	Add custom trailers to message	❌ Not supported
`-n, --no-verify`	Skip pre-commit and commit-msg hooks	✅ Supported
`--allow-empty`	Allow empty commits	✅ Supported
`--allow-empty-message`	Allow commits with empty message	❌ Not supported
`--cleanup=<mode>`	Set commit message cleanup mode	❌ Not supported
`-e, --edit`	Force edit of commit message	❌ Not supported
`--no-edit`	Use message without editing	❌ Not supported
`--amend`	Amend the previous commit	✅ Supported
`--no-post-rewrite`	Bypass post-rewrite hook	❌ Not supported
`-i, --include`	Stage specified files in addition to staged	❌ Not supported
`-o, --only`	Commit only specified files	❌ Not supported
`--pathspec-from-file=<file>`	Read pathspec from file	❌ Not supported
`--pathspec-file-nul`	NUL-separated pathspec file	❌ Not supported
`-u[<mode>], --untracked-files[=<mode>]`	Show untracked files	❌ Not supported
`-v, --verbose`	Show diff in commit message editor	✅ Supported
`-q, --quiet`	Suppress commit summary message	❌ Not supported
`--dry-run`	Don't actually commit, just show what would be committed	✅ Supported
`--status`	Include git status in commit editor	❌ Not supported
`--no-status`	Don't include git status in commit editor	❌ Not supported
`-S[<keyid>], --gpg-sign[=<keyid>]`	GPG-sign commit	❌ Not supported
`--no-gpg-sign`	Don't GPG-sign commit	❌ Not supported
`--`	Separate paths from options	❌ Not supported
`<pathspec>...`	Commit only specified paths	❌ Not supported

Legend

✅ Supported - Fully functional in git-commitai
⚠️ Modified - Works differently than standard git commit
❌ Not supported - Not yet implemented

Supported Providers

OpenRouter (Recommended) - Access to Claude, GPT-4, and many models
Local LLMs (Recommended) - Ollama, LM Studio
OpenAI - GPT-4, GPT-3.5
Anthropic - Claude models
Any OpenAI-compatible API

✨ Features

🤖 AI-powered commit messages - Analyzes your code changes and generates descriptive messages
📝 Drop-in replacement - Use git commitai just like git commit with the same flags
🔧 Provider agnostic - Works with OpenAI, Anthropic, local LLMs, or any compatible API
📖 Full documentation - Comprehensive man page with git commitai --help
⚡ Smart context - Understands both diffs and full file contents
🎯 Git native - Respects your git editor, hooks, and workflow
🐛 Debug mode - Built-in debugging for troubleshooting issues
🔄 CLI overrides - Override API settings per-command for testing and flexibility
📋 Template support - Automatically uses your .gitmessage templates for project-specific conventions
🎨 Custom prompts - Customize AI behavior with .gitcommitai configuration

🧪 Examples

# Stage changes and generate commit message
git add src/
git commitai

# Preview what would be committed without actually committing
git commitai --dry-run

# Quick fix with auto-staging
vim buggy-file.js
git commitai -a -m "Fixed null pointer exception"

# Work in progress (skip hooks)
git commitai -a -n -m "WIP: implementing feature"

# Amend last commit with better message
git commitai --amend

# Trigger CI/CD with empty commit
git commitai --allow-empty -m "Trigger deployment"

# Review changes while committing
git commitai -v

# Override author information
git commitai --author "John Doe <john@example.com>"

# Override commit date
git commitai --date "2024-01-01 12:00:00"

# Test with a different model
git commitai --model "gpt-4o" --api-key "sk-..."

# Use local LLM for sensitive code
git commitai --api-url "http://localhost:11434/v1/chat/completions" --model "codellama"

# Preview with dry-run and debug
git commitai --dry-run --debug 2>&1 | tee preview.log

# Debug mode for troubleshooting (outputs to stderr)
git commitai --debug 2> debug.log
git commitai --debug -a -m "Testing auto-stage" 2>&1 | tee debug.log

# Combine CLI overrides with debug
git commitai --debug --model "claude-3.5-sonnet" --api-key "sk-ant-..."

Using with .gitmessage Templates

# Create a project-specific template
cat > .gitmessage << 'EOF'
# Type: feat|fix|docs|style|refactor|test|chore
# Scope: (optional) affected module
#
# Remember: Use imperative mood in the subject line
EOF

# Git Commit AI will automatically detect and use this template
git add .
git commitai

# The AI will generate messages following your template format
# Example output: "feat(auth): Add JWT token validation"

# Note: This .gitmessage in your repo will override any configured templates
# or global ~/.gitmessage, ensuring team conventions are followed

🐛 Debugging

If you encounter issues, use the --debug flag to enable detailed logging to stderr:

# Enable debug mode (outputs to stderr)
git commitai --debug

# Capture debug output to a file
git commitai --debug 2> debug.log

# View debug output on screen and save to file
git commitai --debug 2>&1 | tee debug.log

# Debug with other flags
git commitai --debug -a -v 2> debug.log

# Debug with API overrides
git commitai --debug --model "gpt-4" --api-url "https://api.openai.com/v1/chat/completions" 2> debug.log

The debug output includes:

All git commands executed
API request/response details
File processing information
Configuration and environment details (including CLI overrides)
Template file detection and loading (shows which template was chosen and why)
Error messages and stack traces

When reporting bugs, please include relevant portions of the debug output.

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

# Clone the repository
git clone https://github.com/semperai/git-commitai.git
cd git-commitai
python3 -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`
pip install -r requirements.txt
pytest
./install.sh

📄 License

MIT License - see LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 172 Commits
.github		.github
tests		tests
.coveragerc		.coveragerc
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
git-commitai.1		git-commitai.1
git_commitai.py		git_commitai.py
install.ps1		install.ps1
install.sh		install.sh
logo.webp		logo.webp
mypy.ini		mypy.ini
pytest.ini		pytest.ini
requirements.txt		requirements.txt

License

semperai/git-commitai

Folders and files

Latest commit

History

Repository files navigation

Git Commit AI

Git Commit AI

🚀 Quick Install

Linux/macOS/WSL

Windows

Alternative Installation Methods

⚙️ Configuration

Running with Local LLMs (Ollama)

1. Install Ollama

2. Start Ollama service

3. Configure Git Commit AI for Ollama

4. Test the setup

Troubleshooting

Performance Tips

Commit Message Templates (.gitmessage)

Setting Up a Template

Template Precedence Example

Custom AI Prompts (.gitcommitai)

Basic Configuration

Available Placeholders

Configuration Precedence

📖 Usage

📚 Documentation

Get Help

Git Commit AI Specific Commands

Standard Git Commit Commands Support

Legend

Supported Providers

✨ Features

🧪 Examples

Using with .gitmessage Templates

🐛 Debugging

🤝 Contributing

📄 License

🌟 Star History

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

Packages