AI-powered git commit message rewriter using AI
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.
📖 Read the blog post: Fix Your Messy Commit History with AI
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.
🔒 Important Privacy Notice: When using remote AI providers (OpenAI), this tool sends your file lists and diffs to external APIs.
Security Features:
- ✅ Explicit consent required before sending data to remote providers
- ✅ Automatic redaction of API keys, passwords, and private keys
- ✅ Local processing option via Ollama (no data leaves your machine)
- ✅ Opt-in hooks - all hooks require explicit enabling via git config
- ✅ Secure argument handling - prevents shell injection attacks
- ✅ Always creates backups before history rewrites
Recommended for sensitive repositories:
# Use local Ollama instead of remote APIs
git config hooks.commitProvider ollama
git config hooks.providerModel gemma3
ollama pull gemma3
ollama serve📖 See SECURITY.md for complete security documentation
- AI-powered commit message generation using OpenAI GPT or local Ollama models
- Rewrite entire git history with better commit messages
- Conventional commits format (feat, fix, chore, etc.)
- Multi-language support - generate commits in any language
- Smart filtering - skip already well-formed commits
- Local AI option with Ollama - no data leaves your machine
- Git hooks integration - automatic AI messages on every commit
- Intelligent analysis of code changes to generate meaningful messages
- Batch processing with rate limiting
- Safe operation with automatic backup branches
- Custom templates for team-specific formats
- Quality scoring to identify commits that need improvement
- Verbose mode with diff preview and detailed processing information
- Custom prompts - Override AI behavior with
--promptfor unique styles - Efficient processing - Process only the last N commits with
--max-commits - Dry-run mode - Preview changes before applying them
- Progress tracking - Real-time progress indicators with colored output
- Custom context - Project-specific guidelines via
COMMIT_MESSAGE.mdfile
npx git-rewrite-commits
# or shorter:
npx grec# Full command name
npm install -g git-rewrite-commits
# Or install the short alias (grec = git-rewrite-commits)
npm install -g grec
# Both work identically:
git-rewrite-commits --help
grec --help # Same thing, just shorter!✅ Works on all platforms: Windows, macOS, Linux
💡 Tip:grecis a shorter alias forgit-rewrite-commits- use whichever you prefer!
Step 1: Install or update the AI commit message hooks
npx git-rewrite-commits --install-hooks
# or with the short alias:
npx grec --install-hooks💡 Updates existing hooks: If hooks already exist, they'll be updated to the latest version. Non-git-rewrite-commits hooks are backed up before replacement.
Step 2: Enable the hooks you want (opt-in required for security):
# Option A: Enable message preview before commit
git config hooks.preCommitPreview true
# Option B: Enable automatic message generation
git config hooks.prepareCommitMsg true
# Or enable both for the full experience!
# For privacy: use local Ollama instead of remote OpenAI
git config hooks.commitProvider ollama
git config hooks.providerModel llama3.2 # Optional: specify modelStep 3: Configure your AI provider:
# Option A: OpenAI (sends data to remote API)
export OPENAI_API_KEY="your-api-key" # Unix/macOS
# set OPENAI_API_KEY="your-api-key" # Windows
# Option B: Ollama (local processing, recommended for sensitive repos)
ollama pull llama3.2
ollama serve
# Option C: Ollama on a custom server/port
export OLLAMA_URL="http://192.168.1.100:11434" # Unix/macOS
# set OLLAMA_URL=http://192.168.1.100:11434 # WindowsSee 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.
# Set specific model
git config hooks.providerModel "gpt-4" # or "gpt-3.5-turbo", "llama3.2", etc.
# Set custom Ollama server URL (if not using localhost:11434)
git config hooks.ollamaUrl "http://192.168.1.100:11434"You can provide project-specific commit message guidelines that the AI will follow by creating a COMMIT_MESSAGE.md file. The tool searches for this file in the following locations (in order):
- Project root -
./COMMIT_MESSAGE.md - Git directory -
./.git/COMMIT_MESSAGE.md - GitHub directory -
./.github/COMMIT_MESSAGE.md
Example COMMIT_MESSAGE.md:
# Project Commit Guidelines
## Requirements
- Use conventional commits with these scopes: auth, api, ui, db
- Include ticket numbers when available (e.g., JIRA-123)
- Security changes must be clearly marked
- Breaking changes need BREAKING CHANGE in the message
## Project Context
This is a financial services API that handles sensitive data.
Emphasize security, compliance, and performance in commit messages.See COMMIT_MESSAGE.md.example in this repository for a complete example.
# Using the full command name
npx git-rewrite-commits [options]
# Or using the short alias (grec)
npx grec [options]Common use cases:
# Rewrite entire git history
npx git-rewrite-commits
# Preview changes without applying (dry run)
npx git-rewrite-commits --dry-run
# Generate commit message for staged changes
npx git-rewrite-commits --staged
# Process only last 10 commits
npx git-rewrite-commits --max-commits 10
# Use custom AI model
npx git-rewrite-commits --model gpt-4
# Use local AI with Ollama
npx git-rewrite-commits --provider ollama
# Install/update git hooks
npx git-rewrite-commits --install-hooksTwo Smart Hooks:
- pre-commit: Preview AI message and optionally replace bad commit messages
- prepare-commit-msg: Automatically generate or use approved messages
# Install the hooks (using either command)
npx git-rewrite-commits --install-hooks
# or
npx grec --install-hooks
# Enable them (opt-in for security)
git config hooks.preCommitPreview true # Preview before commit
git config hooks.prepareCommitMsg true # Auto-generate in editor
# Configure provider
git config hooks.commitProvider ollama # or use OpenAI with OPENAI_API_KEY
git config hooks.providerModel llama3.2 # Optional: specify modelNow when you run git commit:
- With pre-commit: You'll see a preview of the AI message first
- With prepare-commit-msg: The AI message appears in your editor
# 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" ]; thenAdd 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-commitBefore 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-branchAdd 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 improvedBefore 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- Analyze: Reads your staged changes or commit history
- Generate: Uses AI to create meaningful, conventional commit messages
- Apply: Updates your commits with better messages
When you use git commit -m "bad message", pre-commit can:
- Suggest a better AI-generated message
- Replace your bad message when you approve it
- Show what was replaced in the commit editor
- Creates backup: Saves current branch state
- Rewrites history: Uses
git filter-branchto apply new messages - Provides recovery: 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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (using conventional commits!)
- Push to the branch (
git push origin feature/AmazingFeature) - 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! 🔒
