Git-AI: Your Friendly AI-Powered Commit Companion

Git-AI transforms your staged changes into clear, human-sounding Git commit messages—powered by LLMs (OpenAI, Ollama, Anthropic, and more). It also provides comprehensive AI-powered code review with professional reports and colored CLI output. The tool handles staging, message generation, code review, inline editing, committing, and pushing, so you can focus entirely on code. The new architecture is provider-agnostic, modular, and fully extensible.

---

Table of Contents

1. Prerequisites
2. Installation
3. Configuration
4. Usage
   • Generating a Commit
   • AI Code Review
   • Listing Models
   • Changing Format
   • Editing Configuration
   • Switching Providers
5. Cross-Platform Build Scripts
6. Advanced: Standalone Binary (DIY)
7. To-Do / Future Plans
8. License

---

Prerequisites

Before you begin, ensure you have:

• Python 3.8+ installed and on your PATH.
• Git installed and configured (username/email set).
• An API key for your chosen provider (OpenAI, Anthropic, etc). You can obtain an OpenAI key at https://platform.openai.com. Ollama requires a local server running.
• (Optional) pyinstaller if you plan to create a standalone binary.

---

Installation

1. Clone the repository:

   git clone https://github.com/samrand96/git-ai.git
   cd git-ai

2. Install dependencies:

   pip install -r requirements.txt

3. Make the script executable (Unix/macOS):

   chmod +x main.py

---

Configuration

On first run, Git-AI will automatically prompt you to:

1. Select your provider (OpenAI, Ollama, Anthropic, ...).
2. Enter your API key (if required by provider).
3. Choose a model from the fetched list (or type your own).
4. Select your default commit style: detailed (multi-sentence) or one-line.

These settings are saved in an INI file at:

• Linux: ~/.config/sam.git.ini
• macOS: ~/.config/sam.git.ini
• Windows: %APPDATA%\sam.git.ini

Tip: You can open this file in any text editor to inspect or manually tweak values.

To reconfigure at any time, simply run:

python main.py config --interactive

This enters interactive mode, showing current values and letting you update only the fields you wish (leave blank to retain the existing setting). You can also set values directly:

python main.py config --set PROVIDER ollama
python main.py config --set-provider openai API_KEY sk-...
python main.py config --set-provider ollama MODEL llama3

---

Usage

Generating a Commit

1. Stage your changes in Git (e.g., git add .).

2. Run:

   python main.py commit

3. The tool will:

   • Stage all unstaged changes.
   • Detect your current branch name and extract any ticket prefix (e.g. ABC-123).
   • Generate a commit message using your selected provider and model.
   • Display the chosen message inline.
   • Prompt: Edit before commit? • Press Enter to skip edits. • Type your own message, ending with an empty line, to replace it.
   • Commit the message.
   • Prompt: Push changes? [Y/n].

AI Code Review

Git-AI now includes a comprehensive AI-powered code review feature that analyzes your changes and provides professional feedback with colored CLI output or beautiful HTML reports.

Basic Usage

python main.py review

By default, this reviews all changes (both staged and unstaged) with a comprehensive analysis covering logic, security, performance, code quality, documentation, and style.

Review Options

Choose what changes to review:

python main.py review --changes staged        # Only git add'ed files
python main.py review --changes unstaged      # Only modified files  
python main.py review --changes all           # Both staged + unstaged (default)
python main.py review --changes last-commit   # Previous commit

Focus on specific review types:

python main.py review --type logical          # Logic and correctness only
python main.py review --type security         # Security vulnerabilities only
python main.py review --type performance      # Performance issues only
python main.py review --type style            # Code style and standards only
python main.py review --type documentation    # Documentation completeness only
python main.py review --type all              # Comprehensive review (default)

Control severity level:

python main.py review --severity critical     # Only critical issues
python main.py review --severity high         # High and critical issues
python main.py review --severity medium       # Medium, high, and critical (default)
python main.py review --severity low          # All issues including low priority

HTML Reports

Generate beautiful, professional HTML reports perfect for sharing with your team or including in PR reviews:

python main.py review --html                           # Generate HTML report
python main.py review --html --output my_review.html   # Custom filename
python main.py review --type security --html           # Security-focused HTML report

The AI generates a complete HTML document with:

• Modern responsive design with professional styling
• Color-coded severity levels and interactive table of contents
• Code syntax highlighting and detailed findings with file/line references
• Executive summary with metrics and actionable recommendations
• Security risk matrix and performance impact analysis
• Compliance checklist for best practices

CLI Features

The CLI output includes smart color formatting:

• 🔴 Red: Critical errors, vulnerabilities, dangerous patterns
• 🟡 Yellow: Warnings, potential issues, suggestions
• 🟢 Green: Good practices, correct implementations
• 🔵 Cyan: Section headers and information
• ⚪ White: General findings and bullet points

Examples

# Quick security check of your current changes
python main.py review --type security

# Comprehensive HTML report for code review meeting
python main.py review --html --output "sprint_review.html"

# Check only critical issues in staged files
python main.py review --changes staged --severity critical

# Performance analysis of your last commit
python main.py review --changes last-commit --type performance

Listing Models

To see all available models for your current provider:

python main.py list-models

Pick any model by its exact name or its index when reconfiguring.

Changing Format

Override or switch your default commit style:

python main.py config --set COMMIT_FORMAT one-line
python main.py config --set COMMIT_FORMAT detailed

This updates your config so future runs use the selected style automatically.

Editing Configuration

Enter full configuration mode to update provider, API key, model, or format:

python main.py config --interactive

Follow the interactive prompts. Leave blank to keep existing values.

You can also set any value directly (see above).

Switching Providers

To switch between OpenAI, Ollama, Anthropic, Gemini, or LMStudio (or add your own):

python main.py config --set PROVIDER ollama
python main.py config --set PROVIDER openai

Then use --set-provider to update provider-specific settings as needed.

---

Cross-Platform Build Scripts

To easily build a standalone executable and set up your environment, use the provided scripts:

Windows

• Use build.bat (right-click and run as administrator):
  • Checks for PyInstaller and builds with no prompt.
  • Optionally adds the dist folder to your PATH for the session or permanently.
  • Shows a PowerShell command for session use if desired.

Linux/macOS

• Use build.sh:
  • Make it executable: chmod +x build.sh
  • Run: ./build.sh
  • Checks for PyInstaller and builds with no prompt.
  • Optionally adds the dist folder to your PATH for the session or permanently (shell profile).

After building, you can run the CLI from anywhere if you add it to your PATH.

---

Advanced: Standalone Binary

If you’d rather run git-ai without Python installed at runtime:

1. Install PyInstaller (if you haven’t already):

   pip install pyinstaller

2. Build the executable:

   pyinstaller --onefile main.py

3. Copy it into your PATH:

   mv dist/git-ai /usr/local/bin/git-ai
   chmod +x /usr/local/bin/git-ai

4. Now run:

   git-ai

---

To-Do / Future Plans

• AI Code Review: Professional code analysis with CLI colors and HTML reports - supports multiple review types, severity levels, and change scopes.
• Support for Conventional Commits: automatically enforce and generate messages in the type(scope): description format (feat, fix, docs, etc.).
• Pre-commit and commit-msg hooks: integrate Git hooks to validate or reformat the AI-generated commit before it’s saved.
• Issue tracker integration: detect and link JIRA, GitHub, or GitLab issue IDs to commits, and fetch issue titles for context.
• Automated semantic version tagging: analyze commit types and suggest or apply version bumps (major, minor, patch) and tag accordingly.
• Changelog automation: aggregate and format commit messages into a CHANGELOG.md, grouped by version and type.
• Custom branch naming rules: allow teams to define and validate branch patterns for consistent ticket prefixes.
• Offline/fallback mode: cache recent commit templates or model outputs so basic messages can be generated without internet.
• Performance profiling and optimization: track and reduce latency for commit generation in large repositories.
• AI security check-up: scan generated commit text for potential secrets, PII, or insecure patterns before committing.
• Template configuration: allow users to define custom commit templates with optional footers, co-author tags, or emojis.
• Multi-language support: enable commit messages in different languages based on project locale or user preference.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Git-AI: Let AI handle the words so you can handle the code.