gitwhisper #

[coverage]

Generated by the Very Good CLI 🤖

Git Whisper is an AI-powered Git commit message generator that whispers the perfect commit message based on your staged changes.

Getting Started 🚀 #

If the CLI application is available on pub, activate globally via:

dart pub global activate gitwhisper

Or locally via:

dart pub global activate --source=path <path to this package>

, claude-3-opus, etc.)

• 🔑 Securely saves API keys for future use
• 🔌 Supports multiple AI models:
  • Claude (Anthropic)
  • OpenAI (GPT)
  • Gemini (Google)
  • Grok (xAI)
  • Llama (Meta)
  • Deepseek (DeepSeek, Inc.)

Usage #

# Generate a commit message (main command)
gitwhisper commit --model openai
gitwhisper # shorthand for 'gitwhisper commit' - runs commit command by default
gw # even shorter command - also runs 'gitwhisper commit' by default

# Choose a specific model variant
gitwhisper commit --model openai --model-variant gpt-4o

# Add a ticket number prefix to your commit message
gitwhisper commit --prefix "JIRA-123"

# Use a specific template for formatting
gitwhisper commit --template "detailed"

# List available models
gitwhisper list-models

# List available variants for a specific model
gitwhisper list-variants --model claude

# Save an API key for future use
gitwhisper save-key --model claude --key "your-claude-key"

# Set defaults
gitwhisper set-defaults --model openai --model-variant gpt-4o --template default

# Clear defaults
gitwhisper clear-defaults

# Template management
gitwhisper template list                                  # List all templates
gitwhisper template add --name "custom" --format "{{type}}: {{emoji}} {{description}}"  # Add template
gitwhisper template show --name "default"                # Show template details
gitwhisper template delete --name "custom"               # Delete a template

# Get help
gitwhisper --help

Shorter Command #

Instead of using the full gitwhisper command you can also use the shortened one gw. Both gitwhisper and gw without any subcommands will automatically run the commit command by default.

Command Structure #

GitWhisper uses a command-based structure:

• commit: Generate and apply a commit message (main command)
• list-models: Show all supported AI models
• list-variants: Show available variants for each AI model
• save-key: Store an API key for future use
• update: Update GitWhisper to the latest version
• set-defaults: Set default model, variant and template for future use
• clear-defaults: Clear any set default preferences
• template: Manage commit message templates
  • template list: Show all available templates
  • template add: Add or update a template
  • template show: Show a specific template
  • template delete: Delete a template

API Keys #

You can provide API keys in several ways:

1. Command line argument: --key "your-api-key"
2. Environment variables:
   • ANTHROPIC_API_KEY (for Claude)
   • OPENAI_API_KEY (for OpenAI)
   • GEMINI_API_KEY (for Gemini)
   • GROK_API_KEY (for Grok)
   • LLAMA_API_KEY (for Llama)
3. Saved configuration: Use the save-key command to store your API key permanently

Model Variants #

GitWhisper supports a comprehensive range of model variants:

OpenAI #

• gpt-4 (default)
• gpt-4-turbo-2024-04-09
• gpt-4o
• gpt-4o-mini
• gpt-4.5-preview
• gpt-3.5-turbo-0125
• gpt-3.5-turbo-instruct
• o1-preview
• o1-mini
• o3-mini

Claude (Anthropic) #

• claude-3-opus-20240307 (default)
• claude-3-sonnet-20240307
• claude-3-haiku-20240307
• claude-3-5-sonnet-20240620
• claude-3-5-sonnet-20241022
• claude-3-7-sonnet-20250219

Gemini (Google) #

• gemini-1.0-pro (default)
• gemini-1.0-ultra
• gemini-1.5-pro-002
• gemini-1.5-flash-002
• gemini-1.5-flash-8b
• gemini-2.0-pro
• gemini-2.0-flash
• gemini-2.0-flash-lite
• gemini-2.0-flash-thinking

Grok (xAI) #

• grok-1 (default)
• grok-2
• grok-3
• grok-2-mini

Llama (Meta) #

• llama-3-70b-instruct (default)
• llama-3-8b-instruct
• llama-3.1-8b-instruct
• llama-3.1-70b-instruct
• llama-3.1-405b-instruct
• llama-3.2-1b-instruct
• llama-3.2-3b-instruct
• llama-3.3-70b-instruct

Deekseek (DeepSeek, Inc.) #

• deekseek-chat (default)
• deepseek-reasoner

GitHub (Free to use models) - rate limited #

• gpt-4o (default)
• Llama-3.3-70B-Instruct
• DeepSeek-R1
• etc - Check for more here https://github.com/marketplace?type=models

To run GitHub models you may need the following:

To authenticate with the model you will need to generate a personal access token (PAT) in your GitHub settings. Create your PAT token by following instructions here: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens

How It Works #

Git Whisper:

1. Checks if you have staged changes in your repository
2. Retrieves the diff of your staged changes
3. Sends the diff to the selected AI model
4. Generates a commit message following the conventional commit format with emojis
5. Applies any prefix/ticket number if specified
6. Submits the commit with the generated message

Configuration #

Configuration is stored in ~/.git_whisper.yaml and contains your saved API keys and default settings:

api_keys:
  claude: "your-claude-key"
  openai: "your-openai-key"
  # ...
default_model: "openai"
default_variant: "gpt-4o"
default_template: "detailed"

Templates are stored in ~/.git_whisper_templates.json:

{
  "default": "{{type}}: {{emoji}} {{description}}",
  "detailed": "[{{prefix}}] {{type}}({{scope}}): {{emoji}} {{description}}",
  "simple": "{{type}}: {{description}}"
}

Requirements #

• Dart SDK (^3.5.0)
• Git installed and available in your PATH

Conventional Commit Format #

Git Whisper generates commit messages following the conventional commit format with emojis:

<type>([scope]): <emoji> <description>

With prefix option:

<type>([scope]): <emoji> PREFIX-123 -> <description>

Common types and their emojis include:

• feat: ✨ New feature
• fix: 🐛 Bug fix
• docs: 📚 Documentation changes
• style: 💄 Code style changes (formatting, etc.)
• refactor: ♻️ Code changes that neither fix bugs nor add features
• test: 🧪 Adding or fixing tests
• chore: 🔧 Changes to the build process or auxiliary tools
• perf: ⚡ Performance improvements
• ci: 👷 CI/CD related changes
• build: 📦 Changes affecting build system or dependencies
• revert: ⏪ Reverting a previous commit

Custom Templates #

You can create custom templates for commit messages to fit your team's workflow:

gitwhisper template add --name "detailed" --format "[{{prefix}}] {{type}}({{scope}}): {{emoji}} {{description}}"

Available template placeholders:

• {{type}} - Commit type (feat, fix, etc.)
• {{scope}} - Optional commit scope (auth, ui, etc.)
• {{emoji}} - Type-specific emoji
• {{description}} - Commit description
• {{prefix}} - User-specified prefix (e.g., ticket number)

Example template formats:

• "[{{prefix}}] {{type}}({{scope}}): {{emoji}} {{description}}"
• "{{emoji}} {{type}}: {{description}}"
• "{{type}}: {{prefix}} - {{description}}"
• "{{type}}({{scope}}): {{description}} ({{prefix}})"

Use templates when generating commit messages:

gitwhisper commit --template "detailed"

Set a default template:

gitwhisper set-defaults --template "detailed"

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License #

This project is licensed under the MIT License - see the LICENSE file for details.