Better sharing UX with nbgitpuller and contextual error handling

2026-04-09T15:02:00+00:00

TL;DR

nbgitpuller now has improved UX context-aware error handling. Update to version 1.3.0 and let us know what you think by opening an issue 🚀

What is 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, opinionated 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:

The author uses the nbgitpuller link generator to create a link.

The consumer clicks the link, and the content is pulled into a live Jupyter session.

Example use cases for sharing with nbgitpuller include:

Interactive demos
Workshop and training scenarios
University exams

and many more!

How does nbgitpuller work?

The nbgitpuller package is installed in the compute environment. The compute environment now has a /git-pull endpoint URL that can understand where to pull content from using URL parameters. Syncing content critically depends on git operations to fetch, checkout, clone, merge, commit, etc.

When it goes wrong

Based on the data sent through by the kind folks running the Berkeley DataHub, there were 2163 logs available, of which:

983 (45%) were ‘merge’ conflicts
493 (23%) were ‘fetch’ errors
467 (22%) were ‘ls-remote’ errors

Bar chart showing the most common errors users faced.]

The remaining errors (10%) were mostly ‘checkout’ errors. This represents the most frequent errors as seen by students.

Bar chart showing the most unique errors link authors made.

In the same set of logs, there were 172 unique errors: most ‘ls-remote’ errors come from mistakes in the content repo URL. This represents the most uniquely common errors made by instructors.

Merge conflicts

If the link author changes content after the consumer clicks a link, then nbgitpuller needs to sync updates for the consumer on subsequent link clicks. The nbgitpuller merging strategy makes opinionated choices so that the link consumer never has to interact with git, and will always preserve the consumer’s working changes.

Things can go wrong when

Consumers can diverge the git history if they perform a git commit
Authors can diverge the git history if they perform force push commits

Error UX (old)

Old UX for merge errors.

Problems with the old UX include:

a scary terminal
difficulty for the user to figure out what went wrong
no suggestion for the user to fix the problem or a signpost to continue to the compute platform

Error UX (new)

New UX for merge errors.

New improvements to the UX include:

The terminal is closed by default, but you can optionally toggle it open
There is a copy to clipboard button to easily share the error log from the terminal
A more user-friendly and context-aware helper message is displayed
A link to the general documentation for reference
A ‘Proceed without syncing’ button takes the user to the compute platform without making any changes
In the case of merge errors, an extra Backup and resync button option is presented

Learn more

nbgitpuller documentation

Acknowledgements

UC Berkeley and the CloudBank Classroom project
CAL ICOR for co-funding this development work
Eric Van Dusen and Sean Morris for championing this work
Balaji Alwar for providing the error data and sharing feedback
Nicolas M. Thiéry for feedback on the UX design
cmarmo for contributing the ‘Backup and resync button’

Jupyter Blog - Jenny Wong