nbgitpuller

nbgitpuller lets you distribute content to a Jupyter user via the click of a button! This allows your users to focus on the content without needing to understand git or other version control machinery.

nbgitpuller provides automatic, opinioned conflict resolution by using git under the hood. It is commonly used to distribute content to multiple users of a JupyterHub, though it works just fine on an individual person’s computer, if they have Jupyter installed.

Here’s an example of nbgitpuller in action:

1. The nbgitpuller link generator is used to create a link.

   

2. A user clicks the link, and the content is pulled into a live Jupyter session.

   

Use nbgitpuller

See Using nbgitpuller for information about how to use nbgitpuller. Here’s a short overview:

1. Ensure your user has nbgitpuller installed. This is commonly done by installing it for all users of a JupyterHub. See the installation instructions for more information.

2. Create an “nbgitpuller link” which points to the content you’d like to distribute (e.g., a Jupyter Notebook in a GitHub repository).

3. Tell your user to click the link, and nbgitpuller will automatically pull in the content to their file system.

Generate an nbgitpuller link

There are several ways to generate an nbgitpuller link. The two easiest ways to do so are:

• Via a browser extension to generate links directly from your repository (Chrome extension, Firefox extension

• Via a GUI web-app at nbgitpuller.link

Fore more information about generating nbgitpuller links, see Using nbgitpuller.

When to use nbgitpuller

Use nbgitpuller when:

1. You want an easy way to distribute content (notebooks, markdown files, etc) to Jupyter users without requiring them to use git.

2. You have an alternative method for collecting content from your users, as nbgitpuller does not “push”, it only “pulls”.

You should not use nbgitpuller when:

1. Users want to push to a git repository that has your content. In this case, you should instruct them to 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.

2. Users want to perform manual git operations locally. Mixing manual git operations + automatic nbgitpuller operations will cause unwelcome surprises.

Full Contents

• Installation
  • Troubleshooting
• Using nbgitpuller
  • Overview of nbgitpuller links
  • Create an nbgitpuller link via a web extension
  • Automatically create an nbgitpuller link via a web app
  • Manually create an nbgitpuller link
• Contributing
  • Setup
  • Running tests
  • Building documentation
• Automatic Merging Behavior
  • Case 1: The instructor changed a file that the student has not changed
  • Case 2: Student & instructor changed different lines in same file
  • Case 3: Student & instructor change same lines in same file
  • Case 4: Student deletes file locally, but instructor doesn’t
  • Case 5: Student creates file manually, but instructor adds file with same name
• Options in an nbgitpuller URL
  • repo
  • branch
  • urlpath
  • depth
  • targetPath
  • Deprecated parameters
• Content git repository best practices
  • Never force push
  • Prevent your repos from becoming huge
  • Don’t add .ipynb_checkpoints (and similar files) to your git repo
• Frequently asked questions
  • Can I automatically tell JupyterHub what kind of server to start (node size, profile name, etc) as part of my nbgitpuller link?
• nbgitpuller link generator