🚀 gcommit

Stop wasting time writing commit messages. Let AI do it for you.

gcommit is an AI-powered CLI tool that analyzes your staged changes and generates perfect commit messages in seconds. No more staring at a blank screen wondering how to describe your changes.

✨ Why You'll Love It

• ⚡ Instant commit messages - Generate professional commits in seconds
• 🎯 Conventional Commits ready - Perfect for teams following standards
• 🌍 Any language - Write commits in English, Russian, Spanish, Chinese, or any language you want
• 🎨 Customizable - Simple, conventional, or your own custom format
• 🔧 Works with any Git workflow - Local, GitHub, GitLab, Bitbucket, you name it
• 🤖 Smart context aware - Analyzes your actual code changes, not just file names
• 💰 Cheap to run - Uses efficient models like gpt-4o-mini (pennies per month)
• 🩺 Built-in diagnostics - gcommit doctor checks your setup
• 🐚 Shell completion - Tab-completion for bash, zsh, fish

🎬 Quick Start

# Install
brew tap opsdevil/tap
brew install opsdevil/tap/gcommit

# Set your OpenAI API key
export OPENAI_API_KEY='sk-your-key-here'

# Stage your changes
git add .

# Let AI write your commit!
gcommit

That's it! You'll see a proposed commit message. Type y to commit, e to edit, or n to cancel.

🎯 How It Works

1. Stage your changes with git add
2. Run gcommit
3. Review the AI-generated message
4. Commit with one keypress

Example Session

$ git add src/auth.py

$ gcommit
Analyzing changes...

Proposed commit message:
feat: add JWT authentication middleware

Implement JWT token validation for protected routes.
Add support for token refresh and blacklist checking.

[y]es / [n]o / [e]dit: y
Committed successfully ✓

🎨 Commit Message Formats

Conventional Commits (default)

Perfect for teams and open source projects.

$ gcommit
feat: add user profile page

Implement user profile with avatar upload and bio editing.
Add validation for profile fields.

Simple Format

Clean and concise, no prefixes.

$ gcommit --format simple
add user profile page with avatar upload

Custom Format

Define your own template in config file:

commit:
  format: custom
  custom_template: |
    [{type}] {subject}
    
    {body}
    
    Signed-off-by: Your Name <your@email.com>

⚙️ Configuration

Create ~/.config/gcommit/config.yaml for global settings or .gcommit.yaml in your project:

llm:
  api_key: sk-your-key-here
  model: gpt-4o-mini        # or gpt-4o for even better quality
  temperature: 0.3          # lower = more consistent
  max_tokens: 500

commit:
  language: english         # or spanish, german, etc.
  format: conventional      # conventional, simple, or custom

Priority order: --config flag → GCOMMIT_CONFIG env → Local .gcommit.yaml → XDG home config → Defaults

Configuration Override Options

• CLI flag: gcommit --config /path/to/config.yaml
• Environment variable: export GCOMMIT_CONFIG=/path/to/config.yaml
• Local config: .gcommit.yaml in project directory (searched up to git root)
• XDG home config: ~/.config/gcommit/config.yaml (auto-created on first run)

Environment Variables

export OPENAI_API_KEY='sk-your-key-here'
export OPENAI_BASE_URL='https://api.openai.com/v1'  # optional
export GCOMMIT_MODEL='gpt-4o-mini'
export GCOMMIT_LANGUAGE='english'
export GCOMMIT_FORMAT='conventional'

🎮 Usage Examples

Basic Usage

gcommit                    # Interactive mode (default)

Auto-commit (no confirmation)

gcommit --auto            # For CI/CD or when you trust the AI

Edit Before Committing

gcommit --edit            # Opens your $EDITOR to refine the message

Add Context Hint

gcommit -m "fixing memory leak in cache"
# AI will use your hint to generate better message

Quick Format Override

gcommit --format simple   # Override config for one commit

Verbose Mode (debugging)

gcommit --verbose         # See the prompt, API call details, tokens used

Different Model

gcommit --model gpt-4o    # Use more powerful model for complex changes

Custom Config File

gcommit --config /path/to/config.yaml  # Use specific config file

Check Setup

gcommit doctor            # Verify config, API key, connectivity

Shell Completion

gcommit completion --install  # Install for current shell (bash/zsh/fish)

Version

gcommit --version         # Show version

🔥 Pro Tips

1. Create an alias

echo "alias gc='gcommit'" >> ~/.zshrc
# Now just type: gc

2. Combine with git commands

git add . && gcommit --auto && git push

3. Use local config for team standards

# .gcommit.yaml in your project
commit:
  language: english
  format: conventional
  
llm:
  model: gpt-4o-mini
  temperature: 0.2  # More consistent for team projects

4. Review before pushing

gcommit              # Generate commit
git log -1 --pretty=format:"%B"  # Review last commit message
git push            # Push when satisfied

5. Use as git subcommand

gcommit registers as git-ai-commit, so you can call it directly as a git subcommand:

git ai-commit
git ai-commit --auto
git ai-commit --format simple

6. Works with OpenAI-compatible APIs

llm:
  base_url: https://your-llm-proxy.com/v1
  api_key: your-proxy-key
  model: gpt-4o-mini

🆚 Why Not Just Use AI-Powered IDEs?

Modern IDEs like Cursor, Windsurf, and Zed have built-in AI commit features. So why gcommit?

Feature	gcommit	AI IDEs (Cursor, etc.)	CLI tools (Aider)
Works over SSH	✅	❌	✅
No IDE dependency	✅	❌	✅
Custom commit formats	✅ Full control	⚠️ Limited	⚠️ Limited
Any language output	✅	⚠️ Mostly English	⚠️
Self-hosted LLMs	✅	⚠️ Some	✅
Focused on commits	✅	❌ General-purpose	❌ General-purpose

TL;DR:

• Server work? → gcommit (no GUI needed)
• Custom team standards? → gcommit (full template control)
• Already in IDE? → Use IDE feature, it's fine
• Privacy-first? → gcommit with local Ollama/vLLM

🤔 FAQ

Do I need an OpenAI API key?

Yes, but it's very affordable! Using gpt-4o-mini, you'll spend pennies even with dozens of commits per day. Get your key at https://platform.openai.com/api-keys

Can I use other LLM providers?

Yes! Set base_url in your config to any OpenAI-compatible API endpoint (Anthropic, local models via Ollama, etc.)

Will it commit automatically?

No, by default it asks for confirmation. Use --auto flag only when you trust the AI completely.

What if I don't like the generated message?

Press e to edit in your favorite editor, or n to cancel and write manually.

Does it work with pre-commit hooks?

Yes! The commit is made via standard git, so all hooks run normally.

Can I use it for multiple commits?

Absolutely! Stage the specific files you want (git add file1 file2) and run gcommit.

🤝 Contributing

Found a bug? Have a feature request? PRs and issues welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Make your changes
4. Use gcommit to commit 😉
5. Push and open a PR

🛠️ Development Setup

# Install uv (via Homebrew)
brew install uv

# Clone and setup
git clone https://github.com/OpsDevil/gcommit.git
cd gcommit
uv sync

# Run locally
uv run gcommit --help

# Run tests
uv run pytest

# Or activate venv
source .venv/bin/activate
gcommit --help

📝 License

MIT License - see LICENSE for details.

⭐ Show Your Support

If gcommit saves you time, give it a star on GitHub! It helps others discover the tool.

---

Made with ❤️ by developers who are tired of writing commit messages

Report Bug · Request Feature · Documentation