pmusolino/ai-git-narrator

AI Git Narrator

[![Swift Version](https://img.shields.io/badge/swift-6.x-orange.svg)](https://swift.org)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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:

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

After installation, you can immediately use the tool:
```bash
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:
```bash
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:
    ```bash
    chmod +x build_executable.sh
    ```
2.  Run the script:
    ```bash
    ./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:
```bash
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:
```bash
./ai-git-narrator --api-key YOUR_OPENAI_API_KEY --generate-commit-message
```

Generate a commit message for staged changes using Gemini:
```bash
./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:
```bash
./ai-git-narrator --api-key YOUR_OPENAI_API_KEY --generate-pr
```

Generate a PR description using Gemini with a specific model:
```bash
./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:
```bash
./ai-git-narrator --llm-provider ollama --model llama3.2 --generate-commit-message
```

Generate a PR description using Ollama with a custom model:
```bash
./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](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](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/](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/](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:
    ```bash
    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:
    ```bash
    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](LICENSE) file for details.

Package Metadata

Repository: pmusolino/ai-git-narrator

Default branch: main

README: README.md