Commit Message Generation
Iris analyzes your staged changes and generates conventional commit messages that follow best practices, optionally enhanced with gitmoji for visual clarity.
Quick Example
# Stage your changes
git add src/auth.rs
# Generate commit message (interactive)
git-iris gen
# Or auto-commit with generated message
git-iris gen --auto-commit
# Just print the message without committing
git-iris gen --printCommand Reference
git-iris gen [FLAGS] [OPTIONS]Key Flags
| Flag | Description |
|---|---|
-a, --auto-commit | Automatically commit with generated message |
--amend | Amend the previous commit with currently staged changes |
-p, --print | Print message to stdout and exit (for scripting) |
--no-gitmoji | Disable emoji prefixes for this commit |
--no-verify | Skip pre/post-commit hooks |
-i, --instructions "text" | Custom instructions for message style |
--preset <name> | Use instruction preset (e.g., concise, detailed) |
Global Options
| Option | Description |
|---|---|
--provider <name> | Override LLM provider |
--model <name> | Override model for this operation |
-r, --repo <url> | Run against a remote repository URL instead of the local repo |
--critic / --no-critic | Run or skip the critic verification pass after generation (default: on) |
--debug | Show agent execution details |
--quiet | Suppress spinners and progress output |
Workflow Modes
Interactive Mode (Default)
Launches Studio in Commit mode with a full TUI:
git-iris gen- Edit generated message before committing
- View diff alongside message
- Chat with Iris to refine the message
- Press
Enterto commit (or amend, if amend mode is active);qto cancel
Auto-Commit Mode
Generate and commit in one step:
git-iris gen --auto-commitNote: Not available for remote repositories. Use --print instead.
Print Mode
Output message for scripting or manual use:
# Save to file
git-iris gen --print > commit-msg.txt
# Pipe to git commit
git-iris gen --print | git commit -F -
# Use in scripts
MSG=$(git-iris gen --print)
git commit -m "$MSG"Amend Mode
Rewrite the most recent commit message using the currently staged changes:
git add <newly fixed files>
git-iris gen --amend --auto-commit
# or preview without rewriting history:
git-iris gen --amend --print--amend currently requires --auto-commit or --print. Plain git-iris gen --amend (without one of those flags) prints a warning and exits — interactive Studio support for amend is coming later. Combine with --auto-commit to rewrite history in one step, or with --print to preview the new message first.
Message Format
Iris generates messages following this structure:
<emoji> <type>: <subject>
<body>Example:
✨ feat: Add JWT authentication middleware
Implements secure token-based authentication using RS256 signing.
Includes refresh token rotation and automatic expiry handling.Iris auto-detects whether a repository uses Conventional Commits by inspecting recent commit history; you can force a style with --preset conventional if detection picks the wrong one. When gitmoji is enabled and the title already starts with an emoji, Iris drops the duplicate so you get a single leading emoji rather than two stacked together.
Customizing Style
Using Presets
# Concise messages
git-iris gen --preset concise
# Detailed explanations
git-iris gen --preset detailed
# Technical focus
git-iris gen --preset technicalSee Presets for all available options.
Custom Instructions
git-iris gen --instructions "Focus on performance impacts"
git-iris gen --instructions "Include migration notes for breaking changes"Gitmoji Control
Disable Globally
Edit ~/.config/git-iris/config.toml:
use_gitmoji = falseDisable Per-Commit
git-iris gen --no-gitmojiEnable/Disable via Config
# Enable
git-iris config --gitmoji
# Disable
git-iris config --no-gitmojiHook Integration
Skip Verification
If you have pre-commit hooks that modify files or fail unexpectedly:
git-iris gen --auto-commit --no-verifyHook Workflow
Iris respects your Git hooks:
- Runs pre-commit hook before generating message
- If hook modifies staged files, regenerates message
- Runs commit-msg hook on generated message
- Runs post-commit hook after successful commit
Tips
For Large Changesets:
- Iris uses parallel subagent analysis for 20+ files
- Consider using
--preset conciseto keep messages focused - Split large changes into multiple commits when possible
For Scripting:
- Use
--printto integrate with CI/CD - Combine with
--quietto suppress all UI output - Use
--no-verifyonly when hooks are problematic
For Consistency:
- Set a default preset in your project config
- Use
--instructionsfor project-specific conventions - Configure gitmoji preference globally
Examples
# Standard workflow
git add .
git-iris gen
# Edit in Studio, then press Enter to commit
# Quick auto-commit
git add src/auth.rs
git-iris gen --auto-commit
# Concise style without emoji
git-iris gen --preset concise --no-gitmoji --print
# Detailed with custom focus
git-iris gen --preset detailed --instructions "Emphasize security changes"
# Debug agent execution
git-iris gen --debug --printError Handling
No Staged Changes:
⚠ No staged changes. Please stage your changes first.
→ Use 'git add <file>' or 'git add .'Remote Repository:
✗ Cannot automatically commit to a remote repository.
→ Use --print insteadPre-Commit Hook Failure: Iris will show the hook error and exit. Fix the issue and try again.