GitLab

How to use the OxCIN GitLab instance for your code and documentation

gitlab-logo

Introduction

Programming is an iterative process, and a script used for stimulus presentation or data analysis will have dozens or hundreds of changes applied to it, sometimes over many years. As projects become more complex, it inevitably becomes necessary to keep track of the changes which have been made to each file over time, for a number of reasons:

  • Researchers may need to roll back a change which has been made to the code, e.g., because it introduced a bug.
  • Researchers frequently share code with collaborators. These collaborators usually make modifications for their specific use-case, resulting in multiple, diverging versions of the same code. This can become confusing if changes are not adequately tracked.

Less experienced programmers frequently attempt to deal with this problem by making backups of a file, sometimes with a timestamp or version number appended to the filename of a script or folder. This is better than nothing, but falls apart in complex cases:

  • What happens if someone made a mistake when modifying a file, but this was not discovered until many changes had been applied on top of it?
  • When a researcher shares code with a collaborator, how might they update their own modified version of the code with improvements or bug-fixes made by their the person who originally wrote the code?

If your only way of tracking changes is via timestamped backups of files, resolving these issues requires extensive manual editing, which is unwieldy and error-prone. The solution is to use a version-control system (VCS). Modern version control systems store a complete, line-by-line history of the entire codebase allowing programmers to pinpoint exactly when a change was made, and revert it, without affecting any subsequent changes. They also facilitate collaboration by allowing changes to be automatically “merged” in from a diverging codebase, without overwriting local changes.

Git is by far the most popular VCS in the world. Git is a distributed version control system, meaning that each person working on a project has a local copy of the code (and its complete history) stored in a directory called a repository. When a programmer makes changes to the codebase, they record them by commiting their changes to their Git repository. They can then synchronise these changes with a remote repository. Other programmers can download (fetch) these changes, and merge them into their own local copy.

For more information on Git, and why it has become the industry standard for version control, check out the Pro Git Book – available for free on Git’s official website. This is a excellent resource for beginners and experienced users alike.

Overview

Git is a service which allows version control of material and syncing between local (on your computer) and remote (on a server, accessible through a web browser) versions of material. These remote and local versions are useful for backup and collaboration, where different users can access the same remote content.

OxCIN provide a git service using the open source GitLab software. We have installed GitLab on our internal servers, so you can use it to maintain your material in a space where we have complete control over who can access it.

GitLab is best used for the management of text-based documents with some pictures (not nifti brain images!). This mainly covers code and documentation. It is also useful for project management by logging issues and milestones, and tracking collaboration.

GitLab Demystified!

This 30 min presentation introduces GitLab and version control. It explains key terminology, demonstrates basic interaction with a repository, and showcases the potential of GitLab Pages. After watching this presentation, GitLab might feel a bit less intimidating!

Benefits

Version control version-control

GitLab manages your version control. This means that each change you make to the remote repository is tracked and can be reversed. This is helpful for undoing changes (you can revert to earlier points in time) and tracking who has made changes on a collaborative project.

Citable research output doi

Your gitlab repository can be assigned a digital object identifier (doi). This means everything containing within your repository can be cited as a research output, be it code or documentation. Find out how to create a doi for your repository.

Managed and attributable collaboration

Git and GitLab are an excellent resource for inviting others to contribute to your material. Potential collaborators can be internal to OxCIN or external. Changes can be incorporated automatically if the collaborator is trusted and known to you (invited directly), or suggested via a “merge request” if the collaborator is not part of your invited group. This process also makes it very easy to follow who has made what contribution, so they can be appropriately attributed for their efforts.

GitLab pages

GitLab pages allows you to build professional looking websites, like this one! It is relatively straightforward to build a simple website to share your work with the world, and the options for building in additional complexity are endless. Take a look at this tutorial for building a GitLab pages site.

Getting started

If you’re new to GitLab, we suggest you take a look a the tutorials and find the appropriate jumping off point for your experience.

How to access GitLab after leaving OxCIN

Contact the OxCIN IT for external access! Our IT team

Table of contents