type
Post
status
Published
date
Jul 23, 2025
slug
git-user-email
summary
tags
开发
category
技术分享
icon
password
本文采用Gemini 2.5 pro 编写，以作记录
在使用 Git 进行版本控制时，你提交的每一个 commit 都会记录下作者的用户名和邮箱。这些信息是代码追溯和身份识别的关键。但有时，我们可能会因为更换公司、使用个人邮箱代替工作邮箱，或者仅仅是想统一身份标识，而需要修改这些信息。
本文将为你提供一份终极指南，教你如何：
- 修改未来所有提交的用户名和邮箱。
- 重写历史记录，修正过去所有不正确的提交信息。
- 解决在此过程中可能遇到的常见问题。
场景一：只修改未来的提交（基础操作，人人必会）
这是最简单也最常见的需求。这个设置会影响你在此电脑上未来所有的
git commit。步骤
- 打开你的终端（Terminal、CMD、PowerShell 或 Git Bash）。
- 设置全局用户名和邮箱：
使用
-global标志，可以让你这台电脑上的所有 Git 仓库都默认使用这个新配置。将"New-Username"和"new-email@example.com"替换成你自己的信息。
- 验证设置是否成功： 运行以下命令，检查输出是否为你刚刚设置的新信息。
提示：如果你只想为单个项目设置不同的用户名/邮箱，可以进入该项目目录，然后运行不带 --global 标志的相同命令。项目级配置会覆盖全局配置。
场景二：修改所有历史提交记录（高级操作，谨慎使用）
当你发现历史记录中已经存在大量错误的作者信息时，就需要重写历史了。这是一个强大的操作，因为它会改变过去每一次相关提交的哈希值（Commit ID）。
⚠️ 重要警告：
- 备份为王：在执行此操作前，请务必备份你的仓库！最简单的方式就是把整个项目文件夹复制一份。
- 团队协作风险：如果你已经将代码推送到远程仓库（如 GitHub、Gitee），重写历史后需要强制推送（
git push --force）。这会给正在同一分支上工作的同事带来巨大麻烦。在操作前，请务必与团队成员沟通！
推荐工具：git-filter-repo
Git 官方现在推荐使用
git-filter-repo 来代替老旧的 git filter-branch。它更快、更安全、更易用。第一步：安装
git-filter-repo推荐使用 Python 的包管理器
pip 进行安装。第二步：解决
command not found 错误安装后，你可能会遇到
git: 'filter-repo' is not a git command 的错误。这是因为 pip 安装脚本的路径没有被添加到系统的 PATH 环境变量中。解决方案：
- 找到脚本路径。在 Windows 上通常是
C:\\Users\\<你的用户名>\\AppData\\Roaming\\Python\\PythonXX\\Scripts。
- 将此路径添加到系统的
Path环境变量中。
- 重启你的终端，使配置生效。
如果不想修改环境变量，也可以使用以下命令直接运行：
第三步：创建
mailmap 映射文件mailmap 是一个简单的文本文件，用于定义新旧信息的对应关系。在你的项目目录中创建一个名为 mailmap.txt 的文件，格式如下：新名字 <新邮箱> 旧名字 <旧邮箱>例如，我们要将用户
Old-Username（邮箱 old-email@work.com）修改为 New-Username（邮箱 new-email@personal.com），文件内容应为：第四步：执行历史重写
git-filter-repo 为了安全，默认只在全新的克隆上运行。如果你在现有仓库执行，会看到类似 Refusing to destructively overwrite repo history 的错误。解决方案：使用
--force 参数。在你的项目根目录下，运行以下命令：
第五步：检查并强制推送
- 检查日志：
运行
git log，检查历史提交的作者信息是否已全部更新。
- 强制推送： 由于历史已被重写，你必须使用强制推送将更改同步到远程仓库。
总结
修改 Git 用户信息是一个常见的需求。对于未来的提交，简单的
git config 命令即可解决。而对于历史记录的修正，git-filter-repo 是你强大的盟友。记住，重写历史是一把双刃剑。在挥舞它之前，请确保你已经做好了充分的准备：备份仓库、通知团队。遵循本文的步骤，你就能像专业人士一样，干净利落地管理你的 Git 身份信息。