Additional Configuration (Optional)

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

Custom Project Guidelines with COMMIT_MESSAGE.md

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

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

Usage

Command Examples

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

Real-World Examples

Automatic Commit Message Generation

Two 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 model

Now 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

Manual Rewriting for Existing Commits

# 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

Alias for Quick Fixes

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

Team Workflow: Feature Branch Cleanup

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

CI/CD Integration

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

Preparing for Open Source

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

How It Works

• Analyze: Reads your staged changes or commit history
• Generate: Uses AI to create meaningful, conventional commit messages
• Apply: Updates your commits with better messages

Smart Message Replacement

• Suggest a better AI-generated message
• Replace your bad message when you approve it
• Show what was replaced in the commit editor

History Rewriting Process

• Creates backup: Saves current branch state
• Rewrites history: Uses git filter-branch to apply new messages
• Provides recovery: Keeps backup branch for restoration if needed

Contributing

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

License

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

Bug Reports

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

Contact

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