nbgitpuller

One-way synchronization of a remote git repository to a local git repository, with automatic conflict resolution.

YouTube video instructions for teachers.

Installation

You can install nbgitpuller from PyPI.

pip install nbgitpuller

You can then enable the serverextension

jupyter serverextension enable --py nbgitpuller --sys-prefix

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.

Merging behavior

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

Launch this Binder for an interactive link generator

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 master.
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 notebook if it is undefined. The allowed values are lab and notebook, the value will determine in what application view you end up in.
urlPath will, if specified, override app and subPath and redirect blindly to the specified path.

Local development

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 git-pull URL handlers.
```
jupyter serverextension enable --sys-prefix nbgitpuller
```
Run a jupyter notebook locally!
```
jupyter notebook
```
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:8888 or whatever the url of your running notebook is. For example, the following URL would pull down a repo:
```
localhost:8888/git-pull?repo=https://github.com/data-8/materials-fa17
```
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 called my_materials_fa17.

See the command line help for more information.

henfee / nbgitpuller