ojogu-gitai 0.1.1

AI automatic commit message

GitAI

Overview

You know how sometimes writing a good Git commit message feels like a chore, especially when you've got a bunch of small changes? This tool, GitAI, takes the pain out of it by automatically generating clear, concise commit messages for you based on your staged changes. It looks at what you've actually changed and suggests a message that truly reflects your work, so you can focus on coding.

Features

Here's what GitAI can do for you:

• Intelligent Commit Message Generation: Automatically creates relevant commit messages by analyzing your staged Git changes.
• Semantic Diff Analysis: Goes beyond raw diffs to understand the high-level meaning of your changes, identifying new functions, class updates, dependency changes, and more.
• Conventional Commits Support: Generate messages in the widely adopted Conventional Commits format (type(scope): message), helping keep your commit history clean and parseable.
• Configurable Output: Customize the commit message style, title length, and whether to include a body in the generated message.
• Breaking Change Detection: Offers hints for potential breaking changes, prompting you to review and confirm impact on public APIs.
• Flexible LLM Integration: Uses litellm to support various large language models (LLMs) for message generation, allowing you to switch providers easily.
• Interactive Workflow: Provides options to accept, reject, or retry message generation if the initial suggestion isn't quite right.
• Automatic Committing: Option to automatically commit with the generated message, streamlining your workflow.

Getting Started

Let's get you set up to use GitAI.

Installation

To use GitAI globally without interfering with your system's Python packages, use one of the following methods:

Option 1: Using uv (Recommended - Fastest)

uv is an extremely fast Python package manager that handles tool isolation automatically.

# Install GitAI as a global tool
uv tool install ojogu-gitai

# It is now available globally
gitai --help

Option 2: Using pipx (Standard for CLI Tools)

pipx installs the package into an isolated environment and automatically adds the executable to your $PATH.

# Install pipx if you haven't already
sudo apt install pipx && pipx ensurepath

# Install GitAI
pipx install ojogu-gitai

Option 3: Using pip (Legacy/Global)

If you are on an older system or inside a container where PEP 668 isn't enforced, you can use standard pip. Note: On modern Linux, this may require the --break-system-packages flag.

pip install ojogu-gitai

Option 4: Install from Source (For Development)

If you want to contribute or modify the source code:

git clone https://github.com/ojogu/gitai.git
cd gitai
pip install -e .

Requirements: Python 3.10 or newer is required.

Why Use uv or pipx?

By recommending uv or pipx, you're solving two problems for your users:

• No Manual Activation: The user doesn't need to run source venv/bin/activate. The tool just works like ls or git.
• No Dependency Hell: If GitAI requires pydantic v2 but their project uses pydantic v1, there won't be a conflict because GitAI's dependencies are hidden away in its own private folder.

Verifying Installation

After installation, you can verify GitAI is working by running:

which gitai

This will show you exactly where the isolated executable lives (usually ~/.local/bin/gitai).

Configuration

GitAI supports multiple configuration methods with the following precedence:

1. Environment Variables (highest priority)
2. Global Configuration (~/.config/gitai/config.json)
3. Project Configuration (config.json in project root)
4. Default Values (lowest priority)

Quick Setup with gitai init

The easiest way to configure GitAI is to run the interactive setup:

gitai init

This will guide you through:

• Setting your API key
• Choosing a model (with presets for popular options)
• Selecting commit message style

Your configuration will be saved globally in ~/.config/gitai/config.json.

Manual Configuration

Environment Variables (for project-specific or temporary overrides):

Create a .env file in your project root:

# API key for your LLM provider
AI_KEY=your_api_key_here

# LLM model to use
LLM_MODEL=gemini/gemini-2.5-flash

Global Configuration (for system-wide settings):

Run gitai init or manually create ~/.config/gitai/config.json:

{
  "api_key": "your_api_key_here",
  "model": "gemini/gemini-2.5-flash",
  "style": "conventional",
  "max_title_length": 72,
  "include_body": true,
  "auto_commit": false,
  "retry": 3
}

💡 Tip: For detailed instructions on configuring different AI providers (Google Gemini, OpenAI, Anthropic, Groq, etc.), see the AI Model Configuration Guide.

Viewing and Updating Configuration

View your current configuration:

gitai config

Update a specific setting:

gitai config model=gemini/gemini-1.5-pro
gitai config style=simple
gitai config auto_commit=true

Usage

Using GitAI is pretty straightforward. Just make your changes, stage them, and let GitAI suggest a commit message.

1. Stage Your Changes: Just like you normally would, add your changes to the staging area:

   git add .
   

2. Generate a Commit Message: Now, run GitAI from your terminal. It'll analyze your staged changes and suggest a message.

   gitai
   

   GitAI will print a suggested commit message and ask you if you'd like to use it. If you're happy, type y and press Enter. If not, you can type n to get another suggestion (up to 3 retries by default) or exit.

   🔍 Generating commit message...
   
   ✨ Suggested Commit Message:
   
   feat(cli): add interactive retry for commit messages
   
   - Implemented a retry mechanism for generating commit messages.
   - Allows users to request new messages if the initial suggestion is not suitable.
   - Configurable `retry` count in `config.json`.
   
   --------------------------------------------------
   👉 Use this commit message? (y/n): y
   ✅ Commit created.
   

3. Automatic Committing: If you've set "auto_commit": true in your config.json, GitAI will automatically commit with the generated message without asking for confirmation.

Logging & Error Handling

GitAI includes comprehensive logging and error handling with a focus on security:

• Secure Logging: All logs are automatically sanitized to prevent sensitive data (API keys, passwords, tokens) from being written to log files.
• Custom Exceptions: Clear, actionable error messages with suggestions for resolution.
• Debug-Friendly: Detailed logs are stored in the logs/ directory for troubleshooting.

For detailed information on configuring logging, understanding error types, and best practices, see the Logging and Error Handling Guide.

Technologies Used

Technology	Description	Link
Python	The primary programming language used for the project.	Python
Unidiff	Library for parsing and working with unified diff output.	Unidiff
LiteLLM	A universal API for all Large Language Models, simplifying AI integration.	LiteLLM
Rich	A Python library for rich text and beautiful formatting in the terminal.	Rich
Setuptools	Standard library for packaging Python projects.	Setuptools

Contributing

We'd love for you to contribute to GitAI! If you have ideas for new features, find a bug, or want to improve the codebase, please feel free to:

1. Fork the Repository: Start by forking the project to your own GitHub account.
2. Create a New Branch: Make a new branch for your changes (e.g., feature/add-new-llm, bugfix/parsing-issue).
3. Implement Your Changes: Write your code, ensuring it follows the existing style and conventions.
4. Write Tests: If applicable, add or update tests to cover your changes.
5. Submit a Pull Request: Open a pull request against the main branch of this repository. Please provide a clear description of your changes and why they're beneficial.

Author Info

• LinkedIn: Precious Ojogu
• X (formerly Twitter): @_Ojogu

---