git-autosquash¶

Automatically squash changes back into historical commits where they belong.

git-autosquash is a powerful tool that analyzes your working directory changes and automatically distributes them back to the commits where those code sections were last modified. Instead of creating noisy "fix lint errors", "cleanup tests", or "address review feedback" commits, it uses git blame analysis to intelligently squash improvements back into their logical historical commits.

Common scenario: You've been working on a feature branch and now need to fix lint errors, test failures, or code review feedback. Rather than committing all fixes into a final "cleanup" commit, git-autosquash lets you push each fix back to the original commit that introduced the issue, maintaining clean and logical git history.

✨ Key Features¶

• 🎯 Smart Targeting: Uses git blame to find the exact commits where code was last modified
• 🖥️ Interactive TUI: Rich terminal interface with syntax-highlighted diff viewer
• 🔒 Safety First: Default unapproved state with user confirmation for all changes
• ⚡ Conflict Resolution: Clear guidance when merge conflicts occur during rebase
• 📊 Progress Tracking: Real-time feedback with detailed commit summaries
• 🔄 Rollback Support: Automatic cleanup and restoration on errors or interruption

🚀 Quick Start¶

Installation¶

uv tool install git-autosquash

pipx install git-autosquash

pip install git-autosquash

Basic Usage¶

1. Make changes to your codebase
2. Run git-autosquash to analyze and distribute changes:

git-autosquash

1. Review the proposed hunk → commit mappings in the interactive TUI
2. Approve changes you want to squash back into their target commits
3. Let git-autosquash perform the interactive rebase automatically

🎬 How It Works¶

graph TD
    A[Working Directory Changes] --> B[Parse Git Diff into Hunks]
    B --> C[Run Git Blame Analysis]
    C --> D[Find Target Commits for Each Hunk]
    D --> E[Interactive TUI Approval]
    E --> F[Group Hunks by Target Commit]
    F --> G[Execute Interactive Rebase]
    G --> H[Distribute Changes to History]

    E -.-> I[Cancel/Abort]
    G -.-> J[Conflict Resolution]
    J -.-> K[User Fixes Conflicts]
    K --> G

📋 Example Workflow¶

Imagine you've been working on a feature and made several changes across different files. Some of these changes are bug fixes that should go back to earlier commits, while others are new feature additions.

$ git status
On branch feature/user-auth
Changes not staged for commit:
  modified:   src/auth/login.py      # Bug fix for validation
  modified:   src/auth/session.py    # Performance improvement  
  modified:   src/ui/dashboard.py    # New feature code

$ git-autosquash
Current branch: feature/user-auth
Merge base: abc123def

Analyzing changes and finding target commits...
Found 3 hunks to process
Found target commits for 3 hunks

Launching interactive approval interface...

The TUI will show you exactly which changes can go back to which commits, with confidence levels and clear diff visualization.

🎯 Use Cases¶

• Bug fixes: Automatically squash fixes back to the commits that introduced bugs
• Refactoring: Distribute code improvements back to their logical commits
• Code cleanup: Move formatting and style changes to appropriate historical points
• Feature development: Separate bug fixes from new features during development
• Commit message fixes: Clean up commit history by moving changes to better locations
• Selective uncommit: Extract accidentally committed code back to working tree while preserving clean history

🛡️ Safety Features¶

git-autosquash is designed with safety as the top priority:

• Default rejection: All changes start as unapproved, requiring explicit user consent
• Conflict detection: Clear guidance when rebase conflicts occur
• Automatic rollback: Repository restored to original state on errors or interruption
• Branch validation: Only works on feature branches with clear merge-base
• Stash management: Safely handles mixed staged/unstaged states
• Comprehensive testing: 121+ tests covering all edge cases and failure modes

📚 Next Steps¶

• Installation Guide - Detailed setup instructions
• Getting Started - Your first git-autosquash workflow
• Basic Workflow - Common usage patterns
• Advanced Usage - Power user features
• Examples - Real-world scenarios and solutions

🤝 Contributing¶

git-autosquash is open source and welcomes contributions! Check out our:

• Development Guide - Set up development environment
• Architecture Overview - Understand the codebase
• Testing Guide - Run and write tests

📄 License¶

MIT License - see LICENSE for details.