Exercise 1: Git & GitLab

You’ll need to use the Git version control system in some of the work for COMP5911M. You’ll also need to use GitLab, a service that hosts Git repositories in the cloud and offers other useful features such as issue tracking, wikis and continuous integration.

This exercise will help you get ready to use Git and GitLab. You may be able to skip some, or even most, of the work here, depending on your prior experience with these tools.

Setting Up Git

  1. If you don’t already have Git on your own PC, install it there. If you are running Linux or Windows Subsystem for Linux (WSL), use your Linux distribution’s standard software package manager to do this. If you have a Mac, Git should already be available to you. If you are running Windows, you can get a suitable Git environment from the Git for Windows site.

  2. Git is already available on the School of Computing’s Linux machines, but the default version (1.8.3) is rather old. If you’d like to use a newer version (e.g., for greater consistency with the set-up on your own PC) then use the following command before running any Git commands on SoC machines:

    module add git/2.9.5

    Normally, this command must be used every time that you start up a terminal window. Since this can become tedious and is easily forgotten, you can put the command in the configuration file .bashrc, located in your home directory; that way, it will be run automatically every time you start a new shell.

  3. IMPORTANT: Make sure that you configure your identity properly on all machines from which you intend to use Git. To check this, use the following command:

    git config --global --list

    The value of user.name should be your real name and the value of user.email should be your university email address. If they don’t have the correct values, you can change them with commands like this:

    git config --global user.name "Charles Xavier"
    git config --global user.email sc99cx@leeds.ac.uk

    Don’t forget the --global option here!1.

  4. If you are not very familiar with Git, or need a refresher in how to use it, the following resources may help:

Setting Up GitLab

  1. If you already have an account on gitlab.com, go to the sign-in page and log in. Go to account settings and make sure that the email address setting is your university email address, in lowercase. Then go to Step 3 below.

  2. If you don’t already have an account on gitlab.com, go to the sign-in page, click the Register tab and fill in the form. Make sure you put your real name in the ‘Full name’ field and your university email address, in lowercase, in the ‘Email’ field.

    Screenshot showing the GitLab account registration UI

    Creating a GitLab account

  3. Click on the user icon at the top-right of the screen, then click on the Settings link in the drop-down menu. On the Settings page, click on the SSH Keys link from the toolbar on the left. This will show you if you have any SSH keys already set up in your GitLab account. If do you have an SSH key already set up in your GitLab account, you can skip the remainder of this section and go straight to the Checking Your Repository section below.

  4. If you have already generated an SSH key pair on the machine that you are currently using, find the public key. Normally, this will be in the directory ~/.ssh, as a file with a .pub extension. Open this file in a text editor and copy its entire contents. Paste the file contents into the input area provided on the SSH Keys page, then click the Add Key button. Then move on to the Checking Your Repository section.

  5. If you’ve got to this point, then you presumably do NOT already have an SSH key pair, and you will therefore need to generate one. You can achieve this using the following command:

    ssh-keygen -t ed25519 -C "COMMENT TEXT"

    Supply some suitable descriptive text in place of COMMENT TEXT in the above. Something that identifies the machine you are using would be a good choice – e.g., “My laptop” or “School of Computing”.

    When prompted to enter a file path for the key, press Enter to accept the default value.

    Provide an appropriate passphrase when prompted to do so – i.e., don’t just press Enter. Choose something secure that you will be able to remember. Note that you won’t see anything echoed on the screen as you type your passphrase.

    After the key pair has been generated, open the file ~/.ssh/id_ed25519.pub in a text editor. Copy the entire contents of the file and paste them into the area provided on the SSH Keys page on gitlab.com.

  6. If necessary, repeat the previous step so that you have separate key pairs on your PC and SoC Linux machines, with the public keys uploaded to gitlab.com. Use the same passphrase for both2.

Checking Your Repository

Before you can proceed with checking your repository, you will need to wait for us to connect your GitLab project area to your GitLab account. Ask for help if you don’t see the project area when you login to gitlab.com.

  1. Open a terminal window, cd to a directory where you want to store your work and then create a local clone of the GitLab repository by entering a command like this:

    git clone git@gitlab.com:comp5911m/21/USERNAME.git comp5911m

    Substitute your university username for USERNAME in the above command - don’t use your GitLab username here.

    The comp5911m appearing at the end of this command is the name of the directory that will be created on the machine where you are executing the command. You can use a different directory name if you prefer (but make sure that it doesn’t include spaces).

    If you’ve set up an SSH key correctly, you will be prompted to enter the SSH passphrase that you specified when creating the key pair. Subsequent uses of Git commands that interact with the remote repository will not require you to reenter your passphrase, at least until your next login.

  2. Move into the newly-created directory and examine it. You should see a file named README.md, containing some instructions on how to use the repository.

  3. Open README.md in your favourite text editor. Remove the line at the bottom that starts DELETE THIS LINE. Save the file.

  4. Use the git status command to check repository status. It should tell you that README.md has been modified. Use the git diff command to see what’s been changed.

  5. Stage and commit the changes with these commands:

    git add README.md
    git commit -m "Edited README file"
  6. Use git log to view the history of commits. Make sure that the most recent commit identifies you correctly, giving your name and university email address. If not, perform the Git configuration steps described in the Setting up Git section.

  7. Push the changes up to GitLab like so:

    git push origin main

    (Note: on recent versions of Git, you can abbreviate this to git push.)

  8. Visit your project area on gitlab.com and check that the commit has appeared there.

Using The Wiki

Your GitLab project area has a wiki that sits alongside your repository. You can create pages in the wiki easily using a lightweight syntax called Markdown.

  1. If you are not already familiar with Markdown, read up on the CommonMark specification and GitLab-Flavored Markdown (GFM). This will give you all the information you need about how to write wiki pages.

  2. Log in to your GitLab account and access your project. Click on the Wiki button in the toolbar of the left of the screen to access the associated wiki. Create a simple page in your wiki. Experiment with Markdown syntax, creating titles and subtitles, different types of text emphasis, hyperlinks, etc.

  1. If you already have a globally configured Git identity that you don’t want to change, you can configure your identity locally, in an individual Git repository, by using the same Git commands but without the --global option. ↩︎

  2. Although slightly less secure, this will be considerably more convenient than having to remember different passphrases depending on where you are using Git. ↩︎