4.1 版本控制
4.1 版本控制
本节摘要：SOURCE 4.1 讲 Git 管理 ipynb：git init/add/commit、忽略 checkpoints、nbdime 可视化 diff、jupytext 文本化备选，以及 main/develop/feature 分支策略。本节保留 nbdime 安装命令与 Mermaid 分支流图要点。
你能学到什么
阅读完本节，你应当能够：
- 在 Notebook 项目目录 git init 并提交 ipynb
- 配置 .gitignore 忽略 .ipynb_checkpoints
- 安装并启用 nbdime 改善 git diff
- 描述 feature 分支合并到 develop 的基本流程
一、Git 基础操作
SOURCE 流程：
git init git add analysis.ipynb git commit -m "Initial notebook"
提交前在 Jupyter 执行 Cell → All Output → Clear All Output（SOURCE 第 10 节）——输出 JSON 让 diff 膨胀且 nbdime 仍难读无意义图像 diff。
.gitignore 建议（SOURCE）：
.ipynb_checkpoints/ *.ipynb~
二、为什么 raw git diff 难读
ipynb 是 JSON：代码、Markdown、输出、metadata 交错。git diff 默认一行 JSON 变更人类无法 review。nbdime 专为 Notebook 设计：
pip install nbdime nbdime config-git --enable
之后 git diff 会高亮单元格级变更——代码格、Markdown 格、输出分开显示。
| 方案 | 优点 | 缺点 |
|---|---|---|
| nbdime | 保留 ipynb 格式 | 需团队统一安装 |
| jupytext 配对 .py | 纯文本 diff | 损失部分元数据 |
| 仅提交 .py 模块 | 最简单 | Notebook 本身不进库 |
三、分支策略（SOURCE Mermaid）
SOURCE 给出 main / develop / feature / hotfix 关系。简化实践：
Notebook 项目常见约定：每人 feature 分支改 ipynb，PR 前 Restart & Run All 通过再请求合并。
协作提交检查
四、jupytext 备选
SOURCE：可将 Notebook 转为 纯文本（percent 或 light 格式）再 diff。适合 CI 强制文本审查；教学仓库仍可用 nbdime + Clear Output 为主。
⚠️ 常见坑：合并冲突出现在同一单元格——优先沟通「谁改哪几格」，或拆 Notebook 按章节分文件。
💡 关键直觉：Git 跟踪的是「叙事+代码+可复现性」，不是「上次运行的随机输出」。
本章回顾
- Clear Output 再 commit
- .gitignore checkpoints
- nbdime config-git --enable
- feature → develop → main
- jupytext：文本 diff 备选
下一节 4.2 导出与分享格式 给非 Git 读者发 HTML/PDF。
提交前自查清单（可贴进 README）
[ ] Clear All Output（Cell → All Output） [ ] Restart & Run All 一次通过 [ ] .gitignore 包含 .ipynb_checkpoints/ [ ] requirements.txt 或 conda env.yml 已更新 [ ] 本次改动只涉及预期单元格
用 nbdime 查看具体变更
配置完成后，git diff 会进入 nbdime 的视图，明确标出"哪个单元格新增、哪个删除、哪个内容变化"。审 Notebook PR 时先看 Markdown 格的变化（讲清楚改了什么逻辑），再看 Code 格，最后确认输出已被清空。
分支策略的轻量版
- main：可发布的版本，通常只有一个。
- develop：日常集成，feature 合并进来。
- feature/xxx：一人一条，改完即合。
- hotfix：紧急修复，从 main 拉出，修完同时合回 main 与 develop。
个人项目可以砍掉 hotfix，直接 feature → main；团队超过三人再上 develop 更省心。
jupytext 适合什么场景
如果团队审查对纯文本有硬性要求（CI 里 diff 白名单），可以配 jupytext 生成 .py 配对文件，审查看 .py，运行仍用 .ipynb。代价是两处要同步，配置不好会出现内容漂移。教学仓库推荐直接 nbdime + Clear Output，少一层同步成本。
回滚：如何撤销一次坏提交
git log --oneline -5 # 找坏提交的哈希 git revert <hash> # 生成反向提交，保留历史 git checkout <hash> -- 文件 # 单文件回退到指定版本
Notebook 项目优先用 revert 而不是 reset：revert 留下"撤销记录"，适合团队仓库；reset 改写历史，只在未推送的个人分支上使用。
提交信息的写法
一句话提交信息在 Notebook 项目里格外重要，因为 diff 往往很长：建议写成"动词 + 对象 + 为什么"，例如"重写 3.2 清洗逻辑：改用中位数填充缺失值"。不要写"update notebook"这类无信息提交，review 时没人能靠它定位改动。
文件改名与历史
重命名 Notebook 前先确认团队引用：README 里的文件名、脚本里 %run 的路径、CI 的触发条件都可能指向旧名。改名后运行一次全量 QC 与 Run All，确保没有断链。
冲突解决的现实顺序
Notebook 合并冲突几乎总发生在同一个单元格。解决顺序建议：先看冲突发生在哪个单元格，双方是否改了同一段代码；能合并就手工拼，不能就约对方确认哪份保留。比技术更重要的是约定：feature 分支之间尽量不并行改同一份 Notebook，按章节拆文件是治本方案。
提交频率的把握
Notebook 提交频率不宜太低。每完成一个阶段（读完一章、修完一个 bug、跑通一次全流程）就提交一次，提交信息写清本阶段做了什么。回滚时粒度小、成本低，同事审查时也能按阶段理解演进过程。
审阅 Notebook 的具体步骤
作为 reviewer，建议按这个顺序审：先看 PR 描述和提交信息是否说明改了哪几格；再看 Markdown 格的变化，理解逻辑改动；然后看代码格是否有明显错误；最后确认输出已清空、依赖说明是否更新。顺序固定下来，review 效率会稳定很多。
版本控制的价值衡量
版本控制省下的时间不在提交那一刻，而在回溯那一刻。三个月后要恢复某个实验的旧版本、要查某个结论是哪次改动引入的、要对比两份 Notebook 的差异——这些场景下，提交历史里清晰的记录就是唯一可靠的时间线。