重写Git历史移除Jupyter Notebook输出后如何协调历史？

一、提前准备：同步与备份 #

• 提前通知所有学生：明确告知仓库历史将被改写，要求在指定截止时间前完成所有本地修改的提交/推送，暂停新开发工作。
• 要求所有学生备份本地仓库：可以用git clone --mirror <原仓库地址> backup-repo.git创建镜像备份，或直接复制本地仓库文件夹。
• 你先在测试环境验证流程：克隆原仓库，运行清理命令，确认所有.ipynb文件的历史输出已清除，文件体积达标。

二、执行历史清理（仅仓库管理员操作） #

1. 确保本地仓库是最新的干净状态：

   git fetch origin && git checkout main && git reset --hard origin/main
   

2. 安装git-filter-repo（替代废弃的git filter-branch）：通过系统包管理器或官方源码安装。
3. 运行清理命令，移除所有.ipynb文件的历史输出：

   git filter-repo --force --blob-callback '
   import json
   if blob.path.endswith(b".ipynb"):
       try:
           nb = json.loads(blob.data.decode("utf-8"))
           for cell in nb.get("cells", []):
               if "outputs" in cell:
                   cell["outputs"] = []
               if "execution_count" in cell:
                   cell["execution_count"] = None
           blob.data = json.dumps(nb, indent=2).encode("utf-8")
       except:
           pass
   '
   

4. 强制推送改写后的历史到远程仓库：

   git push origin --force main
   

   注意：必须确保在此期间没有其他人推送代码，否则会覆盖他们的提交。

三、指导学生同步本地仓库（避免代码丢失） #

分两种场景处理：

场景1：本地无未提交修改 #

• 先备份本地仓库（保险操作）
• 执行同步命令：

  git fetch origin
  git checkout main
  git reset --hard origin/main
  

场景2：本地有未提交修改 #

1. 保存本地修改：
   • 方式一：暂存修改

     git stash push -m "temp-stash"
     

   • 方式二：生成补丁文件

     git diff > local-changes.patch
     

2. 同步远程改写后的历史：

   git fetch origin
   git checkout main
   git reset --hard origin/main
   

3. 恢复本地修改：
   • 若用暂存：git stash pop，如有冲突，手动解决（冲突大概率集中在学生新增的代码/文本，输出部分已被清理，冲突易处理）
   • 若用补丁：git apply local-changes.patch，若报错，手动调整补丁内容后重新应用。

四、后续维护：防止输出再次提交 #

• 确保所有学生配置nbstripout过滤器：

  # 全局配置（所有仓库生效）
  nbstripout --install --global
  # 或仅当前仓库生效
  nbstripout --install
  

• 在仓库根目录添加.gitattributes文件，确保过滤器自动生效：

  *.ipynb filter=nbstripout
  

• 提醒学生提交前可手动运行nbstripout <notebook-file.ipynb>清理输出，或依赖Git自动处理。

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