Automatic Merging Behavior#
nbgitpuller tries to make sure the end user who clicked the link
never has to manually interact with the git repo. This requires us to
make some opinionated choices on how we handle various cases where both the
student (end user) and instructor (author of the repo) repo have modified the
Here, we describe how we handle the various possible cases each time the student clicks the nbgitpuller link.
Case 1: The instructor changed a file that the student has not changed#
The student’s changes are left alone, and the instructor’s changes are pulled in to the local copy. Most common case. This is also what happens when the instructor adds a new file / directory.
Case 2: Student & instructor changed different lines in same file#
Very similar to case 1 - the student’s changes are left alone, and the instructor’s changes are merged in to the existing local file.
Case 3: Student & instructor change same lines in same file#
In this case, we always keep the student’s changes. We want to never
accidentally lose a student’s changes -
nbgitpuller will not eat your
Case 4: Student deletes file locally, but instructor doesn’t#
If the student has deleted a file locally, but the file is still present in the remote repo, the file from the remote repo is pulled into the student’s directory. This enables the use case where a student wants to ‘start over’ a file after having made many changes to it. They can simply delete the file, click the nbgitpuller link again, and get a fresh copy.
Case 5: Student creates file manually, but instructor adds file with same name#
As an example, let’s say the student manually creates a file named
Untitled141.ipynb in the directory where nbgitpuller has pulled a
repository. At some point afterwards, the instructor creates a file also
Untitled141.ipynb and pushes it to the repo.
When the student clicks the nbgitpuller link next, we want to make sure we
don’t destroy the student’s work. Since they were created in two different
places, the likelihood of them being mergeable is low. So we rename the
student’s file, and pull the instructor’s file. So the student’s
Untitled141.ipynb file will be renamed to
Untitled141_<timestamp>.ipynb, and the instructor’s file will be kept at
This is a fairly rare case in our experience.