git-reauthor

Change an author's email and name across the whole Git repository

$ git reauthor [[-o|--old-email]] [old@example.com] [[-e|--correct-email]] [new@example.com] [[-n|--correct-name]] "[name]"

$ git reauthor [[-o|--old-email]] [old@example.com] [[-c|--use-config]]

$ git reauthor [[-a|--all]] [[-e|--correct-email]] [name@example.com] [[-n|--correct-name]] [name]

git-reauthor [options] [<commit-range>]

Note: This synopsis represents a common implementation pattern for a 'git-reauthor' script, not a universally defined built-in Git command. Specific scripts may vary in their arguments and functionality.

--map <map_file>
    Specifies a file containing rules for mapping old author/committer identities to new ones. Each line typically defines an '<old_email> <new_name> <new_email>' pattern or similar structured mapping.

--old-email <email>
    The old author or committer email address to match for replacement.

--new-email <email>
    The new email address to assign to matched commits.

--new-name <name>
    The new name to assign to matched commits.

--all
    Applies the reauthoring process to all commits in the repository's entire history.

--dry-run
    Performs a simulation of the reauthoring process, showing potential changes without actually modifying the repository history.

<commit-range>
    An optional Git commit range (e.g., HEAD~5..HEAD, <commit-hash>) to limit the reauthoring to a specific set of commits. If omitted, the script's behavior depends on its implementation, often implying --all or HEAD.

The term "git-reauthor" refers to a common utility script, rather than a built-in Git command, designed to modify the author and committer information of commits within a Git repository's history.

Its primary function is to correct or unify commit identities, addressing issues like misspelled names, incorrect email addresses, or different identities used for the same person. These scripts typically leverage powerful Git history rewriting tools such as git filter-branch --env-filter or the more modern and faster git filter-repo.

When executed, a git-reauthor script iterates through a specified set of commits, transforms environment variables like GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, and GIT_COMMITTER_EMAIL, and then recreates the commits with the new information. This process fundamentally rewrites history, resulting in new commit SHAs for affected commits and all their descendants. Consequently, pushing these changes to a shared remote repository requires a force-push (e.g., git push --force-with-lease). It is a powerful but potentially destructive operation, best performed on a fresh clone of the repository and with a backup.

Not a Built-in Command: git-reauthor is not part of the standard Git distribution but is a common name for user-created or community-maintained scripts.
History Rewriting: It fundamentally rewrites Git history, changing commit SHAs. This makes all affected commits (and their descendants) entirely new objects.
Force Pushing Required: After rewriting history, pushing to a shared remote repository necessitates a force-push (e.g., git push --force-with-lease), which can be disruptive for collaborators.
Data Loss Risk: Always perform this operation on a fresh clone of the repository and ensure you have a backup of the original repository to prevent irreversible data loss.
Performance Considerations: For very large repositories, scripts relying on git filter-branch can be slow. Modern implementations often use git filter-repo for significantly better performance.
GPG Signatures: Rewriting commits invalidates any existing GPG signatures on those commits.

A common use case for a git-reauthor script is when a developer accidentally commits with a personal email address to a professional repository, or vice-versa. The script provides a streamlined way to correct the author/committer details across multiple commits consistently.

Before force-pushing rewritten history to a shared repository, it is crucial to communicate with all collaborators. They must be informed to fetch the new history and rebase or reset their local branches accordingly to avoid creating divergent histories and potential merge conflicts.

The necessity to modify commit authorship in Git history has existed since the early days of Git. Initially, users would construct complex git filter-branch --env-filter commands manually. Over time, various scripts emerged to automate this tedious process, with 'git-reauthor' becoming a widely recognized and descriptive name for such a utility. These scripts encapsulate the filtering logic, simplifying the management of author and committer mappings. The evolution of more efficient tools like git-filter-repo has led many newer git-reauthor implementations to switch from filter-branch for improved performance. The widespread use of these scripts highlights a common Git maintenance task rather than the development of a single, official command.

git-filter-branch(1), git-filter-repo(1), git-log(1), git-reflog(1), git-push(1)