If you can already use git, read this first

If you have experience of using git, or other similar version control, then you can skim through most of this page. Some highlights are included at the top here that you need to make sure you have done, so that you can fully engage with the module.

1. You will need access to CS GitLab! You should sign-in to the CS GitLab server to activate your account. If you receive any kind of error message, fill in this form.
2. Skeleton code is provided on this GitHub page, so you'll need to clone it
3. Submission code goes onto the CS GitLab, where you will be assigned a team repository

If you need more detail about any of those steps, you can find it on this page.

What is git?

Git is a version control tool: it allows you to track changes to your code and collaborate with team-mates. We will be using the CS GitLab server, which is where you will store your code so you can access it outside of the lab (using git). This page will take you through the git basics you will need to complete this course, although there is further reading at the end of the page if you want to improve your git skills.

We will go through the following skills:

1. Cloning a git repository
2. Making a new repository in GitLab
3. Linking the repository on the machine (local) to your GitLab repository (remote)
4. Committing code changes to the repository

Git is installed on all lab machines in CS, including in B85. You may wish to install git on your personal machine so you can work on your code outside of the lab. You should follow the install instructions on the git website.

There a few similarly-named tools that we'll be using and talking about in this tutorial, so you may find these definitions handy:

• git is the name of the version control tool itself. It's what provides you with the git commands we'll be using.
• GitHub is the name of the website that the COMP4034 tutorials are hosted on (this website!). It is a website that implements git protocols and provides repositories. We will use GitHub as a student-facing interface, however you will not store your code in private GitHub accounts. Instead you will use GitLab (see below).
• GitLab is the Computer Science internal git server. It's like GitHub, but private and accessible only to CS staff and students. You will be given a team space where you can create a repository for your code.

Cloning a git repository

Before you start: we will be using the Linux command line during this module. If you are not familiar with the command line, you can find resources at the bottom of this tutorial to help you - as you work through the tutorial, make sure to look up any commands you're not familiar with.

The first step when working with git is often to use git clone. This creates a copy of a remote (on the Internet) repository on your local machine. Follow these steps to get a copy of the COMP4034 code onto your machine:

1. Open a terminal window (you can find the terminal by clicking the grid of 9 dots in the bottom left of the screen)
2. You need to move into the directory where you want the code to go. This will be inside the src folder of your ROS2 workspace. In the terminal, type cd ~/[ROS2_ws]/src/ and press the Enter key
3. Now in the terminal, type git clone https://github.com/RobotTeaching/COMP4034.git and press Enter

Congratulations! You have successfully cloned the code from our GitHub onto your local machine. This is a good opportunity to practice your command line skills ;) try exploring your newly-downloaded repository using cd to change directories and ls to list directory contents.

Making a new repository in CS GitLab

STOP! Before you complete this section you will need access to CS GitLab! You should sign-in to GitLab to activate your account. If you receive any kind of error message, fill in this form. We will be assigning GitLab projects to teams later in the term, but to complete this section just work on your personal account.

1. The first thing you need to do is create a new project. From the left side panel choose "Projects", and then click the "New project" button in the top right corner of the screen.
2. Select "Create blank project"
3. Name the project something sensible (like "COMP4034 git basics")
4. In the "group or namespace" drop-down, select your username
5. Leave the rest of the settings as they are, and click "create project"

Move into that project. A readme will have been created with some instructions in, under the heading "Add your files". Let's explore what each of these commands do before we run them.

cd existing_repo: cd means "change directory", and you will need to replace "existing_repo" with the name of the repository you cloned previously.

git remote add origin [url]: this runs the git command "add origin". The origin, or the source code, is what is on your machine. The "remote" part lets git know we're adding a new remote location (i.e. GitLab, a location on the Internet).

git branch -M main: git has a branching structure, which you can learn more about from the resources below - but for now, you just need to understand that this command sets git to the main version of the code.

git push -uf origin main: "git push" is the command used to move code from your local repository to your remote repository, and this command puts the code in the "main" branch. You can find out more about the "-uf" flag in the resources at the end of this page.

Allowing force push

Before we can work with our GitLab repository, we need to enable the "Allow force push" setting. In the project, go to "Settings > Branch Rules" and click "View details" next to the main branch. Toggle the switch to allow force push.

Using an access token as a password

We also need to set up an access token for security. Click your user icon (top right of the side panel) then click "Edit profile". This gives you a new side bar. Click "Access tokens" in that side bar, then "Add new token" in the top left. Your token needs a name, and you need to check the "read_repository" and "write_repository" scopes. Then click "create token".

Important: you will only be shown your access token once! Keep it somewhere safe, e.g. on your phone. You can issue a new token if you lose it, but you'll need to repeat the above steps.

Using our git repositories

Note: We will be maintaining 2 git repositories for this course. The first one you've already created, and that's where you will get code from our GitHub page (referred to here as "lab code"). The second will be the one you put your code into for pushing to GitLab (called "submission code". There is a workflow below in case you get confused.

Note: If you run into permissions issues when trying to do this in Docker, make sure you are in the right folder. You can only git init inside the src folder.

1. The first thing to do is create a new folder inside ~/ros2_ws/src/ for your submission code
2. Copy the minitask_ folders from the lab code folder into your submission code folder
3. Open your submission code folder in the terminal (you can right-click in the window, then "Open in terminal")
4. Run the command git init. This creates a new git repository in your submission code folder
5. Run the command git remote add origin https://projects.cs.nott.ac.uk/[your_repo].git (copy it from the readme on GitLab to avoid mistakes)
6. Run git branch -M main
7. Run git add -A: this adds all new file in the git repo to the next commit
8. Run git commit -m "First commit" to add a commit message to the next commit
9. Run git push -uf origin main
   • This will ask for your username, which is your IT username (the start of your university email)
   • The password is the access token we created earlier

You should get a message ending with "Branch 'main' set up to track remote branch 'main' from 'origin'" if your commit was successful; congratulations!

Git workflow

Useful links

Download git and access git tutorials

Git cheat sheet

Ubuntu terminal tutorial

Linux command line cheat sheet