1. Setting up Version Control

This worksheet covers the tasks you need to carry out in preparation for doing the exercises and coursework for COMP1721.

1.1. Configuring Git

  1. Make sure Git is installed on your own PC. Use your Linux distribution’s package manager to install it if necessary. If you have a Mac, you can download an official Mac build from the Git project, or install it using Homebrew. If you are wedded to Microsoft Windows, there is a Git for Windows distribution available that should be suitable.

  2. If you wish, configure a more recent version of Git to use on SoC Linux machines. The standard system version provided on these machines is at least 5 years old, but you can make a more recent version available using the following command:

    module add git/2.9.5
    

    You make this permanent by adding this command to the end of your ~/.bashrc file; otherwise, you’ll need to enter it at the start of every terminal window session.

  3. IMPORTANT: If you haven’t already configured Git with your identity, do so now using commands like the following in a terminal window (substituting your actual name and university email address, obviously):

    git config --global user.name "Jane Smith"
    git config --global user.email jane@example.com
    

    Do this on a SoC Linux machine and on your own PC, so that authorship of your future Git commits is recorded consistently.

1.2. Working With GitLab

  1. If you already have an account on gitlab.com, you can skip to Step 2 below.

    If you haven’t yet created an account, do so now by visiting https://gitlab.com/users/sign_in#register-pane in a web browser.

    ../_images/register.png

    Note

    Please be sure to use your real name and your university email address when registering, and make sure that your email address has been entered in lowercase - see the example above.

    If you don’t use your university email address, we will not be able to link your GitLab account to the repository that we have created for you!

    Once you have successfully created the account, notify me - either directly in a lab session or by via email. You will then need to wait for me to link your account with the GitLab repository that we’ve set up for you.

  2. When your GitLab account has been linked with your repository, you will receive notification from gitlab.com via email.

    Use the link provided in the email message to log in to your GitLab account. You should see a list of your GitLab ‘projects’. Click on the link for COMP1721 and you should see a screen that looks similar to this:

    ../_images/project.png

    Click on the files and directories listed in your repository to examine their contents. Note that there are separate directories for each piece of coursework, and also separate directories for each set of exercises.

    This directory tree was set up for you via a single commit. Find the Repository menu in the list of options on the left of the screen, then use the Commits link in this menu to examine this commit.

  3. The next step is to add an SSH key. You can skip to Step 4 below if you have already done this.

    To add the key, 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 that appears in the menu on the left.

    If you already have an SSH key pair, paste the public key data into the Key area and click the green Add key button. If you don’t have a key pair already, click on the generate one link for instructions on how to create it. Note: when running ssh-keygen, accept the suggested defaults for key filename and location.

    If doing this on SoC Linux machines, ignore the suggestion made in the GitLab help about using xclip to copy the public key; instead, just open ~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub in a text editor such as Atom and then copy and paste the public key data from there into the Key area in GitLab.

    Note

    Adding an SSH key isn’t strictly necessary, but if you don’t do this then you will need to supply your GitLab password on every clone, push or pull operation, which quickly becomes very tedious!

    When you generate a key pair, be sure to choose an SSH passphrase that you will remember. It is best not to use any of your existing passwords for this.

    If you intend working from your own PC as well as SoC Linux machines, generate separate key pairs on each, using the same passphrase for both. Then upload the public keys for both to GitLab.

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

    git clone git@gitlab.com:comp1721/20/username.git comp1721
    

    Substitute your actual University of Leeds username for username in the above command.

    The comp1721 appearing at the end of this command is the name of the directory that Git will create to hold your cloned repository. Use a different name for this directory if you like (but make sure 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 1. 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.

  5. Move into the newly created directory and examine it. You should see a file named README.md, shell scripts named finished & notfinished, and subdirectories cwk1, cwk2 and exercises.

    Warning

    Do NOT use the git init command inside your repository! It has already been initalised for you. Running this command again may cause problems.

    Also, do not rename or move the directories or the README.md file, and do not move or modify the finished and notfinished shell scripts.

    Make sure that you store your work in the right place. All of your exercise solutions should go in the appropriate subdirectories of exercises, your files for Coursework 1 should go in cwk1, etc.

  6. Make sure that you’ve cloned the repository onto your own PC as well as into your SoC Linux filestore. This will give you the flexibility to be able to work either at home or in the School.

    Note that you’ll only need to use the clone command once on SoC Linux machines and once on your own PC (unless you remove the local repository for some reason). Subsequent interaction with the GitLab repository will involve the push and pull commands.

  7. Do one of the exercises from Set 1, on a SoC Linux machine. Make sure that you put the .java file in the exercises/set1 directory. Use Git’s add and commit commands to commit your exercise solution to the local repository.

    Next, use the following command to push your commit up to GitLab:

    git push origin master
    
  8. Wait a few seconds, then view your GitLab project again in a web browser. Use the Files and Commits links from the Repository menu to verify that your exercise solution is stored correctly in the remote repository.

  9. Finally, go to local repository on your own PC and use this command:

    git pull origin master
    

    Check that this has transferred your work successfully from GitLab to your own PC.

Footnotes

1

If this doesn’t work, run the ssh-add command, then try again.