.. _topic/automatic-merging:

==========================
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
repository.

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
homework.

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*
named ``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
``Untitled141.ipynb``.

This is a fairly rare case in our experience.