Git

Prerequisite¶

• Git - Version control systems that allow you to track changes to your files.

• ASF’s Jupyter Notebook - A collection of Jupyter Notebooks used in OpenScienceLab.

• Terminal - A built-in terminal within OpenScienceLab. The user should also have a basic understanding of Bash commands.

Gitpuller¶

nbgitpuller pulls any changes to your tracked notebook repositories through a jupyter extension nbgitpuller-jl-interface.

The nbgitpuller-jl-interface extension will check for any pending updates and alert you to it’s status.

• Green: Everything is up to date

• Orange: One or more repositories need to be updated, click the button to pull the updates

• Red: An error has occured. Either double check your extensions settings, the failed repository, or contact the site admins.

Gitpuller Merge Conflicts¶

If a user has made changes to a notebook and the same notebook has been updated in its repo, the following will occur:

Users will retain two copies of the same notebook.

• The user-edited notebook will have a timestamp appended to its name.

• The notebook with the original name will contain the new changes made by ASF.

Example:

Before Edit

• Original version: sample_notebook.ipynb

After Edit

• Updated by user: sample_notebook__20210616165846.ipynb

• Updated by ASF: sample_notebook.ipynb

You can read more about the merging behavior of nbgitpuller here

In the case of a broken Git state¶

Due to its complexity, it is common for users to break Git workflow. A broken Git state can lead to unexpected results, such as notebooks not being updated.

Below are the steps users can take if the Git workflow is in a state beyond their ability to repair.

Repair Process:

1. Preserve any files/directories you wish to keep under the /home/jovyan/notebooks directory.

   • Either *download or move out items you wish to keep.

2. Delete the entire /home/jovyan/notebooks directory.

   • Use rm -rf /home/jovyan/notebooks on the terminal to delete all.

3. Restart your server.

4. Gitpuller will automatically clone a clean repository into your account.

*NB: When downloading a directory, users may compress them first to optimize downloading. The below commands will allow users to (de)compress files/directories:

• Compress: zip -r <name>.zip <directory>

• Decompress: unzip <name>.zip

Where <name> can be anything you wish.

Using Other Git Repos in OpenScienceLab¶

If you wish to utilize repositories other than those hosted by ASF, you can clone them into your OpenScienceLab account. However, users will need to manage the repos that they clone to prevent any issues.

When cloning a repository from elsewhere, users must ensure not to nest git repositories, i.e., do not clone a repository within another repository.

To avoid complications, clone your repos to /home/jovyan.