Using the Revision Control Mechanism extension

The Revision Control Mechanism (RCM) Jupyter Notebook extension provides simple version control for notebook files. It uses the internal Jupyter functionality to perform tasks.

On the surface, RCM uses a simple linear model, but beneath that is a more complex git-based branching model. To prevent merge conflicts, this model uses a “latest wins” policy as its main merging strategy.

The RCM Jupyter Notebook extension adds four buttons:

../../../../../../_images/aen-user-extensions_rcm.png

TIP: If you do not see the RCM buttons, see Setting up RCM for the first time.

Using the Status button

The Status button allows you to see what revision you are on.

Clicking the Status button displays:

../../../../../../_images/aen-user-extensions_rcm_status.png

Using the Checkout button

The Checkout button allows you to view a list of the previous revision points, check out a previous revision or compare differences between revisions.

Clicking the Checkout button displays:

../../../../../../_images/aen-user-extensions_rcm_checkout.png

Checking out a previous revision

To checkout a notebook at an earlier revision point:

  1. Select the checkbox next to the desired revision point.

  2. Click the OK button.

    A copy of the notebook at the selected revision point is displayed.

NOTE: If you have not saved the work in your current project window, checking out a previous revision destroys it. If in doubt, click the Cancel button and save your work before reverting to a previous revision point.

Comparing revisions

To compare 2 previous revision points:

  1. Select the checkboxes of the revision points to compare.

  2. Click the View Diff button.

    A side-by-side comparison is displayed.

    Click the Cancel button to close the differences window.

Using the Commit button

The Commit button allows you to save or persist the current changes, keeping a permanent record of any changes that are introduced, so that you do not have to worry about losing important data.

Clicking the Commit button displays:

../../../../../../_images/aen-user-extensions_rcm_commit.png

  1. Enter a description of the changes in the commit as a reminder in case you need to revert back to it later.

  2. Click the OK button.

    Your changes are committed and a revision point is created.

If Git user name and user email are not set, the following window appears:

../../../../../../_images/aen-user-extensions_rcm_commit_error.png

Configure Git and then try to commit again.

TIP: You can roll back committed changes by checking out a previous version.

Using the Configure git button

The Configure git button allows you to configure Git user name and email values.

After clicking the Configure Git button, the following window appears:

../../../../../../_images/aen-user-extensions_rcm_git_config.png

Enter user name and e-mail address. Click the OK button when finished.

Setting up RCM for the first time

If you do not see the RCM buttons in your notebook:

  1. Go to the project home page.

  2. Open the Terminal application.

  3. In the terminal window, run:

    git config --global user.email "you@example.com"
    git config --global user.name "Your Name"
    

    NOTE: Change you@example.com to your email address, and Your Name to your actual name.

  4. Open Jupyter Notebook and refresh the page.