Stop wasting time manually reorganizing commits. Let AI do it for you.

You've been there: 15 commits for a feature, half of them are "fix", "typo", or "WIP". Now you need to clean it up for PR review. Manually squashing and rewriting is tedious.

Git Smart Squash analyzes your changes and reorganizes them into logical commits with proper messages:

# Before: your messy branch
* fix tests
* typo  
* more auth changes
* WIP: working on auth
* update tests
* initial auth implementation

# After: clean, logical commits
* feat: implement JWT authentication system
* test: add auth endpoint coverage

# Using pip
pip install git-smart-squash

# Using pipx (recommended for isolated install)
pipx install git-smart-squash

# Using uv (fast Python package manager)
uv tool install git-smart-squash

Option A: Local (Free, Private)

# Install Ollama from https://ollama.com
ollama pull devstral  # Default model

Option B: Cloud (Better results)

export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export GEMINI_API_KEY="your-key"

cd your-repo
git-smart-squash

That's it. Review the plan and approve.

• OpenAI: gpt-4.1 (default)
• Anthropic: claude-sonnet-4-20250514 (default)
• Gemini: gemini-2.5-pro (default)
• Local/Ollama: devstral (default)

# Specify a different model
git-smart-squash --ai-provider openai --model gpt-4.1-mini

# For local Ollama
git-smart-squash --ai-provider local --model llama-3.1

The --instructions parameter lets you control how commits are organized:

# Add ticket prefixes
git-smart-squash -i "Prefix all commits with [ABC-1234]"

# Separate by type
git-smart-squash -i "Keep backend and frontend changes in separate commits"

# Limit commit count
git-smart-squash -i "Create at most 3 commits total"

• Be specific: "Group database migrations separately" works better than "organize nicely"
• One instruction at a time: Complex multi-part instructions may be partially ignored
• Use better models: Larger models follow instructions more reliably than smaller models

git-smart-squash              # Shows plan and prompts for confirmation
git-smart-squash --auto-apply # Auto-applies without prompting

git-smart-squash --base develop

git-smart-squash --ai-provider openai

Your code is safe:

• Shows plan before making changes
• Creates automatic backup branch
• Requires clean working directory
• Never pushes without your command

If something goes wrong:

# Find backup
git branch | grep backup

# Restore
git reset --hard your-branch-backup-[timestamp]

Want to customize? Create a config file:

Project-specific (.git-smart-squash.yml in your repo):

ai:
  provider: openai  # Use OpenAI for this project
base: develop       # Use develop as the base branch for this project

Global default (~/.git-smart-squash.yml):

ai:
  provider: local   # Always use local AI by default
base: main          # Default base branch for all projects

This usually means the AI model couldn't format the response properly:

• With Ollama: Switch from llama2 to mistral or mixtral
• Solution: ollama pull mistral then retry
• Alternative: Use a cloud provider with --ai-provider openai

Some models struggle with complex instructions:

• Use better models: --model gpt-4-turbo or --model claude-3-opus
• Simplify instructions: One clear directive works better than multiple
• Be explicit: "Prefix with [ABC-123]" not "add ticket number"

# Install from https://ollama.com
ollama serve
ollama pull devstral  # Default model

If the AI creates too many commits or doesn't group well:

• Insufficient model: Use a larger model
• Add instructions: -i "Group related changes, max 3 commits"
• Provide Feedback: Create an issue on GitHub and let us know what happened

If you don't have pip or prefer isolated installs:

# Using pipx (recommended)
brew install pipx
pipx install git-smart-squash

git log --oneline main..HEAD  # Check you have commits
git diff main                 # Check you have changes

Local models have a ~32k token limit. For large changes:

• Use --base with a more recent commit
• Switch to cloud: --ai-provider openai
• Split into smaller PRs

Check out our detailed documentation or open an issue!

MIT License - see LICENSE file for details.