# 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:
```bash
# 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
```bash
# 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)**
```bash
# Install Ollama from https://ollama.com
ollama pull devstral # Default model
```
**Option B: Cloud (Better results)**
```bash
export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
```
### 3. Run
```bash
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` |
## Recommended Models
### Default Models
- **OpenAI**: `gpt-4.1` (default)
- **Anthropic**: `claude-sonnet-4-20250514` (default)
- **Gemini**: `gemini-2.5-pro` (default)
- **Local/Ollama**: `devstral` (default)
### Model Selection
```bash
# 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
```
## Custom Instructions
The `--instructions` parameter lets you control how commits are organized:
### Examples
```bash
# 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"
```bash
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"
```bash
git-smart-squash --base develop
```
### "I want to use a specific AI provider"
```bash
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:**
```bash
# 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):
```yaml
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`):
```yaml
ai:
provider: local # Always use local AI by default
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-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"
### "Ollama not found"
```bash
# 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:
```bash
# Using pipx (recommended)
brew install pipx
pipx install git-smart-squash
```
### "No changes to reorganize"
```bash
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](DOCUMENTATION.md) or open an issue!
## License
MIT License - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/edverma/git-smart-squash",
"name": "git-smart-squash",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "git, commit, squash, rebase, conventional-commits, ai",
"author": "Evan Verma",
"author_email": "edverma@icloud.com",
"download_url": "https://files.pythonhosted.org/packages/3d/c2/d11c37467a0b57cf6bf5e4244932e4bb924bc1ff26f3ec990cb7962f7bfc/git_smart_squash-3.7.1.tar.gz",
"platform": null,
"description": "# Git Smart Squash\n\nStop wasting time manually reorganizing commits. Let AI do it for you.\n\n## The Problem\n\nYou'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.\n\n## The Solution\n\nGit Smart Squash analyzes your changes and reorganizes them into logical commits with proper messages:\n\n```bash\n# Before: your messy branch\n* fix tests\n* typo \n* more auth changes\n* WIP: working on auth\n* update tests\n* initial auth implementation\n\n# After: clean, logical commits\n* feat: implement JWT authentication system\n* test: add auth endpoint coverage\n```\n\n## Quick Start\n\n### 1. Install\n\n```bash\n# Using pip\npip install git-smart-squash\n\n# Using pipx (recommended for isolated install)\npipx install git-smart-squash\n\n# Using uv (fast Python package manager)\nuv tool install git-smart-squash\n```\n\n### 2. Set up AI\n\n**Option A: Local (Free, Private)**\n```bash\n# Install Ollama from https://ollama.com\nollama pull devstral # Default model\n```\n\n**Option B: Cloud (Better results)**\n```bash\nexport OPENAI_API_KEY=\"your-key\"\nexport ANTHROPIC_API_KEY=\"your-key\"\nexport GEMINI_API_KEY=\"your-key\"\n```\n\n### 3. Run\n\n```bash\ncd your-repo\ngit-smart-squash\n```\n\nThat's it. Review the plan and approve.\n\n## Command Line Parameters\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| `--base` | Base branch to compare against | Config file or `main` |\n| `--ai-provider` | AI provider to use (openai, anthropic, local, gemini) | Configured in settings |\n| `--model` | Specific AI model to use (see recommended models below) | Provider default |\n| `--config` | Path to custom configuration file | `.git-smart-squash.yml` or `~/.git-smart-squash.yml` |\n| `--auto-apply` | Apply commit plan without confirmation prompt | `false` |\n| `--instructions`, `-i` | Custom instructions for AI (e.g., \"Group by feature area\") | None |\n| `--no-attribution` | Disable attribution message in commits | `false` |\n| `--debug` | Enable debug logging for detailed information | `false` |\n\n## Recommended Models\n\n### Default Models\n- **OpenAI**: `gpt-4.1` (default)\n- **Anthropic**: `claude-sonnet-4-20250514` (default)\n- **Gemini**: `gemini-2.5-pro` (default)\n- **Local/Ollama**: `devstral` (default)\n\n### Model Selection\n```bash\n# Specify a different model\ngit-smart-squash --ai-provider openai --model gpt-4.1-mini\n\n# For local Ollama\ngit-smart-squash --ai-provider local --model llama-3.1\n```\n\n## Custom Instructions\n\nThe `--instructions` parameter lets you control how commits are organized:\n\n### Examples\n```bash\n# Add ticket prefixes\ngit-smart-squash -i \"Prefix all commits with [ABC-1234]\"\n\n# Separate by type\ngit-smart-squash -i \"Keep backend and frontend changes in separate commits\"\n\n# Limit commit count\ngit-smart-squash -i \"Create at most 3 commits total\"\n```\n\n### Tips for Better Results\n- **Be specific**: \"Group database migrations separately\" works better than \"organize nicely\"\n- **One instruction at a time**: Complex multi-part instructions may be partially ignored\n- **Use better models**: Larger models follow instructions more reliably than smaller models\n\n## Common Use Cases\n\n### \"I need to clean up before PR review\"\n```bash\ngit-smart-squash # Shows plan and prompts for confirmation\ngit-smart-squash --auto-apply # Auto-applies without prompting\n```\n\n### \"I work with a different main branch\"\n```bash\ngit-smart-squash --base develop\n```\n\n### \"I want to use a specific AI provider\"\n```bash\ngit-smart-squash --ai-provider openai\n```\n\n## Safety\n\n**Your code is safe:**\n- Shows plan before making changes\n- Creates automatic backup branch\n- Requires clean working directory\n- Never pushes without your command\n\n**If something goes wrong:**\n```bash\n# Find backup\ngit branch | grep backup\n\n# Restore\ngit reset --hard your-branch-backup-[timestamp]\n```\n\n## AI Providers\n\n| Provider | Cost | Privacy |\n|----------|------|---------|\n| **Ollama** | Free | Local |\n| **OpenAI** | ~$0.01 | Cloud |\n| **Anthropic** | ~$0.01 | Cloud |\n| **Gemini** | ~$0.01 | Cloud |\n\n## Advanced Configuration (Optional)\n\nWant to customize? Create a config file:\n\n**Project-specific** (`.git-smart-squash.yml` in your repo):\n```yaml\nai:\n provider: openai # Use OpenAI for this project\nbase: develop # Use develop as the base branch for this project\n```\n\n**Global default** (`~/.git-smart-squash.yml`):\n```yaml\nai:\n provider: local # Always use local AI by default\nbase: main # Default base branch for all projects\n```\n\n## Troubleshooting\n\n### \"Invalid JSON\" Error\nThis usually means the AI model couldn't format the response properly:\n- **With Ollama**: Switch from `llama2` to `mistral` or `mixtral`\n- **Solution**: `ollama pull mistral` then retry\n- **Alternative**: Use a cloud provider with `--ai-provider openai`\n\n### Model Not Following Instructions\nSome models struggle with complex instructions:\n- **Use better models**: `--model gpt-4-turbo` or `--model claude-3-opus`\n- **Simplify instructions**: One clear directive works better than multiple\n- **Be explicit**: \"Prefix with [ABC-123]\" not \"add ticket number\"\n\n### \"Ollama not found\" \n```bash\n# Install from https://ollama.com\nollama serve\nollama pull devstral # Default model\n```\n\n### Poor Commit Grouping\nIf the AI creates too many commits or doesn't group well:\n- **Insufficient model**: Use a larger model\n- **Add instructions**: `-i \"Group related changes, max 3 commits\"`\n- **Provide Feedback**: Create an issue on GitHub and let us know what happened\n\n### Installation Issues (Mac)\nIf you don't have pip or prefer isolated installs:\n```bash\n# Using pipx (recommended)\nbrew install pipx\npipx install git-smart-squash\n```\n\n### \"No changes to reorganize\"\n```bash\ngit log --oneline main..HEAD # Check you have commits\ngit diff main # Check you have changes\n```\n\n### Large Diffs / Token Limits\nLocal models have a ~32k token limit. For large changes:\n- Use `--base` with a more recent commit\n- Switch to cloud: `--ai-provider openai`\n- Split into smaller PRs\n\n### Need More Help?\n\nCheck out our [detailed documentation](DOCUMENTATION.md) or open an issue!\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Automatically reorganize messy git commit histories into clean, semantic commits",
"version": "3.7.1",
"project_urls": {
"Bug Reports": "https://github.com/edverma/git-smart-squash/issues",
"Documentation": "https://github.com/edverma/git-smart-squash#readme",
"Homepage": "https://github.com/edverma/git-smart-squash",
"Source": "https://github.com/edverma/git-smart-squash"
},
"split_keywords": [
"git",
" commit",
" squash",
" rebase",
" conventional-commits",
" ai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dd7241e32b3617aa4ad86ad0b4f2b38e3f78e46c0e2849b06d3486d47db22e84",
"md5": "f79a02095eb707b78e836c9366cdbd07",
"sha256": "661c1ec0a99df497fbe67bfbd957d45d3d5a7bba1265e2e2320c5649e5082ee7"
},
"downloads": -1,
"filename": "git_smart_squash-3.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f79a02095eb707b78e836c9366cdbd07",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 98040,
"upload_time": "2025-07-10T03:36:19",
"upload_time_iso_8601": "2025-07-10T03:36:19.131011Z",
"url": "https://files.pythonhosted.org/packages/dd/72/41e32b3617aa4ad86ad0b4f2b38e3f78e46c0e2849b06d3486d47db22e84/git_smart_squash-3.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3dc2d11c37467a0b57cf6bf5e4244932e4bb924bc1ff26f3ec990cb7962f7bfc",
"md5": "e56117d2f3f8f50c7004e861a4ca9d51",
"sha256": "d3e2eaece17dd3c60ffe40dac4c65e784ffefcd730f031a6bb031b895bc1276b"
},
"downloads": -1,
"filename": "git_smart_squash-3.7.1.tar.gz",
"has_sig": false,
"md5_digest": "e56117d2f3f8f50c7004e861a4ca9d51",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 89908,
"upload_time": "2025-07-10T03:36:23",
"upload_time_iso_8601": "2025-07-10T03:36:23.447271Z",
"url": "https://files.pythonhosted.org/packages/3d/c2/d11c37467a0b57cf6bf5e4244932e4bb924bc1ff26f3ec990cb7962f7bfc/git_smart_squash-3.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 03:36:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "edverma",
"github_project": "git-smart-squash",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "openai",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "anthropic",
"specs": [
[
">=",
"0.3.0"
]
]
},
{
"name": "tiktoken",
"specs": [
[
">=",
"0.5.0"
]
]
},
{
"name": "google-generativeai",
"specs": [
[
">=",
"0.8.5"
]
]
}
],
"lcname": "git-smart-squash"
}
JSON
