Gitlab Tutorial 1. Step-by-Step Guide to Git and Gitlab

Using a UZH Gitlab repository for project owners and collaborators

Gitlab
Basic
Author

G.Fraga Gonzalez & E. Furrer

Published

December 16, 2024

Back

Why is this useful?

Collaborative research requires a version control system for multiple files as researchers need to be able to track changes, to revise change history and to share code, documentation and metadata. Our CRS primer on Digital Collaboration further describes the available tools and their relevance to good research practices.

This tutorial is based on Git as it is the de facto standard set of tools for source control.

Overview

This tutorial is a short step-by-step guide on using Git and Gitlab and provides a workflow to use Github Desktop to sync with local files. For complete beginners we recommend the Git book, which is very accessible but also very detailed. It is available in several languages and as pdf. Another option for beginners are the Gitlab tutorials by Gitlab.com (commercial).

  • Git is a system to track changes in files, it is most often used to coordinate the work among several persons who access the files online on a server or sync them to their computer. The online use does not require any installation, local use is only possible after installing Git.

  • Gitlab.com and Github.com are commercial hosting services for version control with Git. The UZH instance of the open source Gitlab at Gitlab.uzh.ch is hosted by the UZH on servers owned by SWITCH, a non-profit foundation that has been established by the Swiss Federal Government. See https://www.zi.uzh.ch/en/staff/software-elearning/webplatforms/gitlab.html for more information.

  • A Git repository is a set of folders and files with complete history and full version-tracking abilities, locally or on a server.

Workflow

1. Create and use a repository (in browser)

For project owners

For someone that wants to share data or metadata (e.g., a data hub)

  1. Login to Gitlab.uzh.ch with your SWITCH edu-ID.
  2. Create a new project repository, give it an informative, easy name (e.g., _pages, project x)
  3. In Settings/General/Visibility mark it as private
  4. In Manage/Members/Invite members add new members to the team, with different levels of permissions
  5. Add your files and code (works through the browser but is easier with the Gitlab workflow below)

For collaborators

For someone who just wants to navigate through the data of a lab, when this is not made fully public:

  1. Ask the owner of the data to be invited as a member of the project repository
  2. Go to the project repository on Gitlab.uzh.ch or Pages URL e.g., https://crsuzh.pages.uzh.ch/afford_website/ and login with your SWITCH edu-ID (if required).

2. Cloning a repository to local computer

For project owners

Our remote Gitlab repository, which we access via the browser is now our main location of metadata, code and (some) data. But sometimes it is convenient to make our edits locally. Specially if we are data owners and want to edit and share a large number of files or code, we cannot do this easily in the browser. Recall that you need to install Git for this.

In Git, you can clone a repository to create a copy on your computer, that will be synchronized with your remote repository. Once cloned we can pull changes done in the remote repository (in the browser). If we have local changes and want to ‘send’ them to the remote we do: 1) commit and 2) push the local changes to remote. (??? what about add?)

NOTE: if we fork a repository instead of cloning it, this will create a completely independent copy of the Git repository. Here, we need cloning so that our local changes can be synchronized and we don’t create duplicates of the repository.

Personal access token

To clone a repository to your machine you will most likely need a personal access token (due to the security of SWITCH login). In your project repository on Gitlab.uzh.ch go to Settings/Access tokens. In the Access Tokens menu you will be able to give the token a name, choose an expiration date (or leave it blank), choose permissions (choose at least developer for making edits) and scope (select API). See also the picture below.

image

After this you will see a long alphanumeric string, the token, that you should save somewhere so you can use it as your password later on when using Github-desktop, Git or any other platform to manage local copies of the repositories.

2.1 Cloning with Github-desktop (user-friendly)

The open source tool Github-desktop with a graphical user interface will simplify pull, commit, push operations for both advanced as well as new users. !Note: official support seems to be only for Windows and Mac. See further documentation on integration with Gitlab

Setup of Github-desktop for Gitlab

  1. Download and install Github desktop

  2. In your Gitlab project, get your personal access token (see above) and save it somewhere

  3. On Github desktop go to File/Clone repository. Then enter the URL of your Gitlab repository (see the clone button) and a local directory name. For example:

    image.png

  4. Then you will be asked for username and password. Your username is your Gitlab username (e.g., the name in your email address) and the password is the Token that you just created.

Now your Local folder is linked to your Gitlab remote repository. You can check below how to pull, commit and push changes.

Editing repository

Pull,commit and Push changes in the content of the repository. The workflow can get quite complex. Here we will ignore elements like branches to oversimplify it into the main steps:

  1. Work on your local repository, for example, create or edit code, update your metadata table, add new files [^1]
  2. Open Github desktop. If you have several repositories, make sure you select the one you are currently working on or the one you want to update. It should detect the local changes done. If there are changes done remotely, but not locally, it willl prompt you to pull those changes (but here, beware there may be conflicts, which you shold be able to solve with Github but may complicate things).
  3. Click Commit ( you will need to write a brief description, e.g., ‘updated figures’). This will prepare your changes to be sent to the remote repository (‘origin’). If you edited multiple scripts, you can commit all changes at once or select specific scripts
  4. Click push to origin so that the changes are uploaded.

[^1]: Gitlab is not intended as a large data storage. For the pages in this example we need to have the pictures we want to render in the repository. But sometimes we have many files in our local repository that we do not want to push to the online repository. For that we can use a plain text file in that directory and call it .gitignore. In that file we can have statements like ‘*.jpg’. Then Git will ignore all jpg files in the folder when pushing.

2.2 Cloning with Git (using command line)

Git refers to this version control system used in Gitlab, but you can also manage the repositories locally downloading the program Git SCM, a free and open source distributed version control system. It is light and works across operating systems, and also has a very basic graphical interface. But it is mostly designed for working through a terminal. As in Github-desktop you use this to do the main Git actions of pulling, committing and pushing changes between local and remote repositories.

Back to top