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.