nbgitpuller gives a whole class a copy of your materials from one link. A student clicks it, the files land in their own space on the hub, and the notebook you pointed at opens. Nobody needs to know git.
Setting this up takes two things: your materials in a public GitHub repository, and a link that points at them.
Put your materials in a public repo¶
Go to GitHub and choose New.
Start from the New button on your GitHub dashboard.
Pick an owner, which can be your personal account or an organization your course uses, and name the repository. Set Choose visibility to Public, then create it.
Visibility has to be Public for students to pull from the repository.
Add your notebooks and data files with Add file, then Upload files.
Upload your materials into the repository once it exists.
Give some thought to the layout. The Data 8 materials keep hw, lab, lectures, and project at
the top level, with each assignment in its own folder next to the data files it needs.
ucb
A consistent layout pays off later, because it makes your links regular enough to edit by hand.
Generate a link¶
We recommend the DataHub Link Generator Chrome extension. nbgitpuller also publishes a link generator form if you would rather not install anything.
Open the notebook you want students to land on, on GitHub, then click the extension from the puzzle icon in your browser toolbar. It reads the repository, branch, and file path from the page you are looking at.
The extension fills in the repository and file path from whichever page you have open.
Enter your hub address in JupyterHub URL. Hub URL covers where to find yours. Then choose what students should open in.
Five targets are available. Classic Notebook opens the notebook by itself, and JupyterLab opens it with the file browser alongside.
Choose Copy nbgitpuller link and share it however your course reaches students.
Landing students in a folder instead of a notebook¶
Generating the link from a notebook page sends students straight to that notebook. Sometimes you want them in a folder instead — a whole lab with its data files, say, where they pick the file themselves.
Open the folder on GitHub rather than a notebook, then use the extension the same way. It reads the path from whichever page you are on, so a folder page produces a folder link.
If you already have a notebook link, you can shorten it by hand. Delete the file name from the end
of urlpath, leaving the folder:
...&urlpath=tree%2Fmaterials-fds-v2%2Fhw%2Fhw01%2Fhw01.ipynb opens hw01.ipynb
...&urlpath=tree%2Fmaterials-fds-v2%2Fhw%2Fhw01 opens the hw01 folderWhat students see on arrival depends on the target you picked in Open in: JupyterLab shows the folder in the file browser, and Classic Notebook shows a directory listing.
What the link contains¶
A generated link looks like this:
https://datahub.berkeley.edu/hub/user-redirect/git-pull?repo=https%3A%2F%2Fgithub.com%2Fucb-dsus-adopters%2Fmaterials-fds-v2&branch=main&urlpath=tree%2Fmaterials-fds-v2%2Fhw%2Fhw01%2Fhw01.ipynb| Part | What it does |
|---|---|
https://datahub.berkeley.edu | The hub the student is sent to |
/hub/user-redirect/git-pull | Pulls into whichever account is signed in |
repo= | The repository to copy, URL encoded |
branch=main | The branch to pull from |
urlpath= | The file to open once the copy finishes |
The urlpath records where you were when you generated the link, so a link made from HW01 opens
HW01. If your repository has a consistent layout, you can copy a link and change hw01 to hw02
rather than generating a new one.
What happens when a student clicks¶
The whole repository copies into the student’s space, and then the file named in urlpath opens.
They get everything, not just the one notebook, which is why the data files an assignment needs
should sit in the repository beside it.
Where the link above lands. The repository now sits in the student’s own space, and HW01 is open in Classic Notebook, the target chosen when the link was made.
Send the same link again later and nbgitpuller merges rather than overwrites:
Files a student never touched pick up your changes.
Where you both edited the same file in different places, both sets of edits survive.
Where you both changed the same lines, the student’s version wins.
A student who deletes a file gets your copy back on the next click, which is how they start a question over.
If a merge cannot be resolved, their work is copied to a backup folder before the fresh pull, so nothing is lost.
If a link does not behave the way you expect, getting help covers where to ask.
To skip the server options page as well, so students go from the link straight into a running server, see Autostart Links.