不能把 .ipynb 文件当普通代码文件直接提交到 git，因其 json 结构含 outputs、execution_count 等动态字段，导致无意义 diff 和合并冲突；应使用 nbstripout 清理后提交，并辅以 jupyterlab-git 提升操作效率。
直接说结论：不能把 .ipynb 文件当普通代码文件直接扔进 Git —— 否则每次运行单元格都会触发大量无意义 diff，合并冲突频发，团队协作几乎瘫痪。真正可行的方案是「开发态保留完整 Notebook，提交态只留纯净代码结构」，靠工具链自动转换。
为什么 git diff 里全是 JSON 变更？
因为 .ipynb 是 JSON 格式，包含 outputs、execution_count、metadata 等动态字段。哪怕只 rerun 一个 cell，Git 就认为整个文件被重写。
- 执行一次
plt.plot(x, y)→outputs字段新增 base64 图像数据 → diff 出几百行 - 改一行代码但没清空输出 → Git 记录的是“代码+旧图+新图”的混合变更
- 两人同时编辑同一 notebook → JSON 结构微小差异导致 merge conflict 无法自动解决
怎么让 .ipynb 提交变干净？用 nbstripout
nbstripout 是专为 Jupyter 设计的 Git 过滤器，它在 commit 前自动剥离非代码内容，确保 Git 只看到你真正改的逻辑。
- 安装并启用：
pip install nbstripout && nbstripout --install - 它默认移除：
outputs、execution_count、metadata.widgets、metadata.language_info - 生效范围仅限当前仓库（
.git/config中写入 clean/smudge 规则） - ⚠️ 注意：必须在所有协作者机器上都运行
nbstripout --install，否则有人漏装就会把带输出的 notebook 提交进来，污染整个历史
要不要装 jupyterlab-git 插件？
装，但别指望它解决 diff 问题 —— 它只是把 git status、git add、git commit 搬进 JupyterLab 界面，底层还是走系统 Git。它的价值在于降低操作门槛，尤其适合不熟悉命令行的数据科学家。
- 安装：
pip install jupyterlab-git && jupyter labextension install @jupyterlab/git - 重启后左侧出现 Git 面板，可直观看到 modified/untracked 文件、一键暂存、填 message 提交
- 但它不干预
.ipynb内容 —— 如果没配nbstripout，界面上看到的 diff 依然满屏 JSON - 真正省心的组合是：
nbstripout处理内容 +jupyterlab-git处理操作流
训练日志和图表别留在 notebook 里
Git 管的不是“结果”，而是“可复现的过程”。把 loss 曲线、指标表格、模型权重这些产出物全塞进 notebook，等于把实验报告和实验记录混成一团。
- 训练中用
tensorboard或wandb单独记录指标，生成独立events.out.tfevents或云端链接 - 关键数值导出为
metrics.json或results.csv，这类纯文本文件 Git 天然友好 - 图表用
plt.savefig("loss.png")单独保存，加进.gitignore或按需提交（如最终版对比图） - notebook 里只留：数据加载逻辑、模型定义、训练循环骨架、少量验证代码 —— 全是可复现的源码
最常被忽略的一点：清理不是一次性动作。只要 notebook 还在本地打开并运行，就可能悄悄积累输出；每次提交前务必确认 git status 显示的变更是否真的只含代码改动 —— 别依赖插件界面，亲手跑一遍 git diff 最可靠。
