Moby 贡献者 Git 配置实战：Fork 克隆、upstream 远程与 DCO 签名全流程

2026-09-04 19:04:43作者：傅爽业Veleda

本篇是 Moby 项目贡献者指南中「配置 Git」一章的完整实操指南。跟着本文你可以从零完成 Moby 代码库的 Fork 与克隆、配置本地 Git 身份并添加指向上游 moby/moby 的 upstream 远程、创建并推送一个用于验证配置的 dry-run-test 分支，同时理解 Moby 项目为何强制要求 Developer Certificate of Origin（DCO）签名——仓库中的 CI 校验脚本 hack/validate/dco 会逐提交检查签名格式，这是后续所有 Pull Request 能否通过检查的第一道门槛。

本篇在贡献者指南中的位置

Moby 的贡献者指南位于 docs/contributing/，推荐的配置顺序为：先安装必需软件（software-required.md），再配置 Git（本文），然后进入开发容器环境。也就是说，本文完成的环境配置是后续所有开发工作（在容器内构建、运行测试、提交 PR）的前置条件：后续章节会继续使用你在本文创建的本地 moby-fork 仓库和 dry-run-test 分支。

本文遵循原指南的默认前提：使用 HTTPS 协议 + git 命令行。如果你习惯 SSH 或其他 Git 客户端，可以自行换算，但本文所有命令按 HTTPS 给出。

Task 1：Fork 并克隆 Moby 代码

贡献 Moby 前，先 Fork 上游代码仓库。Fork 是在某一时间点复制一份仓库，托管平台会记录 Fork 的来源。你在自己的 Fork 中修改代码，完成后再向原始 moby/moby 仓库发起 Pull Request。

操作步骤

打开浏览器并登录你的 GitHub 账号。
进入 moby/moby 仓库页面。
点击界面右上角的 Fork 按钮，把仓库 Fork 到你自己的账号下。原始 moby/moby 会变成你账号下的 YOUR_ACCOUNT/moby。
从 GitHub 复制你 Fork 的克隆 URL。平台允许使用 HTTPS 或 SSH 协议克隆，可以用 git 命令行，也可以用图形客户端。
在本地主机打开终端，进入你的主目录：
```
$ cd ~
```
Windows 用户请在 Docker 提供的终端环境中操作（原指南写作时期使用的是 Docker Quickstart Terminal，今天的 Windows 上可等价使用 Git Bash 等终端），而不是 PowerShell 或 cmd。
创建 repos 目录：
```
$ mkdir repos
```
进入 repos 目录：
```
$ cd repos
```
把你的 Fork 克隆到本地，目录命名为 moby-fork：
```
$ git clone https://github.com/YOUR_ACCOUNT/moby.git moby-fork
```
将命令中的 YOUR_ACCOUNT 替换为你的 GitHub 用户名。把本地仓库命名为 moby-fork 有助于对照本指南的说明；有经验者也可以保持默认名称。
进入新克隆的目录：
```
$ cd moby-fork
```
花一点时间熟悉仓库内容并列出目录结构。你会看到 Moby 代码库的主要顶层模块：api/（共享类型与 API 定义）、client/（Go 客户端库）、daemon/（守护进程）、integration/（API 集成测试）、hack/（开发与 CI 脚本）等，这些目录划分在 CONTRIBUTING.md 的「Where to put your changes」一节中有详细说明。

Task 2：设置签名身份与 upstream 远程

为什么必须配置签名

向 Moby 提交代码，你等于在认证自己同意 CONTRIBUTING.md 中收录的 Developer Certificate of Origin（开发者源起证书）。你通过在 git 提交末尾追加签名行来表达同意：

Signed-off-by: Pat Smith <pat.smith@email.com>

要生成签名，需要在 Git 中配置你的用户名和邮箱地址。可以全局设置，也可以只在本地的 moby-fork 仓库上设置（本文采用 --local 局部设置）。签名必须使用真实姓名，Moby 不接受匿名贡献或化名贡献。配置好 user.name 与 user.email 后，可以用 git commit -s 自动追加签名行。

完整的 DCO 1.1 证书文本（(a) 至 (d) 四条认证声明）见 CONTRIBUTING.md「Sign your work」一节，提交前建议通读一遍。

添加 upstream 远程

当你在 Fork 中修改代码时，需要随时与上游 moby/moby 的变更保持同步。为此，要添加一个名为 upstream 的远程（remote），指向 moby/moby。remote 本质上就是托管在互联网或内网上的另一份项目版本。这样 origin 指向你自己的 Fork（用于推送），upstream 指向上游（用于同步），是后续 git fetch upstream、git rebase 同步流程的基础。

Moby 的所有开发变更都进入 master 分支（见 project/BRANCHES-AND-TAGS.md），所以 upstream 远程指向的正是你日常要跟踪同步的目标。

配置命令

进入 moby-fork 仓库根目录：
```
$ cd moby-fork
```

设置本仓库的 user.name：

$ git config --local user.name "FirstName LastName"

设置本仓库的 user.email：

$ git config --local user.email "emailname@mycompany.com"

添加 upstream 远程，指向 moby/moby：

$ git remote add upstream https://github.com/moby/moby.git

用 git config 检查结果：

$ git config --local -l
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
remote.origin.url=https://github.com/moxiegirl/moby.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
branch.master.remote=origin
branch.master.merge=refs/heads/master
user.name=Mary Anthony
user.email=mary@docker.com
remote.upstream.url=https://github.com/moby/moby.git
remote.upstream.fetch=+refs/heads/*:refs/remotes/upstream/*

输出中应能看到 remote.origin.url（你的 Fork）、remote.upstream.url（上游 moby/moby）以及你刚设置的 user.name、user.email。只想查看两个远程时：

$ git remote -v
origin	https://github.com/moxiegirl/moby.git (fetch)
origin	https://github.com/moxiegirl/moby.git (push)
upstream https://github.com/moby/moby.git (fetch)
upstream https://github.com/moby/moby.git (push)

源码印证：签名是如何被 CI 强制校验的

签名不是"建议"，而是 CI 硬校验。从仓库中的校验脚本 hack/validate/dco 可以看到，PR 检查会遍历提交历史，用正则匹配每个提交信息中的签名行：

dcoPrefix='Signed-off-by:'
dcoRegex="^(Docker-DCO-1.1-)?$dcoPrefix ([^<]+) <([^<>@]+@[^<>]+)>( \\(github: ($githubUsernameRegex)\\))?$"

（见 hack/validate/dco#L17-L22）

从这条正则可以读出几个实用信息：

签名行以 Docker-DCO-1.1- 前缀开头（兼容历史提交）或直接以 Signed-off-by: 开头；
姓名后必须跟 <email@example.com> 形式的邮箱；
可选地在行尾追加 (github: 用户名) 标注 GitHub 账号，用户名只允许字母数字和中划线且不能以中划线开头；
纯 Merge 等无内容变更的提交会被跳过；任何一个内容提交缺少合规签名，校验就会列出该提交并以非零码失败，要求你 git commit --amend 补签名后重推。

这解释了为什么 Task 2 强调"必须用真实姓名"——签名行中的姓名与邮箱会随提交永久留存在公开历史中。另外，仓库根目录的 .mailmap 文件与 hack/generate-authors.sh 脚本会基于 git log 的作者信息生成 AUTHORS 文件并按邮箱去重，因此 CONTRIBUTING.md 明确提醒：不要手动把自己加进 AUTHORS，该文件由脚本定期从 Git 历史重新生成。

Task 3：创建并推送一个分支

改代码应在分支上进行，分支名应反映你在做什么。本节创建一个仅用于验证配置的分支：做一次"干跑"（dry run）——建分支、改一个文件、签名提交并推送到你的 Fork。

打开终端，进入 moby-fork 根目录：
```
$ cd moby-fork
```
创建 dry-run-test 分支：
```
$ git checkout -b dry-run-test
```
该命令会创建分支并把仓库切换到该分支。
确认当前所在分支：
```
$ git branch
* dry-run-test
  master
```
当前分支带 *（星号）标记，说明你在新分支上。
在仓库根目录创建 TEST.md 文件：
```
$ touch TEST.md
```
编辑文件，写入你的邮箱和所在地。使用你熟悉的任何文本编辑器即可。
保存并关闭文件。

查看分支状态：

$ git status
On branch dry-run-test
Untracked files:
  (use "git add <file>..." to include in what will be committed)

    TEST.md

nothing added to commit but untracked files present (use "git add" to track)

你只改了一个文件，此时它还是 Git 未跟踪（untracked）的。

添加文件到暂存区：
```
$ git add TEST.md
```
这是唯一被 staged（暂存，即 Git 正在跟踪其变更）的文件。
签名并提交改动：
```
$ git commit -s -m "Making a dry run test."
[dry-run-test 6e728fb] Making a dry run test
 1 file changed, 1 insertion(+)
 create mode 100644 TEST.md
```
提交信息的短摘要句不超过 50 个字符；可选地在摘要后加空行，再写更详细的说明。Moby 对提交信息的完整约定（CONTRIBUTING.md「Commit Messages」）还要求：摘要首字母大写、使用祈使语气（imperative），正文说明问题背景与解决方式；squash 之后要像"一次灵光一现"一样重写提交信息，让每个提交都能独立讲故事。

把改动推送到 GitHub：

$ git push --set-upstream origin dry-run-test
Username for 'https://github.com': moxiegirl
Password for 'https://moxiegirl@github.com':

Git 会提示输入你的 GitHub 用户名和密码，然后返回类似结果：

Counting objects: 13, done.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 320 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To https://github.com/moxiegirl/moby.git
 * [new branch]      dry-run-test -> dry-run-test
Branch dry-run-test set up to track remote branch dry-run-test from origin.

--set-upstream 让本地 dry-run-test 分支与远程 origin/dry-run-test 建立跟踪关系，之后可以直接 git push / git pull 而不必再写远程名。

打开浏览器进入 GitHub。
导航到你的 Moby Fork。
确认 dry-run-test 分支存在、包含你的提交，并且提交带有签名。

提交信息末尾应出现 Signed-off-by: 你的名字 <你的邮箱> 一行。

补充：提交推送前的 Moby 约定速查

配置完成后，在真正开始贡献代码之前，结合仓库文档再记住几条会被审查直接引用的规则（均出自 CONTRIBUTING.md 与 TESTING.md）：

分支命名：修 bug 或加特性都用 XXXX-something 命名，XXXX 是 issue 编号；
测试：每个提交都应保证测试套件通过，单元测试用标准 go test，API 集成测试放在 integration/<component> 目录，遗留的 integration-cli/ 已弃用、不接受新测试；
代码格式：提交前对每个改动文件运行 gofmt -s -w file.go；
PR 卫生：Pull Request 必须干净地 rebase 到 master 之上，用 rebase 而不是 merge master 更新分支；提交前用 git rebase -i 把提交压缩成"逻辑工作单元"，绝大多数 PR 应只有一个提交；
issue 关联：关闭 issue 的提交中写上 Closes #XXXX 或 Fixes #XXXX；
文档同步：功能变更要与文档改动放在同一个 PR 中，保证回滚时不留痕迹。