GitRewrite 🪄

Intelligently rewrite your Git history with AI-powered commit messages.

• ALPHA SOFTWARE DISCLAIMER
• Overview
• Features
• Usage
  • Basic Usage
  • Options
  • Workflow Example
• Requirements
• Installation
  • From Prebuilt Binaries
  • Using Go
  • From Source
  • Ollama Setup
  • Recommended: Custom Ollama Modelfile
• Examples for Advanced Scenarios
• Motivation
• Cautions and FAQ
  • Rewriting History Implications
  • Known Limitations (Alpha)
  • Common Questions
• Development

ALPHA SOFTWARE DISCLAIMER

GitRewrite is currently in ALPHA stage of development.

• This software is experimental and may contain bugs or unexpected behavior
• It is NOT recommended for use in production environments or with critical repositories
• Always create a backup of your repository before using GitRewrite
• Git history rewriting is inherently risky - proceed with caution
• Features and command-line interface may change without notice
• Use at your own risk

Overview

GitRewrite transforms your repository's history by converting cryptic or minimal commit messages into meaningful, structured, conventional commits. Using AI, it analyzes each commit's code changes and creates descriptive messages that explain what changed and why.

Before GitRewrite:

fix stuff

After GitRewrite:

fix: resolve race condition in database connection pooling (database)
chore: update Docker image to v21.3.1 (infrastructure)

Features

• AI-Powered Message Generation: Analyzes diffs to create meaningful, context-aware commit messages
• Conventional Commits Format: Structures messages with type, description, and component
• Interactive TUI: Beautiful terminal interface with real-time progress tracking
• Dry Run Mode: Preview changes before applying them
• Batch Rewrite: Process and rewrite multiple commits at once
• Filters: Target only commits with minimal or unclear messages
• Repository Safety: Careful validation prevents accidental history corruption

Usage

Basic Usage

gitrewrite -repo=/path/to/repository

Options

  -repo string
        Path to the git repository
  -max-length int
        Maximum length of commit messages to consider for rewriting (default: 10)
  -model string
        Ollama model to use for rewriting (default: "qwen2.5:14b")
  -temperature float
        Temperature for model generation (default: 0.1)
  -max-diff int
        Maximum length of diff to send to the model (default: 2048)
  -dry-run
        Generate new commit messages but don't apply them
  -output string
        Custom path for dry run output file (default: repo-name-rewrite-changes.json)
  -apply-changes string
        Path to JSON file with commit rewrite changes to apply directly without using Ollama
  -exclude string
        Regex pattern to exclude matching files from diff processing
  -max-files int
        Maximum number of files in a commit before handling differently (default: 200)
  -summarize-oversized
        Generate a one-line summary for commits with too many files instead of skipping them
  -debug-log string
        Path to output debug log file
  -output-repo string
        Name of the output repository (default: <original-repo-name>-rewritten)

Workflow Example

1. IMPORTANT: Before running GitRewrite, create a backup of your repository and ensure you're on the default branch:

   cp -r /path/to/repo /path/to/repo-backup
   cd /path/to/repo
   git checkout main  # or your default branch (master, develop, etc.)

2. Run GitRewrite in dry-run mode first to preview changes without applying them:

   gitrewrite -repo=/path/to/repo -dry-run

   This will generate a JSON file (default: repo-name-rewrite-changes.json) with the proposed commit message changes.

3. Review the generated JSON file and make any desired edits.

4. Apply the changes from the JSON file:

   gitrewrite -repo=/path/to/repo -apply-changes=path/to/changes.json

   A confirmation dialog will appear before applying the changes.

5. For direct rewriting (not recommended for important repositories during alpha):

   gitrewrite -repo=/path/to/repo

   A confirmation dialog will appear that looks like this:

   50 total commits found, 12 will be rewritten with improved messages. All commits will be applied to a new repository at /path/to/your-repo-rewritten.
   
   This operation will create a new repository with the same files but improved commit messages.
   
   'No' is selected by default. Use Tab to select 'Yes' if you want to proceed.
   

6. GitRewrite creates a new repository with rewritten history:

   New repository located at /path/to/your-repo-rewritten
   

   The new repository will be created as a sibling directory to your original repository with the same files, branches, and remotes, but with improved commit messages.

7. To use this new repository as your main repository, you can force push it to remote:

   cd /path/to/your-repo-rewritten
   git push --force origin main  # or your default branch

   Note: Force pushing rewrites history on the remote repository and affects all collaborators.

Requirements

• Go 1.23.4+
• Git
• Ollama with a large language model installed (default: qwen2.5:14b)

Installation

From Prebuilt Binaries

The easiest way to install GitRewrite is to download a prebuilt binary from the releases page.

1. Go to the releases page
2. Download the appropriate binary for your system:
   • For Linux: gitrewrite-linux-amd64 or gitrewrite-linux-arm64
   • For macOS: gitrewrite-darwin-amd64 or gitrewrite-darwin-arm64
   • For Windows: gitrewrite-windows-amd64.exe or gitrewrite-windows-arm64.exe
3. Make the binary executable (Linux/macOS):

   chmod +x gitrewrite-*

4. Move the binary to a location in your PATH:

   # Linux/macOS
   mv gitrewrite-* /usr/local/bin/gitrewrite
   
   # Or add to a personal bin directory
   mkdir -p ~/bin
   mv gitrewrite-* ~/bin/gitrewrite

Using Go

go install github.com/MrLemur/gitrewrite/cmd/gitrewrite@latest

From Source

git clone https://github.com/MrLemur/gitrewrite.git
cd gitrewrite
make build

Ollama Setup

1. Install Ollama from ollama.ai
2. Pull the recommended model:

   ollama pull qwen2.5:14b

3. Ensure Ollama is running before using GitRewrite

Recommended: Custom Ollama Modelfile with Increased Context

For repositories with larger commits, it's highly recommended to create a custom Ollama model with increased context length. This improves the AI's ability to analyze code changes for better commit message generation.

1. Create a file named Modelfile with the following content:

   FROM qwen2.5:14b
   PARAMETER context_length 32768
   

2. Build the custom model:

   ollama create gitrewrite-qwen -f ./Modelfile

3. Use your custom model with GitRewrite:

   gitrewrite -repo=/path/to/repo -model=gitrewrite-qwen

Note: Increasing the context length requires more RAM and VRAM. Adjust the context_length value based on your system capabilities (16K, 32K, etc.).

Examples for Advanced Scenarios

Handling Repositories with Many Files Per Commit

For repositories with a large number of files per commit:

gitrewrite -repo=/path/to/repo -max-files=300

This increases the limit of files processed per commit before the commit is considered "oversized".

Generate Summaries for Oversized Commits

Instead of skipping commits with too many files, generate a simplified message:

gitrewrite -repo=/path/to/repo -summarize-oversized

Excluding Specific Paths from Analysis

To ignore certain paths using regex patterns (like generated files or dependencies):

gitrewrite -repo=/path/to/repo -exclude="node_modules|dist|vendor|.*\.generated\.go"

Custom Output Repository Name

Specify a custom name for the new repository:

gitrewrite -repo=/path/to/repo -output-repo="my-improved-repo"

Enable Debug Logging

For troubleshooting or detailed analysis:

gitrewrite -repo=/path/to/repo -debug-log="./debug.log"

Motivation

Every developer has encountered (or created) repositories with unclear commit histories. GitRewrite was born from the frustration of maintaining a GitOps repository where many small changes accumulated over time with minimal or unhelpful commit messages.

When you're debugging an issue or trying to understand why a change was made months ago, commit messages like "update config" or "fix bug" are nearly useless. GitRewrite transforms these into a clean, structured history that documents your codebase's evolution properly.

By enforcing Conventional Commits standards and detecting affected components, GitRewrite makes your Git history into a powerful documentation tool rather than a cryptic timeline.

Cautions and FAQ

Rewriting History Implications

• ALWAYS CREATE A BACKUP before using this tool - this cannot be emphasized enough
• During alpha development, unexpected bugs may cause repository corruption
• Consider testing on a clone or fork of your repository first
• GitRewrite must be run on the default branch of your repository (typically main or master)
• The tool automatically verifies you're on the default branch before proceeding
• Rewriting history changes commit hashes, which can cause issues for collaborators
• For shared repositories, communicate with your team before using this tool
• After force pushing rewritten history, all collaborators must reset their local repositories
• IMPORTANT: Force pushing will automatically close all open Pull Requests in GitHub, GitLab, or other platforms
• BEST PRACTICE: Before running GitRewrite on a shared repository:
  1. Merge or close all open Pull Requests
  2. Coordinate with your team to ensure no active development branches exist
  3. Have all team members push their changes
  4. Pull down a fresh copy of the repository
  5. Run GitRewrite
  6. Force push the new repository
• Collaborators should follow this procedure after you've force pushed:

  git fetch origin
  git checkout main  # or your default branch
  git reset --hard origin/main

• Failing to reset local repositories after history rewriting can lead to merge conflicts and duplicate commits
• Protected branches on GitHub, GitLab, or other platforms may block force pushes
• If you have active branches based on the old history, they will need to be rebased onto the new history

Known Limitations (Alpha)

• May not handle merge commits correctly in all situations
• Large repositories with complex histories might cause unexpected behavior
• Performance issues might occur with very large commits or diffs
• Repositories with binary files or non-text content may not be analyzed correctly
• Commits with more files than the -max-files limit will be skipped unless -summarize-oversized is used
• The program works best on repositories with a clean, linear history
• Certain regex patterns in the -exclude flag might impact performance on large repositories

Common Questions

Q: How long will it take to process my repository?
A: Processing time depends on repository size, commit count, and your machine's specs. A rough estimate is 2-5 seconds per commit being rewritten.

Q: Will this affect branches?
A: Yes. Rewriting commits will change their hashes, which can affect branches that build upon those commits.

Q: What if I don't like some of the generated messages?
A: Use the dry-run mode to preview changes, edit the JSON file as needed, then apply with -apply-changes.

Q: Can I process only specific commits?
A: Currently, the tool processes all commits with messages shorter than the -max-length threshold. You can use the -exclude pattern to skip files in certain paths, which may indirectly filter some commits.

Q: What happens with commits that have too many changed files?
A: By default, commits with more than 200 files (configurable with -max-files) are skipped. Enable -summarize-oversized to generate simplified messages for these commits instead of skipping them.

Q: Can I customize the name of the output repository?
A: Yes, use the -output-repo flag to specify a custom name for the new repository.

Q: What should I do if I encounter a bug?
A: Please report it on our GitHub issues page with detailed steps to reproduce.

Development

# Clone the repository
git clone https://github.com/MrLemur/gitrewrite.git

# Install dependencies
cd gitrewrite
go mod tidy

# Run tests
make test

# Build
make build

# Run locally with dry-run for safety during development
./bin/gitrewrite -repo=/path/to/test/repo -dry-run