Pre-Commit Hooks

如何使用 nbdev 的 Git pre-commit 钩子

我们为 pre-commit 框架 提供了钩子，用于在本地捕获和修复未清理或未导出的 notebook，无需等待持续集成（CI）流水线运行。

如果你使用的 notebook 编辑器（例如 VSCode）尚未支持 Jupyter clean 钩子，它们也可以作为替代方案。

安装 pre-commit

…安装 pre-commit（如果遇到困难，请查阅 他们的最新说明）

pip install pre-commit
conda install -c conda-forge pre-commit
brew install pre-commit

为你的仓库配置 pre-commit

在你的仓库根目录下创建一个名为 .pre-commit-config.yaml 的文件，内容如下：

repos:
- repo: https://github.com/fastai/nbdev
  rev: 2.2.10
  hooks:
  - id: nbdev_clean
  - id: nbdev_export

只包含你希望运行的一个或多个钩子，以及任何其他 支持的钩子。

提示

如果你期望所有协作者都使用 pre-commit，请将 .pre-commit-config.yaml 文件添加到你的仓库中。否则，请将其添加到你的 .gitignore 文件中。

将 pre-commit 钩子安装到你的仓库中

pre-commit install

提交并体验 pre-commit 的作用

当你在一个安装了 pre-commit 钩子的仓库中执行 git commit 时，你的新工作流程将如下所示：

  1. pre-commit 会对你已暂存的更改（即你执行 git add 的更改）运行每个钩子。
  2. 如果某个钩子修改了文件——例如，如果提交的 notebook 未经清理——pre-commit 会停止提交，并将这些更改保留为*未暂存*状态。
  3. 你现在可以暂存这些更改，并进行任何必要的编辑以使 pre-commit 通过。
  4. 重新执行 git commit，如果成功，你的提交将被创建。

在实际使用中，它并没有听起来那么复杂。了解它是否适合你的最佳方法是亲自尝试一下。

当你遇到困难时如何覆盖 pre-commit

如果你努力尝试让 pre-commit 通过你认为绝对正确的提交，可以像这样 暂时禁用某个钩子：

SKIP=hook git commit

...这里的 hook 指代配置中有效的钩子，例如，禁用 nbdev_export 钩子：

SKIP=nbdev_export git commit

你也可以使用 --no-verify 标志完全禁用 pre-commit：

git commit --no-verify

最后，如果你决定不使用它，可以使用以下命令从你的仓库中完全移除 pre-commit 钩子：

pre-commit uninstall