jupyter-histree v0.1.1
Histree
A history tracking tool for JupyterLab, based on Verdant by Mary Beth Kery. The purpose of Histree is to provide a JupyterLab extension that does tree-based history tracking with branching capabilities.
Check out our paper (preprint) for the research behind this tool.
Install
- Jupyterlab: Histree works with > JupyterLab 3 (latest version). To install or update your JupyterLab:
- with pip:
pip install jupyterlab -U
- with conda:
conda install -c conda-forge jupyterlab
- to check version:
jupyter lab --version
- for windows users!: due to a bug with lab extensions in earlier 3.0 releases, be sure you have >=
3.0.7
of JupyterLab - tested with JupyterLab version 3.0.X
- NodeJs: JupyterLab needs node to configure and install extensions, not just Histree
- to check if you have node installed
node --version
- to install: Official NodeJS installers
- tested with NodeJS version 16.X.X
- Histree:
- with the JupyterLab extension manager: look for "jupyter-histree" in the extensions menu (the puzzle icon in the sidebar of JupyterLab) and click "Install".
- alternatively, with the command line:
jupyter labextension install jupyter-histree
- If the installation was successful, the Histree extension will be available in the sidebar on the left!
Develop
To build Histree from source code, execute the following commands in the source code directory:
yarn
yarn build
yarn start
After making modifications to the code, use the following commands to rebuild (this will take a while every time):
yarn build
yarn start
In case you wish to apply your changes more quickly, you can use hot-reloading:
- Open up a command line in the source code directory and enter
jupyter lab --watch
- Open up a second command line in the source code directory and enter
yarn watch
Now the changes will be applied automatically within seconds after saving changes within the source code.
Known Issues
This is an experimental extension not yet properly released, and may contain bugs that could cause problems with your Jupyter Notebooks. Please use at your own risk. Here are a few issues that we are currently aware of:
- Reordering cells can sometimes cause issues with the history tracking
- Copy/Pasting of cells can cause similar problems
Acknowledgments
This tool has been developed as part of a project supervised by Selin Aydin at the Research Group Software Construction of RWTH Aachen University.
Thank you to Mary Beth Kery for the original Verdant extension and our study participants for all the valuable feedback on earlier versions!