git-rewrite-commits

The tool installs three specific hooks to manage the AI commit lifecycle:

• prepare-commit-msg: Triggered during git commit. It generates the AI message based on staged changes and opens your editor with the message ready.
• post-commit: Triggered after a successful commit. It reviews and improves the commit message, automatically fixing poor ones.
• pre-push: Triggered before git push. It reviews unpushed commits and offers to fix messages before they are sent to the remote.

History Rewriting Warning

This tool rewrites git history, which is generally NOT recommended for shared repositories. Rewriting history changes commit hashes and requires force-pushing.

Recommended use cases:

• Personal projects before making them public.
• Feature branches before merging (with team agreement).
• Cleaning up local commits before pushing.

Privacy Warning

When using remote AI providers (like OpenAI), your file lists and diffs are sent to external APIs. For sensitive repositories, it is highly recommended to use Ollama for local processing so that no data leaves your machine.

You can enforce consistent commit message formats using the template option. Supported variables include:

• {type}: Commit type (feat, fix, docs, etc.)
• {scope}: Commit scope (optional)
• {description}: Commit description
• {ticket}: Extracted ticket number (if found)

const rewriter = new GitCommitRewriter({
  template: '[JIRA-{ticket}] {type}: {description}'
});

// Generates: "[JIRA-123] feat: add user authentication"

The tool is designed with a privacy-first approach to protect sensitive data during the AI rewriting process.

Automatic Protection:

• .env files are completely hidden from the AI.
• API keys are automatically redacted.
• Passwords are removed.
• Database URLs are sanitized.

Privacy Controls:

• Local AI Option: You can use Ollama for full offline support, ensuring no data leaves your machine.
• Opt-in Hooks: Git hooks are not active unless explicitly configured.
• Explicit Consent: The tool requires consent before processing.

To guide the AI with project-specific rules (e.g., specific scopes, ticket number requirements, or security emphasis), create a COMMIT_MESSAGE.md file. The tool searches for this file in the following order:

1. Project root: ./COMMIT_MESSAGE.md
2. Git directory: ./.git/COMMIT_MESSAGE.md
3. 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.

You can use the tool without permanent installation using npx, or install it globally for easier access. The short alias grec is identical to the full command name git-rewrite-commits.

# Quick Start (No Installation Required)
npx git-rewrite-commits
# or shorter:
npx grec

# Global Installation
npm install -g git-rewrite-commits
# or shorter:
npm install -g grec

The grec command is a drop-in alias for git-rewrite-commits. You can use it to rewrite commit history using AI, preview changes, or manage git hooks.

Common tasks include:

• Rewrite history: Run grec to start the AI-powered rewriting process.
• Dry run: Use --dry-run to preview how commits will be changed without actually applying them.
• Git hooks: Use --install-hooks to automate the process.
• Staged changes: Use --staged to generate a message based on currently staged changes.
• Local AI: Use --provider ollama to use a local Ollama instance instead of a remote API.

# Rewrite commit history with AI
grec

# Preview changes (dry run)
grec --dry-run

# Install git hooks
grec --install-hooks

# Generate message for staged changes
grec --staged

# Use local AI with Ollama
grec --provider ollama

You can install the AI-powered hooks using the recommended built-in installer or manually.

Recommended: Built-in Installer

This works on all platforms and automatically handles backups of existing hooks.

npx git-rewrite-commits --install-hooks

Manual Installation (Unix/macOS/Linux)

cp hooks/pre-commit .git/hooks/
cp hooks/prepare-commit-msg .git/hooks/
chmod +x .git/hooks/*

Manual Installation (Windows)

copy hooks\pre-commit.bat .git\hooks\pre-commit
copy hooks\prepare-commit-msg.bat .git\hooks\prepare-commit-msg

Required: Enable Hooks

For security, hooks are opt-in. You must explicitly enable them via git config after installation:

# Enable preview before commit
git config hooks.preCommitPreview true

# Enable automatic message generation
git config hooks.prepareCommitMsg true

When working with highly sensitive code, follow these three steps to minimize risk:

1. Use Ollama for local processing via the CLI flag.
2. Review with Dry Run to see changes before they are applied.
3. Limit Scope to a small number of commits to reduce the data processed at once.

The GitCommitRewriter class is the primary entry point for programmatic usage. You can use it to rewrite existing git history or generate new commit messages for staged changes.

import { GitCommitRewriter } from 'git-rewrite-commits';

const rewriter = new GitCommitRewriter({
  provider: 'openai',  // or 'ollama'
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4',  // optional, defaults to gpt-3.5-turbo
  dryRun: false,
  verbose: true
});

// Rewrite history
await rewriter.rewriteHistory();

// Generate message for staged changes
const message = await rewriter.generateForStaged();
console.log(message);