AI-powered git commit message rewriter using GPT

Automatically rewrite your entire git commit history with better, conventional commit messages using AI. Perfect for cleaning up messy commit histories before open-sourcing projects or improving repository maintainability.

This tool rewrites git history, which is generally NOT recommended for shared repositories!

When to use:

• Personal projects before making them public
• Feature branches before merging (with team agreement)
• Cleaning up local commits before pushing
• Preparing repositories for open-sourcing

When NOT to use:

• On shared branches without team coordination
• After pushing commits that others have pulled
• On main/master branches of team projects
• In repositories where commit hashes are referenced

Remember: Rewriting history changes commit hashes and requires force-pushing, which can disrupt your team's workflow.

• AI-Powered: Uses OpenAI's GPT models to generate meaningful commit messages
• One-Command Hook Setup: Install git hooks instantly with npx git-rewrite-commits --install-hooks
• Smart Detection: Automatically skips well-formed commits (can be disabled)
• Quality Scoring: Assesses commit quality and only fixes broken messages
• Custom Templates: Define your own commit format with --template
• Custom Prompts: Override AI behavior with --prompt for unique styles
• Multi-language: Generate messages in 20+ languages
• Conventional Commits: Follows conventional commit standards (feat, fix, docs, etc.)
• Safe: Automatically creates backup branches before rewriting
• Flexible: Supports dry-run mode to preview changes
• Customizable: Choose your preferred AI model and processing options
• Progress Tracking: Real-time progress indicators with colored output
• Efficient: Process only the last N commits for faster operation

You can run this tool directly with npx (no installation required):

Or install it globally:

npm install -g git-rewrite-commits

npm install -g @f/git-rewrite-commits --registry https://npm.pkg.github.com

Note: For GitHub Packages, you'll need to authenticate first:

npm login --registry=https://npm.pkg.github.com --scope=@f

One command to enable AI-powered commit messages:

npx git-rewrite-commits --install-hooks

That's it! Now you get:

• Automatic AI messages when you run git commit
• Post-commit improvement after each commit
• Pre-push review before pushing to remote

See QUICK_START.md for detailed setup guide

# Set your template format
git config hooks.commitTemplate "[JIRA-XXX] feat: message"

# Set language
git config hooks.commitLanguage "es"  # Spanish, French, etc.

Add to .git/hooks/post-commit to automatically improve your last commit message:

#!/bin/sh
# Automatically improve the last commit message after each commit
npx git-rewrite-commits --max-commits 1 --skip-backup --no-skip-well-formed

Make it executable: chmod +x .git/hooks/post-commit

Or use our ready-made hook: cp hooks/post-commit .git/hooks/

Add to .git/hooks/pre-push to fix commits before pushing:

#!/bin/sh
# Clean up the last 5 commits before pushing
echo "🔧 Improving commit messages before push..."
npx git-rewrite-commits --max-commits 5 --dry-run

echo "Apply changes? (y/n)"
read answer
if [ "$answer" = "y" ]; then
    npx git-rewrite-commits --max-commits 5
fi

Add to your ~/.gitconfig or ~/.zshrc/~/.bashrc:

# Git alias
git config --global alias.fix-commits '!npx git-rewrite-commits --max-commits'

# Usage: git fix-commits 3

# Shell alias
alias fix-last-commit='npx git-rewrite-commits --max-commits 1 --skip-backup'
alias fix-branch='npx git-rewrite-commits --max-commits 20'

# Usage: fix-last-commit

Before creating a pull request:

# 1. Check what needs fixing
npx git-rewrite-commits --dry-run --max-commits 10

# 2. Apply improvements
npx git-rewrite-commits --max-commits 10

# 3. Force push to your feature branch
git push --force-with-lease origin feature-branch

Add to your CI pipeline (e.g., GitHub Actions) for PR validation:

- name: Check Commit Quality
  run: |
    npx git-rewrite-commits --dry-run --max-commits ${{ github.event.pull_request.commits }}
    # This will show which commits would be improved

Before making a private repo public:

# Fix all commits with custom template
npx git-rewrite-commits \
  --template "feat(scope): message" \
  --language en \
  --no-skip-well-formed

# Review the changes
git log --oneline -20

# If satisfied, force push
git push --force-with-lease origin main

1. Set up your OpenAI API key:

   export OPENAI_API_KEY="your-api-key-here"

2. Install git hooks in your repository:

   cd your-repo
   npx git-rewrite-commits --install-hooks

3. That's it! Now just commit normally:

   git add .
   git commit  # AI message appears automatically!

1. Set up your OpenAI API key (same as above)

2. Navigate to your git repository:

3. Run the tool:

   npx git-rewrite-commits  # Rewrites all commits
   npx git-rewrite-commits --max-commits 10  # Only last 10

# Use with environment variable OPENAI_API_KEY
npx git-rewrite-commits

# Or provide API key directly
npx git-rewrite-commits --api-key "sk-..."

Options:
  -V, --version                 output the version number
  -k, --api-key <key>           OpenAI API key (defaults to OPENAI_API_KEY env var)
  -m, --model <model>           OpenAI model to use (default: "gpt-3.5-turbo")
  -b, --branch <branch>         Branch to rewrite (defaults to current branch)
  -d, --dry-run                 Show what would be changed without modifying repository
  -v, --verbose                 Show detailed output
  --max-commits <number>        Process only the last N commits
  --skip-backup                 Skip creating a backup branch (not recommended)
  --no-skip-well-formed         Process all commits, even well-formed ones
  --min-quality-score <score>   Minimum quality score (1-10) to consider well-formed (default: 7)
  -t, --template <format>       Custom commit message template (e.g., "(feat): message")
  -l, --language <lang>         Language for commit messages (default: "en")
  -p, --prompt <text>           Custom prompt for AI message generation
  --staged                      Generate a message for staged changes (for git hooks)
  --install-hooks               Install git hooks to the current repository
  -h, --help                    display help for command

# Preview changes without modifying history (recommended first step)
npx git-rewrite-commits --dry-run

# Use GPT-4 for better quality messages
npx git-rewrite-commits --model gpt-4

# Process only the last 10 commits (most recent)
npx git-rewrite-commits --max-commits 10

# Process ALL commits, including well-formed ones
npx git-rewrite-commits --no-skip-well-formed

# Set stricter quality threshold (8/10 instead of default 7/10)
npx git-rewrite-commits --min-quality-score 8

# Use custom commit format templates
npx git-rewrite-commits --template "(feat): message"
npx git-rewrite-commits --template "[JIRA-123] feat: message"
npx git-rewrite-commits --template "feat: message"

# Generate commit messages in different languages
npx git-rewrite-commits --language es  # Spanish
npx git-rewrite-commits --language fr  # French
npx git-rewrite-commits --language zh  # Chinese
npx git-rewrite-commits --language ja  # Japanese

# Generate message for staged changes (great for git hooks!)
npx git-rewrite-commits --staged
npx git-rewrite-commits --staged --template "[JIRA-123] feat: message"

# Use custom prompts for unique message styles
npx git-rewrite-commits --prompt "Generate a commit message with emojis and enthusiasm"
npx git-rewrite-commits --prompt "Write a haiku-style commit message"
npx git-rewrite-commits --prompt "Be extremely technical and detailed"
npx git-rewrite-commits --prompt "Follow Linux kernel commit style"

# Install git hooks to your repository
npx git-rewrite-commits --install-hooks

# Verbose mode for debugging
npx git-rewrite-commits --verbose

You can define your own commit message format using the --template option. The tool will follow your template pattern while generating meaningful descriptions.

• "(feat): message" → (feat): add user authentication
• "[JIRA-XXX] type: message" → [JIRA-123] fix: resolve null pointer
• "feat: message" → feat: implement new dashboard
• "type(scope): message" → fix(auth): handle expired tokens

The --prompt option allows you to completely customize how the AI generates commit messages. This overrides the default instructions, giving you full creative control.

Emoji-rich commits:

npx git-rewrite-commits --prompt "Generate fun commit messages with relevant emojis"
# Result: "🐛 fix: squash the authentication bug"

Haiku-style commits:

npx git-rewrite-commits --prompt "Write commit messages as haikus"
# Result: "auth middleware fix / tokens validate properly / users rejoice now"

Technical detail:

npx git-rewrite-commits --prompt "Be extremely technical, mention specific functions and variables"
# Result: "fix(auth): refactor validateJWT() to handle malformed exp claim in token payload"

Team-specific style:

npx git-rewrite-commits --prompt "Follow our team style: start with ticket number, be casual but clear"
# Result: "TECH-123 - fixed that annoying auth bug everyone was complaining about"

# Custom prompt + template format
npx git-rewrite-commits \
  --template "[JIRA-XXX] type: message" \
  --prompt "Be concise and focus on business impact"

The tool automatically assesses each commit message quality based on:

• Conventional format: Following feat/fix/docs/etc. patterns (4 points)
• Appropriate length: Between 10-72 characters (2 points)
• Descriptive content: Not generic like "update" or "fix" (2 points)
• Present tense: Following best practices (1 point)
• No trailing period: Clean formatting (1 point)

Messages scoring 7/10 or higher are considered well-formed and skipped by default. Use --no-skip-well-formed to process all commits or --min-quality-score to adjust the threshold.

1. Backup Branch: Automatically creates a backup branch before rewriting
2. Confirmation Prompts: Asks for confirmation at critical steps
3. Dry Run Mode: Preview all changes without modifying your repository
4. Uncommitted Changes Warning: Alerts you about uncommitted changes

• This tool rewrites git history! This is a destructive operation.
• Always work on a separate branch, not on main/master
• Create a manual backup of your repository
• Coordinate with your team if working on a shared repository

1. Review the changes:

2. If satisfied, force push to remote:

   git push --force-with-lease

3. If something went wrong, restore from backup:

   git reset --hard backup-branch-name

4. Clean up backup branch when done:

   git branch -D backup-branch-name

The tool generates commit messages following these conventional types:

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that don't affect code meaning (formatting, etc.)
• refactor: Code change that neither fixes a bug nor adds a feature
• test: Adding or correcting tests
• chore: Changes to build process or auxiliary tools
• perf: Performance improvements
• ci: CI/CD configuration changes
• build: Changes affecting build system or dependencies
• revert: Reverting a previous commit

• OPENAI_API_KEY: Your OpenAI API key (required)

• gpt-3.5-turbo (default) - Fast and cost-effective
• gpt-4o - Latest GPT model

# Clone the repository
git clone https://github.com/f/git-rewrite-commits.git
cd git-rewrite-commits

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Build and run
npm run build
node dist/cli.js

1. Analyzes each commit: Reads the diff, changed files, and original message
2. Generates new message: Uses AI to create a conventional commit message
3. Creates backup: Saves current state in a backup branch
4. Rewrites history: Uses git filter-branch to apply new messages
5. Provides recovery options: Keeps backup branch for restoration if needed

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (using conventional commits!)
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

If you discover any bugs, please create an issue here.

For questions and support, please open an issue in the GitHub repository.

Remember: Always backup your repository before rewriting history! 🔒