如何在 Git Commit Message 中正确提及共同贡献者(Co-authored-by 实践指南)

在现代软件开发中，协作是常态。无论是结对编程、代码审查，还是多人共同完成一个功能模块，经常会出现多个开发者共同贡献同一个 commit 的情况。然而，Git 默认的 author 字段只能记录提交者（通常是执行 git commit 的人），这可能导致另一位贡献者的努力被忽视。

幸运的是，GitHub 提供了一种简单而标准的方式——使用 Co-authored-by 来在 commit message 中明确标注共同贡献者。本文将详细介绍这一机制的原理、用法和最佳实践。

---

一、为什么需要提及共同贡献者？

在开源社区或团队协作中，公平地认可每位开发者的贡献至关重要。以下是几个典型场景：

• 你和同事结对编程，一人写代码，另一人实时审查并提出修改建议，最终由你执行提交。
• 你在同事的草稿基础上进行了大量重构和补充，最终形成一个完整的 commit。
• 一位贡献者提供了核心逻辑，另一位负责文档和测试，你们共同完成了这次提交。

在这些情况下，仅记录一个 author 是不公平的。Co-authored-by 正是为了弥补这一不足而设计的。

---

二、什么是 Co-authored-by？

Co-authored-by 是一种 commit message trailer（提交信息尾部标记），被 GitHub、GitLab 等平台广泛支持，用于声明该 commit 有多个贡献者。

当你在 commit message 中添加：

Co-authored-by: Alice <alice@example.com>

GitHub 会识别该字段，并在提交记录、Pull Request 和贡献图中将该 commit 同时归功于原始作者和被提及的共同作者。

✅ 支持平台：

• GitHub（完全支持，贡献图中显示双作者）
• GitLab（支持，但贡献统计可能略有差异）
• Bitbucket、Gitee 等也逐步支持类似机制

---

三、Co-authored-by 的标准格式

Co-authored-by: Full Name <email@example.com>

• Full Name：贡献者的真实姓名或 GitHub 用户名。
• email@example.com：必须是该用户在 GitHub 上关联的邮箱地址，否则无法正确关联账号。

🔍 如何查找 GitHub 用户的提交邮箱？

1. 访问其 GitHub 主页。
2. 进入其仓库的 “Commits” 页面。
3. 点击任意 commit，查看 author 字段中的邮箱。
4. 或使用 GitHub 提供的隐私邮箱格式：username@users.noreply.github.com

示例：

Co-authored-by: awan-deng <awan-deng@users.noreply.github.com>
Co-authored-by: 张三 <zhangsan@gmail.com>

---

四、实际操作：如何添加 Co-authored-by

场景 1：尚未提交（推荐方式）

git add .
git commit -m "feat: 实现用户登录功能

- 添加 JWT 认证逻辑
- 集成 OAuth2 第三方登录
- 修复登录状态持久化问题

Co-authored-by: awan-deng <awan-deng@users.noreply.github.com>"

场景 2：已提交，需修改（使用 --amend）

git commit --amend -m "feat: 实现用户登录功能

- 添加 JWT 认证逻辑
- 集成 OAuth2 第三方登录
- 修复登录状态持久化问题

Co-authored-by: awan-deng <awan-deng@users.noreply.github.com>"

⚠️ 如果已推送到远程仓库，需使用：

git push --force-with-lease

请确保团队知晓此操作，避免影响他人工作。

场景 3：多人协作，使用 Git 的 --author 参数

如果你是代他人提交，可以指定原始作者：

git commit --author="awan-deng <awan-deng@example.com>" -m "..."

但更推荐使用 Co-authored-by，因为它更透明且支持多作者。

---

五、多个共同作者怎么办？

你可以添加多个 Co-authored-by 行：

Co-authored-by: Alice <alice@example.com>
Co-authored-by: Bob <bob@example.com>
Co-authored-by: Charlie <charlie@example.com>

GitHub 会识别所有标记，并将 commit 归功于所有人。

---

六、最佳实践建议

1. 尽早沟通：在提交前与合作者确认是否需要添加 Co-authored-by。
2. 使用正确邮箱：确保邮箱与 GitHub 账户绑定，否则无法关联贡献。
3. 保持消息清晰：Co-authored-by 应放在 commit message 末尾，前后空行分隔。
4. 团队规范：在 CONTRIBUTING.md 中明确协作提交的规范。
5. 避免滥用：仅在实质性贡献时使用，避免为轻微建议添加。

---

七、GitHub 上的效果展示

添加 Co-authored-by 后，你将在 GitHub 上看到：

• ✅ 提交页面显示“Authored by A and B”
• ✅ 贡献图（Contributions Graph）中，两位作者都会获得当日贡献标记
• ✅ Pull Request 中明确列出所有作者

这不仅提升了透明度，也增强了团队成员的归属感和认可感。

---

八、最后最后最后

在 Git 中使用 Co-authored-by 是一种简单却极具意义的协作实践。它体现了开源精神中的尊重与公平，让每一位贡献者都能被“看见”。

下次当你和同事共同完成一个 commit 时，别忘了加上一句：

Co-authored-by: [姓名] <[邮箱]>

这不仅是技术操作，更是一种对协作文化的尊重。