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-squashOption A: Local (Free, Private)
# Install Ollama from https://ollama.com
ollama pull devstral # Default modelOption 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-squashThat's it. Review the plan and approve.
| Parameter | Description | Default |
|---|---|---|
--base |
Base branch to compare against | Config file or main |
--ai-provider |
AI provider to use (openai, anthropic, local, gemini) | Configured in settings |
--model |
Specific AI model to use (see recommended models below) | Provider default |
--config |
Path to custom configuration file | .git-smart-squash.yml or ~/.git-smart-squash.yml |
--auto-apply |
Apply commit plan without confirmation prompt | false |
--instructions, -i |
Custom instructions for AI (e.g., "Group by feature area") | None |
--no-attribution |
Disable attribution message in commits | false |
--debug |
Enable debug logging for detailed information | false |
--reasoning |
Reasoning effort for GPT-5 (high, medium, low, minimal) | low |
--max-predict-tokens |
Maximum tokens for completion/output | 200000 |
- OpenAI:
gpt-5(default),gpt-5-mini,gpt-5-nano- Only GPT-5 models supported, default reasoning: low - 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-5-mini
# For local Ollama
git-smart-squash --ai-provider local --model llama-3.1- The OpenAI integration now uses the Responses API, supporting GPT‑5 models only.
- Supported models:
gpt-5(default),gpt-5-mini,gpt-5-nano. - You can control reasoning effort with
--reasoning(high | medium | low | minimal; default:low). - If you previously used GPT‑4.* models, switch to GPT‑5 or select another provider:
- OpenAI:
--ai-provider openai --model gpt-5 - Anthropic:
--ai-provider anthropic --model claude-sonnet-4-20250514 - Gemini:
--ai-provider gemini --model gemini-2.5-pro - Local (Ollama):
--ai-provider local --model devstral
- OpenAI:
- The CLI includes a gentle pre-check: if OpenAI is selected with a non‑GPT‑5 model, a helpful message is shown with guidance to migrate.
Example with reasoning:
git-smart-squash --ai-provider openai --model gpt-5 --reasoning highThe --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 promptinggit-smart-squash --base developgit-smart-squash --ai-provider openaiYour 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]| Provider | Cost | Privacy |
|---|---|---|
| Ollama | Free | Local |
| OpenAI | ~$0.01 | Cloud |
| Anthropic | ~$0.01 | Cloud |
| Gemini | ~$0.01 | Cloud |
Want to customize? Create a config file:
Project-specific (.git-smart-squash.yml in your repo):
ai:
provider: openai # Use OpenAI for this project
reasoning: medium # Use medium reasoning effort
max_predict_tokens: 100000 # Limit output to 100k tokens
base: develop # Use develop as the base branch for this projectGlobal default (~/.git-smart-squash.yml):
ai:
provider: local # Always use local AI by default
max_predict_tokens: 50000 # Conservative output limit for local models
base: main # Default base branch for all projectsThis usually means the AI model couldn't format the response properly:
- With Ollama: Switch from
llama2tomistralormixtral - Solution:
ollama pull mistralthen retry - Alternative: Use a cloud provider with
--ai-provider openai
Some models struggle with complex instructions:
- Use better models:
--model gpt-5or--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 modelIf 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-squashgit log --oneline main..HEAD # Check you have commits
git diff main # Check you have changesLocal models have a ~32k token limit. For large changes:
- Use
--basewith 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.