Git for Jupyter Notebook¶

The ClearML Jupyter plugin is a Jupyter Notebook extension which enables you to push ipython notebooks to a Git repository, using a git button (see Screenshots) added to the notebook toolbar.

After saving a notebook, you can push the notebook to a predefined Git repository (currently, pushing to a specific predefined branch is supported).

When you click the version-control button, the following happens:

The notebook .ipynb file is pushed to the Git repository based on the folder structure in which it is located.
The notebook is converted to a .py script, pushed alongside the .ipynb file.
A requirements.txt is created, updated according to the notebook imports, and pushed alongside the .ipynb file.

For example, if you have the following two repositories:

repo1/
├── .git
└── experiment1/
   └── notebook.ipynb

repo2/
├── .git
└── experiment2/
   └── notebook2.ipynb

When you click the version-control button, notebook1.ipynb is pushed to the repo1 repository, and notebook2.ipynb is pushed to the repo2 repository.

To select the predefined branch into which the files will be pushed, use git checkout on the jupyter host machine.

For example, switch to branch2 in repo2:

$ cd ~/repo2
$ git checkout branch2

After switching, the jupyter notebook pushes to the branch2 branch in the repo2 repository.

Installation¶

To use the plugin, execute the following script which installs the plugin and configures Jupyter to use it:

pip install clearml-jupyter-plugin

if [ ! -f ~/.jupyter/jupyter_notebook_config.py ]; then
   jupyter notebook --generate-config
fi
echo 'c.NotebookApp.disable_check_xsrf = True' >> ~/.jupyter/jupyter_notebook_config.py

jupyter serverextension enable --py clearml-jupyter-plugin
sudo jupyter nbextension install --py clearml-jupyter-plugin

To enable the extension for all notebooks:

jupyter nbextension enable --py clearml-jupyter-plugin

Using the plugin¶

After the installing the plugin and configuring Jupyter:

Clone your Git repository to a folder that will be assigned to a specific user.
Checkout a specific branch for the current user.
Make sure git is configured with the correct credentials (we recommend verifying a password/passphrase is required when pushing).
Run Jupyter Notebook.
Any commit/push of notebooks from this specific folder are to the checked out branch.

Screenshots¶

An additional button to the Jupyter toolbar:

The git push dialog for pushing the notebook:

Acknowledgements¶

Thanks to Lab41/sunny-side-up & sat28/githubcommit for laying the foundations for this plugin.