Tortoise AI Commit 🐢✨

A lightweight, dual-mode TortoiseGit hook & CLI tool that automatically generates clean, informative commit messages in Conventional Commits format using any OpenAI-compatible AI backend (local Ollama, LM Studio, OpenAI, OpenRouter, etc.).

---

🌟 Key Features

• 🎯 Dual Mode Operation:
  • TortoiseGit Hook: Automatically pre-fills the TortoiseGit commit message area upon opening the commit dialog.
  • Standalone CLI: Run ai-commit directly in your favorite terminal (CMD, PowerShell, Windows Terminal) with formatted console output.
• 🔌 Universal OpenAI-Compatible API: Works seamlessly with local models via Ollama or LM Studio, as well as cloud providers like OpenAI, OpenRouter, or Groq.
• ⚡ Instant Provider Profiles: Switch between configured providers (Ollama, OpenAI, LM Studio, etc.) by changing a single word ($AI_ACTIVE_PROFILE).
• 📋 Modular Commit Formats: Easily switch between built-in format templates or add your own in the prompts/ directory:
  • conventional-body (default: subject line + bullet points with dashes)
  • conventional (single-line summary)
  • gitmoji (emoji-prefixed conventional commits)
• 🔍 Deep Function Context (-w / --context): Use git diff -W to provide the LLM with the entire enclosing function context, producing far more accurate commit descriptions for localized changes.
• 🎯 Targeted File Selection: Pass specific files directly in the CLI (ai-commit file1 file2) to generate messages exclusively for those changes.
• 📦 Index-First Accuracy: By default the tool analyzes only the Git index (git diff --cached), so the message describes exactly what will be committed. Untracked files and unstaged edits are never mentioned. Use --all (or $AI_INCLUDE_UNSTAGED = $true) to widen the analysis to the whole working tree.
• 🧹 Smart Draft & Scratchpad Filter: Automatically exclude drafts, notes, or scratchpads using customizable glob patterns ($AI_EXCLUDE).
• 🌐 Universal Multilingual Support: Supports any ISO 639-1 language code (en, ru, de, es, fr, ja, etc.) or full language name via built-in .NET CultureInfo.
• 🛠️ Correct UTF-8 Everywhere: Responses are decoded from raw bytes with explicit UTF-8, so Cyrillic and other non-ASCII commit messages never turn into mojibake even in Windows PowerShell 5.1.

---

📂 Project Structure

tortoise-ai-commit/
├── prompts/
│   ├── conventional-body.txt  # Default: subject + bullet points with dashes
│   ├── conventional.txt       # Single-line conventional commit
│   └── gitmoji.txt            # Gitmoji conventional commit
├── ai-commit.ps1              # Main hook and CLI engine
├── ai-commit.cmd              # Command wrapper for fast terminal execution
├── environment.example.ps1    # Configuration template (copy to environment.ps1)
├── .gitignore                 # Excludes local secrets (environment.ps1)
├── LICENSE                    # MIT License
└── README.md

---

🚀 Installation & Setup

Step 1: Clone the Repository

Clone this repository to a stable directory on your machine (e.g., C:\Tools\tortoise-ai-commit):

git clone https://github.com/goloveshko/tortoise-ai-commit.git C:\Tools\tortoise-ai-commit

Step 2: Configure Environment

1. In the project folder, duplicate environment.example.ps1 and rename it to environment.ps1.
2. Open environment.ps1 and adjust your preferences:
   • Active Profile: Set $AI_ACTIVE_PROFILE = "ollama" (or "openai", "lm-studio", "openrouter").
   • Format: Choose $AI_FORMAT = "conventional-body" (or "conventional", "gitmoji").
   • Language: Set $AI_LANGUAGE = "en" (or "ru", "de", "es", etc.).
   • Exclusions: Modify $AI_EXCLUDE for draft/temporary files.

💡 Recommended local model: qwen2.5-coder:7b. It is fast, lightweight, and excels at understanding Git diffs.

---

🖥️ Usage

Option A: Standalone CLI (Terminal)

To run ai-commit from anywhere in any terminal:

1. Add C:\Tools\tortoise-ai-commit to your Windows PATH environment variable.
2. Open any terminal in any Git repository and run:

# Generate a message for the staged changes (Git index) only:
ai-commit

# Generate with full function context (-W / --function-context):
ai-commit -w

# Include unstaged changes and untracked files as well:
ai-commit --all

# Generate only for specific files:
ai-commit src/main.cpp include/config.h

# Combine flags and specific files:
ai-commit -w src/auth.go

📦 What gets analyzed: by default the tool reads git diff --cached, i.e. only what you have staged with git add. Files that just sit in the folder (untracked) and unstaged edits are ignored, so the generated message never mentions changes that will not be committed. Add --all when you want the whole working tree (staged + unstaged + untracked) described instead.

Option B: TortoiseGit Hook (GUI)

To have commit messages generated automatically when opening TortoiseGit:

1. Right-click anywhere in Windows Explorer and open TortoiseGit → Settings.
2. In the left navigation tree, select Hook Scripts.
3. Click Add...:
   • Hook Type: Select Start Commit Hook.
   • Run when working tree path is under: Enter * (asterisk applies the hook to all repositories) or specify a particular repository path.
   • Command Line To Execute:

     powershell.exe -ExecutionPolicy Bypass -File "C:\Tools\tortoise-ai-commit\ai-commit.ps1"

     (⚠️ Adjust to your actual path. Do NOT append %1 or %2 — TortoiseGit appends them automatically).
   • Wait for the script to finish: ✅ Checked.
   • Hide the script while running: ✅ Checked.
   • Enable: ✅ Checked (at the top of the dialog).
4. Click OK and Apply.

⏱️ Note on TortoiseGit Delay: When clicking Git Commit..., the dialog will take 2 to 5 seconds to appear. This delay occurs because the hook queries the LLM and pre-fills the message before the window is rendered.

---

⚙️ Advanced Customization

Adding Custom Commit Formats

Create a new text file inside the prompts/ directory (e.g., prompts/my-style.txt). In your environment.ps1, specify:

$AI_FORMAT = "my-style"

Use {{LANG_INSTRUCTION}} inside your prompt file to allow dynamic language substitution.

Expanding Function Context Globally

If you always want the AI to analyze entire functions instead of small diff hunks, enable it in environment.ps1:

$AI_EXPAND_CONTEXT = $true

Analyzing the Whole Working Tree

The default scope is the Git index — only staged changes are described. To make the tool analyze every change in the working tree (staged + unstaged + untracked files) on every run, enable it globally:

$AI_INCLUDE_UNSTAGED = $true

This is especially handy for the TortoiseGit hook, where CLI flags cannot be passed.

---

❓ Troubleshooting

The commit message shows # [AI Error]

If the AI server is unreachable, times out, or returns an error, the script will write an error description directly into the commit text box (or terminal output).

• If using Ollama, verify that the service is running (ollama list or check the system tray).
• Verify that the model specified in your profile is downloaded (ollama pull qwen2.5-coder:7b).
• Check your network connection and API keys for cloud providers.

Execution Policy Error

If PowerShell scripts are restricted on your system, ensure -ExecutionPolicy Bypass is included in the hook command:

powershell.exe -ExecutionPolicy Bypass -File "C:\Tools\tortoise-ai-commit\ai-commit.ps1"

---

📄 License

This project is licensed under the MIT License.

---

☕ Support & Feedback

Developed with ❤️ by a professional C++ & Qt developer.

• Telegram Support Bot: @itz2bot
• Portfolio: sergey.is-a.dev
• GitHub Issues: Report a bug