Pre-Commit Hooks

How to use nbdev’s git pre-commit hooks

We provide hooks for the pre-commit framework to catch and fix uncleaned and unexported notebooks, locally, without having to wait for continuous integration pipelines to run.

They might also be useful as an alternative to the Jupyter clean hook if you’re using a notebook editor that isn’t yet supported (e.g. VSCode).

Install pre-commit

…Install pre-commit (check their latest instructions if you have any difficulty with these commands):

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

Configure pre-commit for your repo

Create a file named .pre-commit-config.yaml in the root of your repo, with the following contents:

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

Include only the hook(s) you’d like to run, as well as any other supported hooks.

Tip

If you expect all collaborators to use pre-commit, add the .pre-commit-config.yaml file to your repo. Otherwise, add it to your .gitignore.

Install pre-commit hooks into your repo:

pre-commit install

Make a commit and enjoy pre-commit in action

When you do a git commit in a repo that has pre-commit hooks installed, your new workflow will be as follows:

  1. pre-commit runs each hook on your staged changes (as in, changes that you git added)
  2. If a hook changes files – for example, if a commited notebook wasn’t cleaned – pre-commit stops the commit, leaving those changes as unstaged
  3. You can now stage those changes and make any edits required to get pre-commit to pass
  4. Redo the git commit, and if it succeeds, your commit will be created.

Using it in practice isn’t as complicated as it might sound. The best way to figure out if it works for you is to give it a try.

How to override pre-commit if you get stuck

If you struggle to get pre-commit to pass a commit that you absolutely think is correct, you can temporarily disable a hook like this:

SKIP=hook git commit

…where hook refers to a valid hook in your configuration, for example, to disable the nbdev_export hook:

SKIP=nbdev_export git commit

You can also disable pre-commit entirely with the --no-verify flag:

git commit --no-verify

Finally, if you decide it’s not for you, you can completely remove pre-commit hooks from your repo with:

pre-commit uninstall