Commit Email Migrator

Systematic history modification and automated noreply resolution for GitHub repositories

---

This is a utility script designed to systematically rewrite the commit history of Git repositories to modify author email addresses. It leverages git-filter-repo to process repository histories, generate necessary mailmap configurations dynamically, and force-push the rewritten history to the origin remote.

Note

This tool is particularly applicable for retroactively applying anonymous noreply email addresses to GitHub repositories, preventing exposure of personal email addresses in public commit logs.

Mechanism

The script executes the following operations per configured repository:

1. Performs a bare clone of the target repository into an ephemeral workspace.
2. Extracts all unique author identities (names and emails) from the repository's commit history via git log.
3. Evaluates the extracted authors against the defined USER_EMAIL_MAP to determine the target email address.
4. If configured for GitHub API resolution (NOREPLY_MODE = "api"), queries the GitHub REST API to obtain the numeric user ID associated with the author's username to construct the standard GitHub noreply email address format (ID+username@users.noreply.github.com).
5. Generates a standard Git mailmap file containing the mapping transformations.
6. Invokes git filter-repo to apply the mailmap transformations across the entire repository history.
7. Re-establishes the remote origin and performs a force-push of all rewritten branches and tags.

Warning

Rewriting Git history alters commit hashes. This is a destructive operation that requires all collaborators to re-clone the repository or perform complex rebase operations on local branches. Always ensure collaborators are informed before executing history modifications on shared repositories.

Prerequisites

• Python 3.8+
• Git (Accessible via system PATH)
• git-filter-repo (Accessible via system PATH)

Setup and Virtual Environment

It is recommended to execute this script within an isolated Python virtual environment.

# Clone or navigate to the project directory
cd "Email Rewriter"

# Initialize a virtual environment
python -m venv venv

# Activate the virtual environment (Windows)
venv\Scripts\activate

# Activate the virtual environment (Unix/macOS)
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Note

Ensure that git-filter-repo is installed and accessible in your system's PATH. If it is not included in requirements.txt, you may need to install it via your system package manager or via pip (pip install git-filter-repo).

Configuration

Configuration parameters are defined directly within migrator.py under the CONFIGURATION section. Modify these variables prior to execution.

Target Specifications

Variable	Type	Description
REPOSITORIES	list	A list of fully qualified repository URLs to process.
USER_EMAIL_MAP	dict	Key-value mapping of author names to target email addresses. Use the key "all" to apply a default target to all discovered authors. Use the value "noreply" to trigger dynamic noreply email resolution.

Network Protocol Configuration

Variable	Type	Description
MODE	str	Defines the protocol for cloning and pushing. Accepted values are "https" or "ssh".
SSH_HOST	str	The SSH host alias to utilize when MODE is set to "ssh". Defaults to "github.com".

Noreply Resolution Strategy

Variable	Type	Description
NOREPLY_MODE	str	Defines the behavior when a target email is "noreply". "api" fetches the user ID via GitHub REST API. "generic" falls back to username@users.noreply.github.com.

Execution Flags

Variable	Type	Description
DRY_RUN	bool	Bypasses git filter-repo execution and network push operations, emitting intended actions to the logger.
CLONE_DIR	str	The local directory path utilized for ephemeral repository cloning. Defaults to "./git_workspace".
CLEAN_UP	bool	Determines whether CLONE_DIR is deleted upon script completion or failure.

Caution

Before modifying production repositories, it is highly advised to test your configuration by executing the script with DRY_RUN = True. This will output the generated mailmap and intended operations to the log file without modifying history or executing remote network operations.

Usage

After configuring the parameters in migrator.py, execute the script:

python migrator.py

Logging

The script implements dual-target logging:

• Standard output (console)
• Disk file (log_YYYYMMDD_HHMMSS.txt)

Review the generated log file for a complete execution trace, including any HTTP errors encountered during API resolution or command execution failures.