Change committer email using git filter-repo

It is possible to fix incorrect email addresses in old git commits, but it involves rewriting the commit history, will change commit hashes, and can generally be expected to require all devs to make new clones. You can use the git filter-repo tool to perform this sort of rewrite!

Don’t attempt this unless you understand that rewriting history is a fairly serious endeavor to undertake, especially if other developers have clones of your repo. After using git filter-repo, an easy way to avoid problems is for all devs make new clones and discard their old clones.

If you’re ok with the caveats, here’s how to do it:

  1. Make sure Python is installed. One easy way is to install the latest from the Windows Store.
  2. Install git filter-repo by copying the file to your $PATH. For example, I added the git-filter-repo file to C:\Program Files\Git\mingw64\libexec\git-core
  3. Edit git-filter-repo in Notepad or another text editor. Remove the “3” from python3 at the very top of the file.
  4. In git bash, cd to the repo which you intend to rewrite.
  5. Using a text editor like nano or Notepad create a file called .mailmap. Place it inside the repo you’re rewriting.
  6. In .mailmap, add the emails you wish to change, in a format like:
    <> <>
    <> <>
    Include the carats and define one rewrite per line. Save the file.
  7. In git bash:
    git filter-repo --use-mailmap
  8. The emails will be rewritten, and this will change most if not all commit hashes. If other people have clones of your repo, and you git push origin main --force this repo, they will need to make new clones of the origin. Before doing any the above process you should be sure no one else has work that was uncommitted or that you don’t have in the local repo where you’re running --use-mailmap

    To replace the history in your bare repo or GitHub
    git push origin main --force
    Don’t run this command or any of the above commands if you don’t understand what it does.

Leave a Comment

Your email address will not be published. Required fields are marked *