git-iris 0.9.0

AI-assisted Git workflow
Documentation

🔮 Git-Iris: AI-Powered Git Workflow Assistant

CI/CD License GitHub Release

Elevate your Git workflow with the power of AI 🚀

Installation • 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, and creating detailed release notes. 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:

  • 🤖 Intelligent Commit Messages: Generate context-aware, meaningful commit messages
  • 📜 Dynamic Changelog Generation: Create structured, detailed changelogs between any two Git references
  • 📋 Comprehensive Release Notes: Automatically generate release notes with summaries and key changes
  • 🔄 Multi-Provider AI Support: Leverage OpenAI GPT-4o, Anthropic Claude, or Ollama for AI capabilities
  • 🎨 Gitmoji Integration: Add expressive emojis to your commits, changelogs, and release notes
  • 🖥️ Interactive CLI: Refine AI-generated content through an intuitive command-line interface
  • 🔧 Customizable Workflows: Tailor AI behavior with custom instructions and presets
  • 📚 Flexible Instruction Presets: Quickly switch between different documentation styles
  • 🧠 Smart Context Extraction: Analyze repository changes for more accurate AI-generated content
  • 📊 Intelligent Code Analysis: Provide context-aware suggestions based on your codebase
  • 🔍 Relevance Scoring: Prioritize important changes in generated content
  • 📝 Multi-Language Support: Analyze changes in Rust, JavaScript, Python, Java, and more
  • 🚀 Performance Optimized: Efficient token management for responsive AI interactions

🛠️ Installation

Prerequisites

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

Via Cargo (Recommended)

cargo install git-iris

Manual Installation

  1. Clone the repository:

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

  2. Build and install:

    cargo build --release
cargo install --path .

⚙️ Configuration

Git-Iris uses a configuration file located at ~/.config/git-iris/config.toml. Set up your preferred AI provider:

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

# For Anthropic Claude
git-iris config --provider claude --api-key YOUR_CLAUDE_API_KEY

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

Additional configuration options:

# Set default provider
git-iris config --default-provider openai

# 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

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 (openai, claude, ollama)
  • --preset: Use a specific instruction preset
  • --no-gitmoji: Disable Gitmoji for this commit
  • -l, --log: Enable logging to file
  • -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 claude --preset detailed

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

git-iris gen --print

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

Generating a Changelog

Git-Iris can generate changelogs between two 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)
  • --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

Example:

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

This command generates a detailed changelog of changes between versions 1.0.0 and 1.1.0, including Gitmoji.

Generating Release Notes

Git-Iris can also generate 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)
  • --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

Example:

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

This command generates standard-level release notes between versions 1.0.0 and 1.1.0 using the conventional commits preset.

🎛️ 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.

Some key presets include:

  • default: Standard commit message style
  • conventional: Follows the Conventional Commits specification
  • detailed: Provides more context and explanation in commit messages
  • concise: Short and to-the-point commit messages
  • cosmic: Mystical, space-themed commit messages
  • ..and lots more styles

To use a preset for a single commit:

git-iris gen --preset conventional

To set a default preset for all commits:

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

  1. Ticket Number Integration

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

  2. Language-Specific Conventions

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

  3. Team-Specific Guidelines

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

  4. Project-Specific Context

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

  5. 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

💖 Acknowledgements

  • OpenAI and Anthropic for their cutting-edge language models
  • The Rust community for the robust ecosystem and tooling

Created by Stefanie Jane 🌠

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