AI Git Narrator

AI Git Narrator is a command-line tool that leverages OpenAI's GPT models, Google's Gemini models, and Ollama's local LLM models to generate insightful commit messages and pull request descriptions based on your Git diffs and commits. This tool aims to streamline your development workflow by automating the often tedious task of writing meaningful and comprehensive Git history, making collaboration easier and your project's evolution clearer.

Built specifically for macOS, AI Git Narrator is designed to integrate seamlessly into macOS development workflows, taking advantage of the platform's native capabilities and Swift's performance optimizations.

Why AI Git Narrator?

• Save Time & Effort: Stop spending precious minutes crafting the perfect commit message. Let AI do the heavy lifting.
• Improve Clarity: Generate consistent and descriptive messages that make your Git log a valuable resource.
• Enhance Collaboration: Well-written PR descriptions facilitate smoother code reviews and team understanding.
• Focus on Coding: Spend more time developing and less time on Git administrative tasks.
• Customizable: Tailor the AI's output to your project's needs with configurable parameters and choice of AI provider.
• Dedicated & Focused: Unlike built-in AI features in larger IDEs or platforms, AI Git Narrator is a lightweight, command-line tool specifically designed for Git. It offers a streamlined experience without the overhead of a full-fledged development environment, providing greater control, flexibility, and often more detailed and tailored output for users who prefer a dedicated tool.

Features

• Generate Commit Messages: Automatically generate commit messages based on all changes, staged changes, or unstaged changes.
• Generate PR Descriptions: Create detailed pull request descriptions based on your commit history.
• Support for Multiple AI Providers: Choose between OpenAI's GPT models, Google's Gemini models, and Ollama's local LLM models.
• Customizable Parameters: Configure the model, maximum tokens, and temperature for the selected AI model to suit your needs.

Installation

Homebrew (Recommended)

The easiest way to install AI Git Narrator is via Homebrew:

brew tap pmusolino/ai-git-narrator
brew install ai-git-narrator

After installation, you can immediately use the tool:

ai-git-narrator --help

Building from Source

Requirements: This tool is designed specifically for macOS and requires Swift 6.x or later.

To build AI Git Narrator from source, clone the repository:

git clone https://github.com/pmusolino/AI-Git-Narrator.git
cd AI\ Git\ Narrator/

This project includes a helper script to create a release build of the executable and place it in the project root directory.

1. Make sure the script is executable:

   chmod +x build_executable.sh

2. Run the script:

   ./build_executable.sh

   This will compile the ai-git-narrator executable and copy it to your project's root directory. You can then run it directly from there.

Usage

Run the tool from the command line with the following options:

ai-git-narrator [--api-key <api-key>] [--llm-provider <provider>] [--model <model>] [--max-tokens <max-tokens>] [--temperature <temperature>] [--timeout <timeout>] [--ollama-base-url <ollama-base-url>] [--base-branch <base-branch>] [--generate-commit-message] [--generate-staged-commit-message] [--generate-unstaged-commit-message] [--generate-pr]

Options

• --help: Display the help message.
• --api-key <api-key>: Set the API key for the selected AI provider (mandatory for OpenAI and Gemini, optional for Ollama).
• --llm-provider <provider>: Set the AI provider (default: openai). Supported values: openai, gemini, ollama.
• --model <model>: Set the model for the AI provider (default: gpt-4.1-mini for OpenAI, gemini-2.0-flash for Gemini, llama3.2 for Ollama).
• --max-tokens <max-tokens>: Set the maximum number of tokens (default: 32768).
• --temperature <temperature>: Set the temperature for sampling (default: 0.7). Lower values make the output more focused and deterministic, while higher values make it more random.
• --timeout <timeout>: Set the request timeout in seconds for the LLM provider (default: 120).
• --ollama-base-url <ollama-base-url>: Set the Ollama base URL (default: http://localhost:11434). Only used when --llm-provider is ollama.
• --base-branch <base-branch>: Set the base branch to compare for generating PR description.
• --generate-commit-message: Generate a commit message based on all changes.
• --generate-staged-commit-message: Generate a commit message based on staged changes.
• --generate-unstaged-commit-message: Generate a commit message based on unstaged changes.
• --generate-pr: Generate a PR title and description based on commits.

Examples

Generate a commit message for all changes using OpenAI:

./ai-git-narrator --api-key YOUR_OPENAI_API_KEY --generate-commit-message

Generate a commit message for staged changes using Gemini:

./ai-git-narrator --api-key YOUR_GEMINI_API_KEY --llm-provider gemini --model gemini-2.0-flash --generate-staged-commit-message

Generate a PR description using OpenAI:

./ai-git-narrator --api-key YOUR_OPENAI_API_KEY --generate-pr

Generate a PR description using Gemini with a specific model:

./ai-git-narrator --api-key YOUR_GEMINI_API_KEY --llm-provider gemini --model gemini-2.0-flash --generate-pr

Generate a commit message for all changes using Ollama:

./ai-git-narrator --llm-provider ollama --model llama3.2 --generate-commit-message

Generate a PR description using Ollama with a custom model:

./ai-git-narrator --llm-provider ollama --model llama3.1:8b --generate-pr

Obtaining an OpenAI API Key

To use AI Git Narrator, you need an API key from OpenAI. If you don't have one, follow these steps:

1. Create an OpenAI Account: Go to https://platform.openai.com/signup and create an account.
2. Navigate to API Keys: Once logged in, go to the API keys section of your OpenAI dashboard, usually found at https://platform.openai.com/account/api-keys.
3. Create a New Secret Key: Click on "Create new secret key". Give it a name (e.g., "AIGitNarratorKey") and save the key securely. You will not be able to see it again after closing the dialog.
4. Set up Billing: Ensure you have set up a payment method and have credits or a subscription that allows API usage. New accounts often come with free trial credits.

Keep your API key confidential and do not share it publicly. You will use this key with the --api-key option when running AI Git Narrator with --llm-provider openai.

Obtaining a Google AI Studio (Gemini) API Key

To use AI Git Narrator with Gemini models, you need an API key from Google AI Studio. If you don't have one, follow these steps:

1. Go to Google AI Studio: Visit https://aistudio.google.com/.
2. Sign In: Sign in with your Google account.
3. Get API Key: Look for an option like "Get API key" or navigate to the API key section. You might need to create a new project if you haven't used Google AI services before.
4. Create API Key: Follow the instructions to create a new API key.
5. Enable APIs: Ensure that the necessary APIs are enabled for your project in the Google Cloud Console if required.
6. Set up Billing: Verify if billing is required for the level of usage you anticipate. Some services might have a free tier.

Keep your API key confidential and do not share it publicly. You will use this key with the --api-key option when running AI Git Narrator with --llm-provider gemini.

Setting Up Ollama (Local LLM)

To use AI Git Narrator with Ollama for local LLM models, you need to install and set up Ollama in your local machine. Follow these steps:

1. Install Ollama: Visit https://ollama.ai/ and download Ollama for your operating system.
2. Start Ollama: After installation, start the Ollama service. On most systems, this runs automatically as a background service on http://localhost:11434.
3. Download Models: Install the models you want to use. For example, to install the default llama3.2 model:

   ollama pull llama3.2

   You can also install other models like llama3.1:8b, mistral, codellama, etc.
4. Verify Installation: Check that Ollama is running by visiting http://localhost:11434 in your browser or running:

   ollama list

Benefits of using Ollama:

• Privacy: Models run locally on your machine, so your code never leaves your system
• No API costs: Once installed, there are no per-request charges
• Offline usage: Works without an internet connection
• No API key required: Unlike OpenAI and Gemini, Ollama doesn't require an API key

Note: You can specify a custom Ollama URL using --ollama-base-url if you're running Ollama on a different host or port.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an issue for bugs, features, or improvements.

License

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