git-smart-squash 4.0.1

Automatically reorganize messy git commit histories into clean, semantic commits

Git Smart Squash

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

The Problem

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.

The Solution

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

Quick Start

1. Install

# 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

2. Set up AI

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"

3. Run

cd your-repo
git-smart-squash

That's it. Review the plan and approve.

Command Line Parameters

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

Recommended Models

Default Models

• 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)

Model Selection

# 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

Migration: OpenAI to GPT-5 (Responses API)

• 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
• 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 high

Custom Instructions

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

Examples

# 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"

Tips for Better Results

• 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

Common Use Cases

"I need to clean up before PR review"

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

"I work with a different main branch"

git-smart-squash --base develop

"I want to use a specific AI provider"

git-smart-squash --ai-provider openai

Safety

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]

AI Providers

Provider	Cost	Privacy
Ollama	Free	Local
OpenAI	~$0.01	Cloud
Anthropic	~$0.01	Cloud
Gemini	~$0.01	Cloud

Advanced Configuration (Optional)

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 project

Global 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 projects

Troubleshooting

"Invalid JSON" Error

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

Model Not Following Instructions

Some models struggle with complex instructions:

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

"Ollama not found"

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

Poor Commit Grouping

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

Installation Issues (Mac)

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

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

"No changes to reorganize"

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

Large Diffs / Token Limits

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

Need More Help?

Check out our detailed documentation or open an issue!

License

MIT License - see LICENSE file for details.