nbfilter

Filter .ipynb (nbformat) files to improve integration with version control systems (VCS), specifically git.

Setup

Install from PyPI:

pip install nbfilter

Use from the command line:

python -m nbfilter.clean < research.ipynb | sponge research.ipynb

Integrate into git:

From your repository's root directory:

Run the following command to define a filter called ipynbfilter in your .git/config settings:

git config filter.ipynbfilter.clean 'python -m nbfilter.clean'

Then run one of the following command sequences to trigger it for all files with the .ipynb extension:

printf '*.ipynb filter=ipynbfilter\n' >> .gitattributes # Apply filter for all contributors
git add .gitattributes

or:

printf '*.ipynb filter=ipynbfilter\n' >> .git/info/attributes # Apply filter for just me

To apply it to files that are already under source control (for example, so that diffing subsequent changes produces more intelligible results):

git add --renormalize . # (re-)apply filters to all files currently under source control

or:

git add --renormalize research.ipynb # (re-)apply filters to a single file

References / alternatives

• Min RK's nbstripout gist that started it all (licensed as "Public Domain").

  git pre-commit hook for stripping output from IPython notebooks

• nbstripout is a PyPI-published package that provides all its functionality through a nbstripout console script.

• StackOverflow question: Using IPython notebooks under version control

• Making Git and Jupyter Notebooks play nice uses jq instead of Python to do the JSON modifications, for the sake of speed.

• Jupyter notebooks and version control discusses alternatives to the .ipynb file format that would natively improve git diff'ing (specifically, YAML with some additional constraints).

License

Copyright (c) 2018 Christopher Brown. MIT Licensed.