🔮 Git-Iris: AI-Powered Git Workflow Assistant

Elevate your Git workflow with the power of AI 🚀

Installation • Docker • Configuration • Usage • Contributing • License

Git-Iris in action: AI-powered Git workflow assistance

🌟 Overview

Git-Iris is a comprehensive AI-powered Git workflow assistant that enhances your development process from start to finish. It offers intelligent support for crafting meaningful commit messages, generating insightful changelogs, creating detailed release notes, and providing code reviews. By leveraging advanced AI models, Git-Iris boosts your productivity and improves the quality of your project documentation.

✨ Features

Git-Iris offers a suite of AI-powered tools to enhance your Git workflow:

🧠 Core Features

Intelligent Commit Messages: Generate context-aware, meaningful commit messages
AI-Powered Code Reviews: Get detailed feedback on your changes across multiple quality dimensions
Dynamic Changelog Generation: Create structured changelogs between any Git references
Comprehensive Release Notes: Generate release notes with summaries and key changes
MCP Integration: Connect directly with Claude, Cursor, VSCode and other compatible AI tools
Project-Specific Configuration: Maintain shared project settings in version control

💪 Advanced Capabilities

Multi-Provider Support: Works with OpenAI, Anthropic, Google, Groq, XAI, Ollama and more
Remote Repository Support: Work with remote repositories without manual cloning
Customizable Workflows: Control AI behavior with custom instructions and presets
Smart Context Analysis: Extract relevant context from repository changes
Multi-Language Support: Analyze code in Rust, JavaScript, Python, Java, and more languages

🎨 User Experience

Interactive CLI: Refine AI-generated content through an intuitive interface
Gitmoji Integration: Add expressive emojis to your Git documentation
Performance Optimized: Efficient token management for responsive interactions
Docker Support: Run in CI/CD pipelines and workflows without installation

🛠️ Installation

Prerequisites

Rust and Cargo (latest stable version)
Git 2.23.0 or newer

Via Cargo (Recommended)

cargo install git-iris

Via Docker

Git-Iris is available as a Docker image:

docker pull hyperb1iss/git-iris:latest

Run it:

docker run --rm -v "$(pwd):/git-repo" hyperb1iss/git-iris gen

For detailed instructions, examples, and CI/CD integration, see our Docker Usage Guide.

Manual Installation

Clone the repository:

git clone https://github.com/hyperb1iss/git-iris.git
cd git-iris

Build and install:

cargo build --release
cargo install --path .

🐳 Docker

Git-Iris provides official Docker images for easy integration into your CI/CD pipelines and workflows without installation:

# Generate a commit message (mount current directory)
docker run --rm --user $(id -u):$(id -g) -v "$(pwd):/git-repo" hyperb1iss/git-iris gen

# Configure with environment variables
docker run --rm --user $(id -u):$(id -g) -v "$(pwd):/git-repo" \
  -e GITIRIS_PROVIDER="openai" \
  -e GITIRIS_API_KEY="your-api-key" \
  hyperb1iss/git-iris gen

For persistent configuration, mount a volume to store your settings:

docker run --rm --user $(id -u):$(id -g) -v "$(pwd):/git-repo" \
  -v git-iris-config:/root/.config/git-iris \
  hyperb1iss/git-iris config --provider openai --api-key your-api-key

The Docker image is particularly useful in CI/CD workflows:

# GitHub Actions example
- name: Generate Release Notes
  env:
    GITIRIS_PROVIDER: openai
    GITIRIS_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  run: |
    docker run --rm -v "$(pwd):/git-repo" \
      -e GITIRIS_PROVIDER -e GITIRIS_API_KEY \
      hyperb1iss/git-iris release-notes \
      --from $(git describe --tags --abbrev=0 $(git rev-list --tags --skip=1 --max-count=1)) \
      --to $(git describe --tags --abbrev=0) \
      --print > RELEASE_NOTES.md

To build and test the Docker image locally:

# Build the image with a custom tag
./docker/build.sh mytag

# Test the image
./docker/test-image.sh mytag

For detailed instructions, examples, and CI/CD integration, see our Docker Usage Guide.

⚙️ Configuration

Git-Iris offers both global configuration and project-specific configuration options.

Global Configuration

Global settings are stored in ~/.config/git-iris/config.toml and apply across all repositories:

# For OpenAI
git-iris config --provider openai --api-key YOUR_OPENAI_API_KEY

# For Anthropic
git-iris config --provider anthropic --api-key YOUR_ANTHROPIC_API_KEY
# Note: "claude" is still supported for backward compatibility

# For Google
git-iris config --provider google --api-key YOUR_GOOGLE_API_KEY

# For Ollama (no API key required)
git-iris config --provider ollama

# For other supported providers (Groq, XAI, DeepSeek, Phind)
git-iris config --provider <provider> --api-key YOUR_API_KEY

Project-Specific Configuration

Project settings are stored in .irisconfig in your repository root and can be shared with your team without sharing sensitive credentials:

# Set project-specific LLM provider
git-iris project-config --provider anthropic

# Configure project-specific preset
git-iris project-config --preset conventional

# Set model for the project
git-iris project-config --model claude-3-7-sonnet-20250219

# View current project configuration
git-iris project-config --print

Project configuration files do not store API keys for security reasons but can store other settings like models, presets, and custom instructions.

Supported LLM Providers

Git-Iris supports the following LLM providers:

Provider	Default Model	Token Limit	API Key Required
anthropic	claude-3-7-sonnet-20250219	200,000	Yes
deepseek	deepseek-chat	64,000	Yes
google	gemini-2.0-flash	1,000,000	Yes
groq	llama-3.1-70b-versatile	128,000	Yes
ollama	llama3	128,000	No
openai	gpt-4o	128,000	Yes
phind	phind-v2	32,000	No
xai	grok-2-beta	128,000	Yes

Additional configuration options:

# Enable/Disable Gitmoji
git-iris config --gitmoji true

# Set custom instructions
git-iris config --instructions "Always mention the ticket number in the commit message"

# Set default instruction preset
git-iris config --preset conventional

# Set token limit for a provider
git-iris config --provider openai --token-limit 4000

# Set model for a provider
git-iris config --provider openai --model gpt-4o

# Set additional parameters for a provider
git-iris config --provider openai --param temperature=0.7 --param max_tokens=150

For more detailed configuration information, please refer to our Configuration Guide.

📖 Usage

Global Options

These options apply to all commands:

-l, --log: Log debug messages to a file
--log-file: Specify a custom log file path
-q, --quiet: Suppress non-essential output (spinners, waiting messages, etc.)
-v, --version: Display version information
-r, --repo: Use a remote repository URL instead of local repository

Generate Commit Messages

Generate an AI-powered commit message:

git-iris gen

Options:

-a, --auto-commit: Automatically commit with the generated message
-i, --instructions: Provide custom instructions for this commit
--provider: Specify an LLM provider
--preset: Use a specific instruction preset
--no-gitmoji: Disable Gitmoji for this commit
-p, --print: Print the generated message to stdout and exit
--no-verify: Skip verification steps (pre/post commit hooks)

Example:

git-iris gen -a -i "Focus on performance improvements" --provider anthropic --preset detailed

To generate a commit message and print it to stdout without starting the interactive process:

git-iris gen --print

AI-Powered Code Reviews

Get a comprehensive analysis of your staged changes:

git-iris review

Options:

-i, --instructions: Provide custom instructions for this review
--provider: Specify an LLM provider
--preset: Use a specific instruction preset
-p, --print: Print the generated review to stdout and exit
--include-unstaged: Include unstaged changes in the review
--commit: Review a specific commit by ID (hash, branch, or reference)

Example:

git-iris review -i "Focus on security" --preset security --include-unstaged

Generate Changelogs

Create a detailed changelog between Git references:

git-iris changelog --from <from-ref> --to <to-ref>

Options:

--from: Starting Git reference (commit hash, tag, or branch name)
--to: Ending Git reference (defaults to HEAD if not specified)
-i, --instructions: Custom instructions for changelog generation
--preset: Select an instruction preset for changelog generation
--detail-level: Set the detail level (minimal, standard, detailed)
--gitmoji: Enable or disable Gitmoji in the changelog
--update: Update the changelog file with the new changes
--file: Path to the changelog file (defaults to CHANGELOG.md)
--version-name: Explicit version name to use in the changelog instead of getting it from Git

Example:

git-iris changelog --from v1.0.0 --to v1.1.0 --detail-level detailed --update

Example using explicit version name (useful in release workflows):

git-iris changelog --from v1.0.0 --to HEAD --update --version-name v1.1.0

Generate Release Notes

Create comprehensive release notes:

git-iris release-notes --from <from-ref> --to <to-ref>

Options:

--from: Starting Git reference (commit hash, tag, or branch name)
--to: Ending Git reference (defaults to HEAD if not specified)
-i, --instructions: Custom instructions for release notes generation
--preset: Select an instruction preset for release notes generation
--detail-level: Set the detail level (minimal, standard, detailed)
--gitmoji: Enable or disable Gitmoji in the release notes
--version-name: Explicit version name to use in the release notes instead of getting it from Git

Example:

git-iris release-notes --from v1.0.0 --to v1.1.0 --preset conventional

Example using explicit version name:

git-iris release-notes --from v1.0.0 --to HEAD --version-name v1.1.0

Project Configuration

Create or update project-specific settings:

git-iris project-config

Options:

--provider: Set default LLM provider for this project
--model: Set model for the specified provider
--token-limit: Set token limit for the specified provider
--param: Set additional parameters for the specified provider
-p, --print: Print the current project configuration
--gitmoji: Enable or disable Gitmoji for this project
-i, --instructions: Set instructions for message generation
--preset: Set default instruction preset for this project

Example:

git-iris project-config --provider anthropic --preset security --model claude-3-7-sonnet-20250219

Working with Remote Repositories

Git-Iris supports working with remote repositories directly without having to clone them manually:

# Generate a changelog between two tags on a remote repository
git-iris changelog --repo https://github.com/example/repo.git --from v1.0.0 --to v2.0.0

# Generate release notes for a remote repository
git-iris release-notes --repo https://github.com/example/repo.git --from v1.0.0 --to v2.0.0

# Review code in a remote repository (read-only)
git-iris review --repo https://github.com/example/repo.git

# Generate a commit message for a remote repository (read-only)
git-iris gen --repo https://github.com/example/repo.git --print

Note: When working with remote repositories, Git-Iris operates in read-only mode. You can't commit changes directly to remote repositories.

MCP Server for AI Integration

Start an MCP (Model Context Protocol) server for integration with AI tools:

git-iris serve

Options:

--dev: Enable development mode with more verbose logging
-t, --transport: Transport type to use (stdio, sse)
-p, --port: Port to use for network transports
--listen-address: Listen address for network transports

Example:

git-iris serve --transport sse --port 3077 --listen-address 127.0.0.1

This allows you to use Git-Iris features directly from Claude, Cursor, VSCode, and other MCP-compatible tools. See MCP.md for detailed documentation.

MCP Tool Parameters

All MCP tools require the repository parameter, which must be a local project path or a remote repository URL. This is necessary because some clients (like Cursor) do not reliably provide the project root.

Example (local path):

{
  "from": "v1.0.0",
  "to": "v2.0.0",
  "detail_level": "detailed",
  "repository": "/home/bliss/dev/myproject"
}

Example (remote URL):

{
  "from": "v1.0.0",
  "to": "v2.0.0",
  "detail_level": "detailed",
  "repository": "https://github.com/example/repo.git"
}

Why is repository required?

Due to limitations in some MCP clients, the server cannot reliably infer the project root or repository path. To ensure Git-Iris always operates on the correct repository, you must explicitly specify the repository parameter for every tool call. This eliminates ambiguity and ensures your commands are always precise and predictable.

Interactive Commit Process

The interactive CLI allows you to refine and perfect your commit messages:

Use arrow keys to navigate through suggestions
Press 'e' to edit the current message
Press 'i' to modify AI instructions
Press 'g' to change the emoji
Press 'p' to change the preset
Press 'u' to edit user info
Press 'r' to regenerate the message
Press Enter to commit
Press Esc to cancel

Getting an AI Code Review

Git-Iris can analyze your staged changes and provide a detailed code review:

git-iris review

The review includes:

A summary of the changes
Code quality assessment
Suggestions for improvement
Identified issues
Positive aspects of your code
Analysis across 11 dimensions of code quality:
- Complexity - Identifies unnecessary complexity in algorithms and control flow
- Abstraction - Assesses appropriateness of abstractions and design patterns
- Unintended Deletion - Detects critical functionality removed without replacement
- Hallucinated Components - Flags references to non-existent functions or APIs
- Style Inconsistencies - Highlights deviations from project coding standards
- Security Vulnerabilities - Identifies potential security issues
- Performance Issues - Spots inefficient algorithms or resource usage
- Code Duplication - Detects repeated logic or copy-pasted code
- Error Handling - Evaluates completeness of error recovery strategies
- Test Coverage - Analyzes test coverage gaps or brittle tests
- Best Practices - Checks adherence to language-specific conventions and design guidelines

🎛️ Custom Instructions and Presets

Git-Iris offers two powerful ways to guide the AI in generating commit messages: custom instructions and presets.

Instruction Presets

Presets are predefined sets of instructions that provide a quick way to adjust the commit message style. Git-Iris comes with several built-in presets to suit different commit styles and project needs.

To list available presets:

git-iris list-presets

This will display a list of all available presets with a brief description of each, categorized by type (general, review-specific, or commit-specific).

Some key presets include:

default: Standard professional style (for both commits and reviews)
conventional: Follows the Conventional Commits specification
detailed: Provides more context and explanation
concise: Short and to-the-point responses
cosmic: Mystical, space-themed language

For code reviews specifically, Git-Iris includes specialized presets:

security: Focus on security vulnerabilities and best practices
performance: Analyze code for performance optimizations
architecture: Evaluate architectural patterns and design decisions
testing: Focus on test coverage and testing strategies
maintainability: Evaluate code for long-term maintenance
conventions: Check adherence to language and project coding standards

To use a preset for a single commit:

git-iris gen --preset conventional

To use a preset for a code review:

git-iris review --preset security

To set a default preset:

git-iris config --preset conventional

Presets work seamlessly with other Git-Iris features. For example, if you have Gitmoji enabled, the preset instructions will be applied in addition to adding the appropriate Gitmoji.

Custom Instructions

Custom instructions allow you to provide specific guidance for commit message generation. These can be set globally or per-commit.

Setting global custom instructions:

git-iris config --instructions "Always include the ticket number and mention performance impacts"

Providing per-commit instructions:

git-iris gen -i "Emphasize security implications of this change"

Combining Presets and Custom Instructions

When using both a preset and custom instructions, Git-Iris combines them, with custom instructions taking precedence. This allows you to use a preset as a base and fine-tune it with specific instructions.

git-iris gen --preset conventional -i "Mention the JIRA ticket number"

In this case, the commit message will follow the Conventional Commits format and include the JIRA ticket number.

If you've set a default preset in your configuration, you can still override it for individual commits:

git-iris gen --preset detailed -i "Focus on performance improvements"

This will use the 'detailed' preset instead of your default, along with the custom instruction.

Examples of Custom Instructions

Ticket Number Integration

Always start the commit message with the JIRA ticket number in square brackets

Language-Specific Conventions

For Rust files, mention any changes to public APIs or use of unsafe code

Team-Specific Guidelines

Follow the Angular commit message format: <type>(<scope>): <subject>

Project-Specific Context

For the authentication module, always mention if there are changes to the user model or permissions

Performance Considerations

Highlight any changes that might affect application performance, including database queries

Custom instructions and presets allow you to tailor Git-Iris to your specific project needs, team conventions, or personal preferences. They provide a powerful way to ensure consistency and capture important context in your commit messages.

🤝 Contributing

We welcome contributions! Please see our CONTRIBUTING.md for details on how to get started, our code of conduct, and the process for submitting pull requests.

📄 License

Distributed under the Apache 2.0 License. See LICENSE for more information.

📚 Documentation • 🐛 Report Bug • 💡 Request Feature

Created by Stefanie Jane 🌠

If you find Git-Iris useful, buy me a Monster Ultra Violet! ⚡️

git-iris 1.1.0

🔮 Git-Iris: AI-Powered Git Workflow Assistant

🌟 Overview

✨ Features

🧠 Core Features

💪 Advanced Capabilities

🎨 User Experience

🛠️ Installation

Prerequisites

Via Cargo (Recommended)

Via Docker

Manual Installation

🐳 Docker

⚙️ Configuration

Global Configuration

Project-Specific Configuration

Supported LLM Providers

📖 Usage

Global Options

Generate Commit Messages

AI-Powered Code Reviews

Generate Changelogs

Generate Release Notes

Project Configuration

Working with Remote Repositories

MCP Server for AI Integration

MCP Tool Parameters

Interactive Commit Process

Getting an AI Code Review

🎛️ Custom Instructions and Presets

Instruction Presets

Custom Instructions

Combining Presets and Custom Instructions

Examples of Custom Instructions

🤝 Contributing

📄 License