跳转至

P2-14.2 分支（branch）、提交（commit）与文档可复现性

Section ID: P2-14.2 Version: v2026.07.20

在 P2-14.1，我们把 Git 看成变更历史管理工具。现在，顺着文档项目的写作流程，把分支（branch）、提交（commit）和已发布文档的可复现性连接起来。

这一节不是为了深入学习 Git。关键是理解：当学习文档变大时，为什么要把写作分支和部署分支分开，为什么要谨慎处理提交边界。现在先抓住这个流程，到了 Part 3 以后，即使模型比较和实验记录增多，也不会把 还在写作中的判断 和 已经可以发布的说明 混在一起。

本节说明 分支（branch）、部署（deployment）、工作流（workflow）、静态部署（static deployment）、文档可复现性（document reproducibility） 的基本区分。Git 本身和提交单位的代表性说明放在 P2-14.1 与概念词汇表；这里重点说明：这些记录应该怎样按工作线和公开标准进行分离。

本节聚焦于工作流分离和部署标准。如果前一节讨论的是“怎样记录变更”，这里的问题就变成“这些记录应该留在哪条工作线上，以及什么时候转入公开标准”。因此，分支不是开发者才需要的附加功能，而是一种运行标准：把前面章节里形成的正文、代码、图片解释区分成 写作中的判断 与 可公开的说明。

这里改变的抓手 现在先检查什么
git history 哪个变更理由应该作为一个提交单位留下？
branch workflow 这个变更应该留在写作分支还是部署分支？
deployment criteria 它什么时候可以转成对外公开的说明？

核心判断标准：分支（branch）、提交（commit）与文档可复现性

  • 能把分支解释为“分离工作流的有名字的历史线”。
  • 能说明文档项目中写作分支和部署分支的角色差异。
  • 能从文档可复现性的角度划分提交单位。
  • 能说明部署前要检查哪些文件关系。
  • 能说明在 GitHub Pages 这类静态部署流程里，部署分支更新意味着什么。

先抓住的标准

这一节首先要抓住的标准，是把 写作中的判断 和 可公开的说明 分开留下。

你现在看到的对象 首先要问的问题
分支（branch） 这个变更属于写作线，还是部署线？
提交（commit） 它能否被归成一个单一的变更理由？
部署（deployment） 它是否已经完成面向公开文档的检查？
文档可复现性 正文、代码、图片和设置是否彼此一致？

换句话说，Git 不应被读成简单存储工具，而应被读成一种运行工具：决定 什么判断在什么时候、按什么公开标准被留下。

三个判断标准

标准 为什么重要 本节需要达到的理解程度
为什么需要分支？ 它防止“写作中的判断”和“公开标准”混在一起。 理解它是为了把写作工作和发布工作分开。
写作分支和部署分支有什么不同？ 它让你得到真正的工作流分离标准。 理解一个负责写作与检查，另一个负责落实公开标准。
部署前要检查什么？ 它避免你遗漏公开前最终检查的范围。 理解要一起检查链接、目录、构建状态和当前分支方向。
术语 本节先抓住的含义
分支（branch） 在同一个仓库中用来分离工作流的一条有名字的历史线。
部署（deployment） 把读者可见的静态站点或文档结果更新到真实公开状态的动作。
工作流（workflow） 规定写作、检查、部署按什么顺序、用什么标准分开的运行方式。
静态部署（static deployment） 把预先生成的文档文件直接作为网站公开的方法。
文档可复现性（document reproducibility） 重新对齐正文、代码、图片和设置后，能再次得到同样文档结果的性质。

这一节之后的流向也很简单。

  • 紧接着的 Chapter 15 会把文档项目自动化和部署流程连接到更实际的运行场景里。
  • 到了 Part 3 以后，实验记录与比较表变多时，这里建立的分支、提交、可复现性标准会原样再次被需要。

分支用来分离工作流

Git 官方书把分支解释为指向提交的轻量指针。与其把这些内部表述全部背下来，不如把分支理解成：在同一个项目里，为了分离工作流而设置的一条有名字的历史。

在文档项目里，下面这些情况会需要分支。

  • 需要区分“仍在写作中的正文”和“已经在发布中的正文”。
  • 实验性的目录改动不应立刻反映到公开版。
  • 当图片、代码、文档结构一起变化时，中间状态不应被直接公开。
  • 如果部署失败，需要追踪到底是哪次变更造成的。

分支并不只是开发者的便利功能，而是保护读者真正看到的文档稳定性的装置。

在文档项目里，可以把写作分支和部署分支分开

在文档项目里，可以把写作中的分支和部署标准分支分开运作。不同团队的分支名字会不同，但例如可以把角色分成写作分支与部署分支。

flowchart TD
  A["写作分支<br/>一般写作与编辑"]
  B["复核<br/>构建与检查"]
  C["部署分支<br/>对外公开的真实来源"]
  D["静态站点部署<br/>让读者可见的书站点"]

  A --> B --> C --> D

写作分支是普通写作与编辑使用的一类分支示例。你可以把添加正文、编写示例代码、修改图表、整理调查笔记等工作，理解为在这种写作分支上进行。

部署分支则是体现公开标准的一类分支示例。在静态站点部署中，变更一旦进入这个分支，就可能直接触发部署。因此，把工作移入部署分支，不应被看成单纯保存，而应被看成更新公开文档的动作。

有了这个区分，到了 Part 3，即使尝试不同 baseline、重新做预处理、修改评价表解释，这些中间判断也不会立刻凝固成公开标准。也就是说，分支运作的核心就是把 仍在写作中的比较 和 已经可以发布的说明 分开。

提交应该成为“可发布说明”的单位

在文档项目里，一个好的提交更接近“完成了一单位说明”，而不是“文件发生了变化”。

例如，在编写 P2-13.3 时，下面这些文件可能会一起变化。

文件类型 例子 为什么要一起看
正文 section-03.md 读者实际阅读的主文
图片生成代码 p2_13_3_compare_and_save.py 能重新生成输出图像的原始来源
图片 subplot-loss-accuracy.png 插入到正文里的结果
调查笔记 section-evidence-analysis.md 说明背后的依据与范围判断
网站导航设置 导航配置文件 在公开文档中暴露出来的路径

如果这些文件彼此相关，把它们放进同一个提交就很自然。相反，如果同一时间还修改了 CSS 布局，那么把那部分拆成另一个提交，会让以后阅读历史更容易。

文档可复现性比代码可复现性更宽

在软件里，可复现性（reproducibility）通常被解释为：在同样代码和环境下，再次得到同样结果的能力。在这本书里，我们把文档可复现性看得更宽一些。

文档可复现性应该能回答下面这些问题。

  • 这段说明是依据什么写出来的？
  • 正文中的图表是由什么代码生成的？
  • 示例代码默认了哪些包版本？
  • 它是在什么时候进入部署目录的？
  • 如果以后发现错误，应该去哪个提交里修？

因此，文档可复现性不是只有正文的问题。正文、代码、图片、调查笔记、部署设置都必须彼此对齐。这个标准也会直接连接到 Part 3 的实验可复现性，因为当你修改 baseline、特征或重新解释评价指标时，必须始终清楚 正在比较的是哪一个时点的代码和说明。

部署前要检查连接关系

在部署前，至少要检查下面这些连接。

检查对象 检查问题
Markdown 正文 图片和内部链接是否真的指向存在的文件？
网站目录设置 新文档是否连接进了 nav？
示例代码 正文中的代码和生成脚本是否彼此一致？
图片 是否存在裁切、重叠或容易误解的地方？
调查笔记 正文中的主张是否真的与来源连接上了？
构建 mkdocs build 是否通过？

如果不做这些检查，那么变更进入部署分支后，公开页面上就可能出现链接损坏、图片缺失，或说明和示例互相不一致的问题。

如果把它改写成更短的检查表：

部署前检查 为什么需要
正文与链接 为了确认读者实际会走到的路径是正确的
图片与代码 为了确认说明和结果没有脱节
nav 与文件 为了确认文档真的暴露在公开文档集里
构建 为了确认整个站点不会损坏
当前分支 为了避免把写作中的变更误部署出去

反映到部署分支需要单独判断

在文档项目里，通常不要把普通写作中的变更直接反映到部署分支，因为一旦反映到部署分支，就可能直接意味着更新公开文档。

因此，可以建立一种运行标准：只有当“这次变更已经达到公开文档标准”这个判断明确成立时，才把它移动到部署分支。

相对地，写作中的正文修改和实验中间整理，默认放在写作分支上会更安全。

用案例来看

案例 1. 还没检查完的正文如果上了部署页面，会出现什么问题

假设一位作者正在写作分支上整理新章节，并同时修改正文、图片和网站目录设置。此时构建还没有完全确认，内部链接是否正确也仍在检查中。

如果这时立刻把它反映到部署分支，公开部署页面就可能把这种中间状态原样暴露出来。目录里已经能看见文档，但正文链接可能是坏的；图片文件已经替换，但说明段落还停留在上一版。也就是说，写作中的草稿被直接变成了公开文档。

所以，把写作分支和部署分支分开，并不是单纯的习惯，而是保护公开稳定性的装置。在写作分支上推进正文和实验，而在移入部署分支之前，要再检查一次构建、链接、图片、目录和来源连接。

这个案例也说明：为什么文档可复现性同时涉及提交边界和分支运作。一本被部署的书，并不是正文对了就够了，围绕正文的代码、资源和设置也要一起对上，才能再次展示同样的结果。

这一节不是要背更多 Git 命令，而是要决定：前面各节里形成的计算与解释，应该按什么标准被留下。

前面章节已经做出的内容 本节现在负责什么 这里还不做什么
数组计算、表检查、图形解读 决定哪些变更应归成一个提交单位，以及该放在哪个分支上 复杂合并策略、冲突解决、高级协作工作流

简短回看表

卡住的场景 先回到哪里
对“为什么需要 Git”又变模糊了 P2-14.1
对可复现性与依赖关系的连接又变模糊了 P2-7.5, P2-10.3
对“为什么笔记本、图表、正文记录会一起移动”又变模糊了 Chapter 10, Chapter 13

检查清单

  • 能把分支解释成分离工作流的有名字的历史线吗？
  • 能说明写作分支和部署分支的角色差异吗？
  • 能说明提交不该只是文件打包，而应是有意义的变更组合吗？
  • 能按变更目的选择哪些文件应放进同一个提交吗？
  • 能说明文档可复现性不只是正文的问题，而是正文、代码、图片、调查笔记和部署目录都要一起对齐吗？
  • 能说明反映到部署分支可能直接连到公开部署，因此需要单独判断吗？
  • 当需要把写作中的变更和可发布的变更分开管理时，能先想起分支与提交单位的视角吗？
  • 能说明为什么部署前要一起检查网站目录设置、图片、调查笔记和构建吗？

来源与参考资料