🔮 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)
Via Docker
Git-Iris is available as a Docker image:
Run it:
For detailed instructions, examples, and CI/CD integration, see our Docker Usage Guide.
Manual Installation
-
Clone the repository:
-
Build and install:
🐳 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)
# Configure with environment variables
For persistent configuration, mount a volume to store your settings:
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
# Test the image
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
# For Anthropic
# Note: "claude" is still supported for backward compatibility
# For Google
# For Ollama (no API key required)
# For other supported providers (Groq, XAI, DeepSeek, Phind)
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
# Configure project-specific preset
# Set model for the project
# View current project configuration
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 |
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
# Set custom instructions
# Set default instruction preset
# Set token limit for a provider
# Set model for a provider
# Set additional parameters for a provider
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:
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:
To generate a commit message and print it to stdout without starting the interactive process:
AI-Powered Code Reviews
Get a comprehensive analysis of your staged changes:
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:
Generate Changelogs
Create a detailed changelog between Git references:
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:
Example using explicit version name (useful in release workflows):
Generate Release Notes
Create comprehensive release notes:
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:
Example using explicit version name:
Project Configuration
Create or update project-specific settings:
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:
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
# Generate release notes for a remote repository
# Review code in a remote repository (read-only)
# Generate a commit message for a remote repository (read-only)
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:
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:
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):
Example (remote URL):
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:
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:
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 specificationdetailed
: Provides more context and explanationconcise
: Short and to-the-point responsescosmic
: Mystical, space-themed language
For code reviews specifically, Git-Iris includes specialized presets:
security
: Focus on security vulnerabilities and best practicesperformance
: Analyze code for performance optimizationsarchitecture
: Evaluate architectural patterns and design decisionstesting
: Focus on test coverage and testing strategiesmaintainability
: Evaluate code for long-term maintenanceconventions
: Check adherence to language and project coding standards
To use a preset for a single commit:
To use a preset for a code review:
To set a default preset:
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:
Providing per-commit instructions:
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.
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:
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! ⚡️