One-way synchronization of a remote git repository to a local git repository, with automatic conflict resolution.
You can install nbgitpuller from PyPI.
pip install nbgitpuller
You can then enable the serverextension
jupyter serverextension enable --py nbgitpuller --sys-prefix
How to use
nbgitpuller usage guide
to learn how to distribute content for your JupyterHub using
What is it?
nbgitpuller allows you to construct a URL that points to a remote git repository. When it is clicked, nbgitpuller will pull the contents of this repository into the user's current folder within Jupyter, while rendering a nice status page. This is especially useful when running on a JupyterHub, since it allows easy distribution of materials to users without requiring them to understand git.
When a link is clicked, we try to make opinionated intelligent guesses on how to do a merge automatically, without making the user do a conflict resolution. nbgitpuller is designed to be used by folks who do not know that git is being used underneath, and are only pulling content one way from a source and modifying it - not pushing it back. So we have made the following opinionated decisions.
- If content has changed in both places, prefer local changes over remote changes.
- If a file was deleted locally but present in the remote, remote file is restored to local repository. This allows users to get a 'fresh copy' of a file by just deleting the file locally & clicking the link again.
- If a file exists locally but is untracked by git (maybe someone uploaded it manually), then rename the file, and pull in remote copy.
When to use / not use nbgitpuller
You should use this when:
- You are running a JupyterHub for a class & want an easy way to distribute materials to your students without them having to understand what git is.
- You have a different out of band method for collecting completed assignments / notebooks from students, since they can not just 'push it back' via git.
You should not use this when:
- You are an instructor using a JupyterHub / running notebooks locally to create materials and push them to a git repository. You should just use git directly, since the assumptions and design of nbgitpuller will surprise you in unexpected ways if you are pushing with git but pulling with nbgitpuller.
- Your students are performing manual git operations on the git repository cloned as well as using nbgitpuller. Mixing manual git operations + automatic nbgitpuller operations is going to cause surprises on an ongoing basis, and should be avoided.
Constructing the nbgitpuller URL
You can construct a working nbgitpuller URL like this:
myjupyterhub.org/hub/user-redirect/git-pull?repo=<your-repo-url>&branch=<your-branch-name>&subPath=<subPath>&app=<notebook | lab>
- repo is the URL of the git repository you want to clone. This parameter is required.
- branch is the branch name to use when cloning from the repository.
This parameter is optional and defaults to
- subPath is the path of the directory / notebook inside the repo to launch after cloning. This parameter is optional, and defaults to opening the base directory of the linked Git repository.
- app This parameter is optional and defaults to either the environment variable
NBGITPULLER_APP's value or
notebookif it is undefined. The allowed values are
notebook, the value will determine in what application view you end up in.
- urlPath will, if specified, override
subPathand redirect blindly to the specified path.
You can easily set up to develop this locally, without requiring a JupyterHub. It requires python3.
Clone this repository
git clone https://github.com/data-8/nbgitpuller
Change into it and create a virtual environment
cd nbgitpuller python3 -m venv .
Install it with symlinks, so you can easily play with it.
pip install -e .
Enable the jupyter notebook server extension. This provides the
jupyter serverextension enable --sys-prefix nbgitpuller
Run a jupyter notebook locally!
Construct a nbgitpuller URL exactly like you would for a hub, but instead of prefixing it with
myjupyterhub.org/hub/user-redirect, just use
localhost:8888or whatever the url of your running notebook is. For example, the following URL would pull down a repo:
Make the changes you want to make, and restart the jupyter notebook for them to take effect.
Using the command line interface
It is also possible to use
nbgitpuller from the command line. For example,
here's how to synchronize the repository listed above using the command line:
gitpuller https://github.com/data-8/materials-fa17 master my_materials_fa17
This will synchronize the
master branch of the repository to a folder
See the command line help for more information.