如何配置Git Smudge/Clean过滤器调用仓库内追踪的脚本

问题背景 #

我在一个使用Jupyter Notebook的数据分析项目中，通过Git的clean/smudge过滤器忽略Notebook的输出内容和部分元数据。但每次调整过滤器配置后，都需要让协作者手动执行git config命令才能生效，希望能让过滤器直接运行仓库中已追踪的脚本，实现配置变更自动同步。

解决方案步骤 #

1. 封装过滤器命令为仓库内可执行脚本 #

在仓库中创建脚本目录（比如scripts/），并新建clean_ipynb.sh脚本，内容如下：

#!/bin/bash
jupyter nbconvert --ClearOutputPreprocessor.enabled=True --ClearMetadataPreprocessor.enabled=True --to=notebook --stdin --stdout --log-level=ERROR

给脚本添加可执行权限：

chmod +x scripts/clean_ipynb.sh

将该脚本提交并推送到Git仓库，确保协作者拉取后能获取到。

2. 创建仓库专属的Git配置文件 #

在仓库根目录创建.gitconfig-repo文件，写入过滤器的配置（使用脚本的相对路径）：

[filter "ipynb-clean"]
    clean = ./scripts/clean_ipynb.sh

将这个配置文件也提交到Git仓库，后续过滤器的规则变更直接修改此文件即可。

3. 让本地Git自动加载仓库配置 #

协作者首次克隆仓库或首次配置时，只需执行一次以下命令，将仓库配置纳入本地Git的仓库级配置：

git config --local include.path ./.gitconfig-repo

这条命令会让Git在操作当前仓库时，自动读取.gitconfig-repo中的配置，后续配置变更只需拉取仓库更新即可生效。

4. 配置.gitattributes关联过滤器 #

确保仓库根目录的.gitattributes文件包含以下内容：

*.ipynb filter=ipynb-clean

将该文件提交到仓库，让Git知道对所有.ipynb文件应用ipynb-clean过滤器。

注意事项 #

• 所有协作者的本地环境需要安装Jupyter Notebook，确保jupyter命令可正常执行。
• 首次配置的git config --local命令只需执行一次，后续仓库配置或脚本更新后，拉取代码即可自动同步过滤器规则。
• 如果需要添加smudge过滤器，可按同样方式封装脚本，并在.gitconfig-repo中添加对应的smudge配置项。

内容的提问来源于Stack Exchange，提问作者Joshua Shew