如何临时停用nbstripout的Git过滤器及排查其异常问题

1. 临时关闭nbstripout的Git过滤器 #

有两种实用的临时禁用方式，按需选择：

• 针对单个Git命令跳过过滤：执行git diff、git commit等命令时，通过参数覆盖过滤器配置，比如：

  # 临时跳过clean过滤器执行diff
  git -c filter.nbstripout.clean= diff
  # 临时跳过过滤器提交文件
  git -c filter.nbstripout.clean= commit your_notebook.ipynb
  

  如果需要同时跳过smudge过滤器（nbstripout一般仅用clean，可按需添加）：

  git -c filter.nbstripout.clean= -c filter.nbstripout.smudge= diff
  

• 临时在当前仓库禁用所有nbstripout过滤：先备份配置，修改后用完再恢复：

  # 备份当前nbstripout配置
  git config --get filter.nbstripout.clean > nbstripout_backup.txt
  # 禁用过滤器
  git config filter.nbstripout.clean ""
  # 执行你需要的操作（比如diff、commit）
  # 恢复原配置
  git config filter.nbstripout.clean "$(cat nbstripout_backup.txt)"
  rm nbstripout_backup.txt
  

2. 排查特定Notebook文件的异常原因 #

按以下步骤逐步定位问题：

• 手动执行nbstripout对比差异：直接对目标文件运行工具，看处理前后的真实变化：

  cp your_notebook.ipynb backup.ipynb
  nbstripout your_notebook.ipynb
  diff backup.ipynb your_notebook.ipynb
  

  如果diff无内容但Git仍标记修改，说明问题出在换行符、权限等Git跟踪的属性上，而非文件内容。
• 检查Git的过滤绑定情况：确认nbstripout是否正确应用到该文件：

  # 查看仓库的nbstripout配置
  git config --get-regexp filter.nbstripout
  # 检查文件的过滤规则匹配情况
  git check-attr --all your_notebook.ipynb
  

  正常输出会显示your_notebook.ipynb: filter: nbstripout，如果没有，说明.gitattributes配置可能有误，文件没绑定到过滤器。
• 排查换行符和权限变化：Git常因换行符（LF/CRLF）或权限变更标记文件为修改：

  # 查看换行符相关的差异
  git diff --cached --numstat
  # 查看权限变化
  git diff --cached --summary
  

• 启用nbstripout调试模式：获取工具处理文件的详细日志，定位解析或处理异常：

  NBSTRIPOUT_DEBUG=1 nbstripout your_notebook.ipynb
  

  调试日志会展示文件读取、JSON解析、输出清理的全过程，帮你找到异常点。
• 检查Notebook的JSON结构：用文本编辑器打开文件，查看是否有损坏的JSON格式、未清理的execution_count/outputs字段，或隐藏的元数据——nbstripout依赖正确的JSON结构才能正常工作。

内容的提问来源于stack exchange，提问作者Paul Rougieux