mailmap 是什么
mailmap（仓库根 .mailmap 文件）把同一贡献者在历史里的多个姓名与邮箱归并成一个规范署名，用于展示与统计：shortlog 名单、log 的作者行、blame 标注都会按映射显示。它不修改任何历史提交，只影响怎么显示，因此可以随时增删、随仓库分发。
基本信息
| 文件位置 | 仓库根 .mailmap；也可用 mailmap.file 或 mailmap.blob 指定 |
|---|---|
| 文件格式 | 规范署名 规范邮箱 旧邮箱，多种写法 |
| 生效命令 | shortlog、log 默认界面、blame 与 aN/aE 占位符 |
| 例外 | an 与 ae 占位符永远显示原始署名；log 可用 --no-use-mailmap 关闭映射 |
| 权限要求 | 普通用户；文件提交后对全队生效 |
典型使用场景
- 换过邮箱的同事：历史提交两个邮箱并存，贡献名单重复计数
- 同一人多个姓名：shortlog 输出多行，评优与统计要按人合并
- 开源项目整理贡献者：发布前归并署名再生成名单
- 机器人账号：把自动生成的邮箱归并到一个规范署名统一展示
- blame 排查更顺：文件作者显示规范名而不是多个马甲
常用示例
常用示例
# 在仓库根创建 .mailmap，邮箱需与历史精确匹配
cat > .mailmap <<'EOF'
Zhang San <zhangsan@example.com> <zhangsan@old-mail.com>
Zhang San <zhangsan@example.com> Old Name <old@example.com>
EOF
git check-mailmap "Old Name <old@example.com>" # 单条验证映射结果
git shortlog -sne HEAD # 确认名单已合并四种书写形式
| 写法 | 效果 | 说明 |
|---|---|---|
| 新名 <旧邮箱> | 只替换姓名 | 同邮箱的多份署名归一 |
| <新邮箱> <旧邮箱> | 只替换邮箱 | 姓名不动、按邮箱合并 |
| 新名 <新邮箱> <旧邮箱> | 按旧邮箱替换姓名与邮箱 | 最常用的形态 |
| 新名 <新邮箱> 旧名 <旧邮箱> | 姓名与邮箱联合匹配替换 | 同名多邮箱场景 |
实测行为（Git 2.54）：log 默认界面、blame 与 shortlog 都会应用 mailmap；an 与 ae 占位符不应用，需要映射后的值用 aN 与 aE 大写形式。
托管平台的贡献图按平台侧账号计算，.mailmap 只影响本地命令输出；两边对不上时要在平台侧补邮箱绑定或账号设置。