Change email address in Git

How to Change Your Email Address in Git Commits

Learn how to correct or update your email address in Git commits, both for future commits and for historical commits, ensuring proper attribution and repository hygiene.

Maintaining an accurate email address in your Git configuration is crucial for proper commit attribution, especially when working in teams or contributing to open-source projects. This article will guide you through changing your Git email address for new commits and, more complexly, for rewriting history to correct past commits. We'll cover both local and global configurations, and discuss considerations for shared repositories.

Changing Email for Future Commits

The simplest scenario is updating your email for all new commits you make. This involves modifying your local Git configuration. You can set your email globally for all repositories on your system, or locally for a specific repository. It's generally recommended to set it globally unless you have a specific reason to use different emails for different projects.

1. Set Global Email

To set your email address for all future Git repositories on your system, use the --global flag. This is the most common approach.

2. Set Local Email (Repository Specific)

If you need a different email for a specific repository, navigate into that repository's directory and run the command without the --global flag. This will override the global setting for that particular repository.

3. Verify Configuration

After setting your email, you can verify that the change was applied correctly by checking your Git configuration.

Global Configuration

git config --global user.email "your_new_email@example.com" git config --global user.name "Your Name"

Local Configuration

cd /path/to/your/repo git config user.email "repo_specific_email@example.com" git config user.name "Your Name"

Verify

git config user.email git config user.name

Rewriting History: Changing Email in Past Commits

Changing the email address in past commits is a more advanced operation as it rewrites Git history. This should be done with extreme caution, especially in shared repositories, as it changes the commit SHAs and can cause issues for collaborators who have already pulled the old history. The git filter-repo tool (recommended) or git filter-branch (legacy) can be used for this purpose.

flowchart TD
    A[Start: Identify Incorrect Commits] --> B{Is it a Shared Repository?}
    B -->|Yes| C[Communicate with Team: Backup & Rebase]
    B -->|No| D[Backup Repository]
    C --> E[Install git-filter-repo (if not installed)]
    D --> E
    E --> F[Run git-filter-repo Command]
    F --> G[Verify Changes Locally]
    G --> H{Are Changes Correct?}
    H -->|Yes| I[Force Push to Remote (if shared)]
    H -->|No| J[Revert Backup & Re-evaluate]
    I --> K[End: History Rewritten]
    J --> E

Process for rewriting Git history to change email addresses

Using git filter-repo (Recommended)

git filter-repo is a modern, faster, and safer alternative to git filter-branch. It needs to be installed separately. This tool allows you to rewrite commit history based on various criteria, including changing author or committer information.

1. Install git-filter-repo

First, ensure you have git-filter-repo installed. You can usually install it via pip.

2. Navigate to Repository

Change your directory to the root of the Git repository where you want to rewrite history.

3. Run the git-filter-repo Command

Execute the command, replacing OLD_EMAIL with the incorrect email and NEW_EMAIL with the correct one. You can also change the NEW_NAME if needed.

4. Force Push to Remote (if applicable)

If this is a shared repository and you've pushed the old history, you will need to force push your changes. This will overwrite the remote history. Use with extreme caution and only after team coordination.

pip install git-filter-repo

cd /path/to/your/repo

git filter-repo --env-filter \
  'if test "$GIT_AUTHOR_EMAIL" = "OLD_EMAIL"; then \
     export GIT_AUTHOR_EMAIL="NEW_EMAIL"; \
     export GIT_AUTHOR_NAME="NEW_NAME"; \
   fi; \
   if test "$GIT_COMMITTER_EMAIL" = "OLD_EMAIL"; then \
     export GIT_COMMITTER_EMAIL="NEW_EMAIL"; \
     export GIT_COMMITTER_NAME="NEW_NAME"; \
   fi' --tag-name-filter cat --force

# After verification, if on a remote:
git push --force --tags origin --all

Using git filter-repo to change email and name in past commits

Using git filter-branch (Legacy)

git filter-branch is an older, built-in Git command that can also rewrite history. While still functional, it's slower and more complex to use than git filter-repo and is generally discouraged for new workflows. However, it's good to be aware of its existence.

cd /path/to/your/repo

git filter-branch --env-filter \
  'if test "$GIT_AUTHOR_EMAIL" = "OLD_EMAIL"; then \
     export GIT_AUTHOR_EMAIL="NEW_EMAIL"; \
     export GIT_AUTHOR_NAME="NEW_NAME"; \
   fi; \
   if test "$GIT_COMMITTER_EMAIL" = "OLD_EMAIL"; then \
     export GIT_COMMITTER_EMAIL="NEW_EMAIL"; \
     export GIT_COMMITTER_NAME="NEW_NAME"; \
   fi' --tag-name-filter cat -- --all

# After verification, if on a remote:
git push --force --tags origin --all

# Clean up old refs (optional, but recommended after successful rewrite)
git for-each-ref --format='delete %(refname)' refs/original | git update-ref --stdin
git reflog expire --expire=now --all
git gc --prune=now

Using git filter-branch to change email and name in past commits