jupyterlab-git是集成于jupyterlab界面的稳定git管理方案，可避免.ipynb文件因outputs、execution_count等json字段变动导致的diff失效与合并冲突，需配合nbstripout清洗提交内容并确保环境一致性。
jupyterlab-git 是目前最实用、最稳定的方案，直接集成在 JupyterLab 界面里，不用切窗口、不记命令、状态实时更新。如果你还在用传统终端手动 git add / git commit 管理 .ipynb 文件，大概率已经踩过输出污染、合并冲突、diff 失效这些坑。
为什么不能直接 git add notebook.ipynb？
因为 .ipynb 是 JSON 文件，每次运行 cell 都会改写 execution_count、outputs、metadata 字段——哪怕你只改了一行代码，Git 也会把整个 cell 当作“全新内容”标为修改。多人协作时，JSON 结构稍有差异就会触发不可自动合并的冲突。
-
outputs字段可能包含图表二进制数据（base64），导致 diff 完全不可读 -
execution_count在不同机器/内核下递增逻辑不一致，纯属噪声 - Markdown cell 的渲染元数据（如
trusted）也会随环境变化，无意义变更
怎么装 jupyterlab-git 并让它真正可用？
装完插件只是第一步，关键是要让它能识别你的仓库、正确过滤 notebook 内容。漏掉任一环节，面板就显示 “No repository found” 或提交后依然满屏 diff。
- 先确保当前目录下已有
.git目录（git init或git clone过）；jupyterlab-git不会自动初始化仓库 - 执行
pip install jupyterlab-git和jupyter labextension install @jupyterlab/git，注意后者需在 JupyterLab 启动前完成 - 重启 JupyterLab（不是刷新页面），且必须从该 Git 项目根目录启动：
jupyter lab --notebook-dir=/path/to/your/repo - 若仍不显示 Git 面板，检查浏览器控制台是否有
Failed to fetch git status—— 很可能是后端没权限调用系统git命令（比如 Docker 容器里没装 git）
怎么避免 .ipynb 提交时带输出和执行序号？
光靠界面操作不够，必须配合 nbstripout 做提交前清洗。否则你在界面上点了 commit，Git 依然会把图表、数字、执行计数全塞进去。
- 在仓库根目录运行
nbstripout --install，它会自动配置.git/config的clean和smudge过滤器 - 确认
.gitattributes文件存在且含这一行：*.ipynb filter=nbstripout；没有就手动创建 - 首次提交前建议先运行
git add --renormalize .，强制重走过滤流程，清理历史残留 - 别依赖 “Save & Commit” 按钮一键搞定——它只 commit 已
git add的文件，而nbstripout是在add阶段起作用的
哪些操作容易被忽略但直接影响协作效果？
团队里一个人没配好，整个分支 history 就会被污染。最常被跳过的其实是环境一致性环节。
-
nbstripout必须在每个协作者本地安装并运行--install，它不随 Git 共享 - 推荐把
nbstripout加进项目requirements.txt，CI 流程里跑pip install -r requirements.txt && nbstripout --install - JupyterLab 版本要和
@jupyterlab/git扩展兼容（例如 JupyterLab 4.x 对应@jupyterlab/git@0.40+），查错先看jupyter labextension list - 别把
.ipynb当源码提交——真正该进 Git 的是清理后的代码逻辑；训练日志、图表输出、大模型权重这些，该存 S3 就存 S3，该写metrics.json就写metrics.json
