Skip to main content

​
Before you begin

Make sure you have:
  • GitWhisper installed (installation guide)
  • Git installed and accessible in your PATH
  • A Git repository to work with
You can use the free model (no API key required) to try GitWhisper instantly, or set up your preferred AI provider for the best experience.

​
Using the free model (no setup required)

The fastest way to try GitWhisper is with the free model powered by LLM7.io:
1

Make some changes to your code

# Create or modify some files
echo "console.log('Hello GitWhisper');" > app.js
2

Stage your changes

git add app.js
3

Generate commit with free model

gw commit --model free
On first use, you’ll see a disclaimer about the free model. Accept the terms to continue.
4

Review and commit

GitWhisper will analyze your changes and present a commit message. Choose to:
  • commit - Use the message as-is
  • edit - Modify the message in your editor
  • retry - Generate a new message
  • discard - Cancel the commit
The free model has limits: 8k chars per request, 60 requests/hour. For production use, set up a paid API provider.

​
Set up with your AI provider

For the best experience with unlimited usage, configure your preferred AI model:

​
OpenAI (GPT models)

1

Get an OpenAI API key

Visit OpenAI’s platform and create an API key
2

Save your API key

gw save-key --model openai --key "sk-..."
3

Set as default (optional)

gw set-defaults --model openai --model-variant gpt-4o
4

Test it out

# Make some changes
echo "function hello() { return 'world'; }" > utils.js
git add utils.js

# Generate commit (uses your defaults)
gw
Available variants: gpt-4, gpt-4o, gpt-4o-mini, gpt-4.5-preview, gpt-3.5-turbo, o1-preview, o1-mini, o3-mini

​
Your first commit

Let’s create your first AI-generated commit with a real-world example:
1

Create a new file or modify existing code

# Example: Add a new authentication function
cat << 'EOF' > auth.js
export function authenticateUser(username, password) {
  if (!username || !password) {
    throw new Error('Username and password are required');
  }
  
  // Hash password and verify against database
  const hashedPassword = hashPassword(password);
  return verifyCredentials(username, hashedPassword);
}

function hashPassword(password) {
  // Implementation details...
  return btoa(password);
}
EOF
2

Stage your changes

git add auth.js
3

Run GitWhisper

# Use the short alias
gw

# Or the full command
gitwhisper commit

# Or specify a model
gw commit --model openai --model-variant gpt-4o
4

Review the generated message

GitWhisper will display something like:
🔮 Analyzing your changes...
✨ Generated commit message:

---------------------------------
feat: ✨ Add user authentication function

Implement authenticateUser function with password hashing
and credential verification for secure user login
---------------------------------

What would you like to do with this commit message?
[commit] | edit | retry | discard:
5

Choose an action

  • Type commit (or press Enter) to use the message
  • Type edit to modify in your Git editor
  • Type retry to:
    • Generate a new message with the same model
    • Try a different AI model
    • Add custom context for the AI
  • Type discard to cancel
6

Commit is created

✅ Commit created successfully!
[main a1b2c3d] feat: ✨ Add user authentication function
 1 file changed, 15 insertions(+)
 create mode 100644 auth.js

​
Common workflows

​
Basic commit

# Make changes
echo "const VERSION = '1.0.0';" > version.js

# Stage and commit
git add version.js
gw

​
Commit with ticket number

# Add JIRA ticket prefix
git add src/
gw commit --prefix "JIRA-123"

# Result: feat: ✨ JIRA-123 -> Add new dashboard component

​
Commit and auto-push

# Stage changes
git add .

# Commit and push in one command
gw commit --auto-push
# or shorthand
gw commit -a

​
Create a tagged release

# Stage changes
git add CHANGELOG.md package.json

# Commit with a git tag
gw commit --tag v1.2.0

# Commit, tag, and push everything
gw commit --tag v1.2.0 --auto-push

​
Analyze changes before committing

# Stage your changes
git add .

# Get AI analysis and suggestions
gw analyze

# Review the feedback, then commit
gw commit

​
Use specific model variant

# Use Claude 3.5 Sonnet
gw commit --model claude --model-variant claude-3-5-sonnet-20241022

# Use GPT-4o
gw commit --model openai --model-variant gpt-4o

# Use Gemini 2.5 Pro
gw commit --model gemini --model-variant gemini-2.5-pro-preview-05-06

​
Interactive commit workflow

GitWhisper provides an interactive workflow for reviewing and refining commit messages: 
gw commit
1

Review generated message

GitWhisper shows you the AI-generated commit message
2

Choose your action

Available options:
  • commit - Accept and commit with this message
  • edit - Open your Git editor to modify the message
  • retry - Generate a new message:
    • With the same model (for variations)
    • With a different model (to compare approaches)
    • With additional context (guide the AI with instructions)
  • discard - Cancel and exit without committing
3

Refine as needed

Keep iterating until you’re happy with the message
Use the retry option with “add context” to guide the AI. For example: “make it more technical” or “focus on performance improvements”.

​
Tips for better commit messages

The AI analyzes your code structure. Clear naming helps generate better messages:
// Good: Clear, descriptive naming
function authenticateUser(credentials) { ... }

// Less helpful for AI
function doAuth(data) { ... }
Different AI models excel at different things:
  • OpenAI GPT-4o: Great all-rounder, detailed descriptions
  • Claude 3.5 Sonnet: Excellent for code understanding, concise
  • Gemini 2.0 Flash: Fast, good for quick commits
  • Free model: Perfect for trying out or personal projects
Integrate with your team’s workflow using prefixes:
# JIRA integration
gw commit --prefix "PROJ-456"

# GitHub issues
gw commit --prefix "#123"

# Custom prefixes
gw commit --prefix "HOTFIX"
Save time by configuring your preferences once:
# Set your favorite model and variant
gw set-defaults --model openai --model-variant gpt-4o

# View current settings
gw show-defaults

# Now just use 'gw' without specifying model
gw commit

​
Environment variables

Instead of saving API keys, you can use environment variables: 
# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."

# Google Gemini
export GEMINI_API_KEY="AIza..."

# xAI Grok
export GROK_API_KEY="xai-..."

# Meta Llama
export LLAMA_API_KEY="..."

# DeepSeek
export DEEPSEEK_API_KEY="..."

# Then use GitWhisper without --key flag
gw commit --model openai
Add these to your ~/.bashrc, ~/.zshrc, or equivalent for persistent configuration.

​
Troubleshooting

GitWhisper needs staged changes to analyze:
# Check status
git status

# Stage your changes
git add <files>

# Or enable auto-staging
gw always-add true
Verify your API key is saved correctly:
# Check saved configuration
gw show-config

# Re-save your key
gw save-key --model openai --key "your-key"

# Or use environment variable
export OPENAI_API_KEY="your-key"
Try these steps:
  1. Check your internet connection
  2. Verify API key has sufficient credits/quota
  3. Try a different model: 
    gw commit --model free
  4. For Ollama, ensure the service is running: 
    ollama list
For very large changesets, GitWhisper automatically processes files individually:
# Adjust max diff size (default: 50000 chars)
gw set-defaults --max-diff-size 100000

# Or commit files in smaller batches
git add specific-file.js
gw commit

​
Next steps

Explore all commands

Learn about analyze, list-models, change-language, and more

Configure GitWhisper

Customize defaults, language preferences, and advanced settings

AI models guide

Compare models, variants, and choose the best for your needs

Best practices

Tips and workflows for effective commit messages

Build docs developers (and LLMs) love

Get started for freeTalk to us